Markus Zapke-Gründemann avatar Markus Zapke-Gründemann committed d01ac56

Restructured and updated documentation.

Comments (0)

Files changed (5)

 .. -*- restructuredtext -*-
 
 Changelog
-*********
+=========
+
+1.2.0
+-----
+
+- First Open Source release!
+- Added testedwith variable
+- Test suite works now with Mercurial 2.2.x
+- Added installation instructions and example to README
+- Moved development information to README
 
 1.1.0
-=====
+-----
 
 - Symlinks are no longer dereferenced on Linux (but still dereferenced on
   Windows).
   without write permissions and Mercurial fails to update them.
 
 1.0.1
-=====
+-----
 
 - Write warnings on ignored copy errors to stdout instead of stderr.
 - Using a slash as new exclude pattern separator.
 
 1.0
-===
+---
 
 - Added new options exclude and ignore-copy-errors.
 
 0.9
-===
+---
 
 - Allow to create anonymous branches.
 
 0.8.1
-=====
+-----
 
 - Fixed the problem with wrong permissons of single files in the root of the
-repo on Windows.
+  repo on Windows.
 
 0.8
-===
+---
 
 - Changed filesystem operations to be OS independent. Extension can now be used on Windows.
 - SOURCE can now be a list of directories.
 
 0.7.1
-=====
+-----
 
 - Fixed the version number (which was still 0.6 for the 0.7 release).
 
 0.7
-===
+---
 
 - Removed the "dereference" option.
 
 0.6
-===
+---
 
 - Fixed missing updates. The repository wasn't always at the lastest revision
   when doing the import.
 - Added new option "dereference" to follow symlinks.
- -Updated package classifiers.
+- Updated package classifiers.
 - Added this Changelog.
 - Added long_description to package metadata.
 
 0.5.1
-=====
+-----
 
 - Removed importfs.py from MANIFEST.in.
 
 0.5
-===
+---
 
 - Initial release.

DEVELOPMENT

-.. -*- restructuredtext -*-
-
-How to set up an development environment for importfs
-*****************************************************
-
-If you havn't created a clone of the importfs repository yet do it now::
-
-  $ hg clone https://mts.lantiq.com/~admhg/repo/importfs
-
-Setup a virtualenv
-==================
-
-The best way to do the development is to use a virtualenv_. So first create
-one using virtualenvwrapper_::
-
-  $ mkvirtualenv --no-site-packages --distribute importfs
-
-Then install all packages needed for development into the virtualenv using pip_::
-
-  (importfs)$ cd importfs
-  (importfs)$ pip install -r requirements-dev.txt
-
-You also need a clone of the hg-stable repository::
-
-  (importfs)$ cd ..
-  (importfs)$ hg clone https://mts.lantiq.com/~admhg/repo/hg-stable
-
-Update to your desired version (if you don't want to use *tip*) and build for
-local use::
-
-  (importfs)$ cd hg-stable
-  (importfs)$ hg up VERSION
-  (importfs)$ make local
-
-After creating the clone create a few symlinks in your importfs repository::
-
-  (importfs)$ cd ../importfs
-  (importfs)$ ln -s ../hg-stable/contrib/pylintrc
-  (importfs)$ ln -s ../hg-stable/tests/hghave
-  (importfs)$ ln -s ../hg-stable/tests/run-tests.py
-
-At least add hg-stable to your virtualenv::
-
-  (importfs)$ add2virtualenv ../hg-stable
-
-Run the tests
-=============
-
-To run all tests you can now execute the following command::
-
-  (importfs)$ ./run-tests.py
-
-Create a new source distribution package
-========================================
-
-A new Python source distribution package can be created using this command::
-
-  (importfs)$ python setup.py sdist
-
-.. _virtualenv: http://pypi.python.org/pypi/virtualenv
-.. _virtualenvwrapper: http://pypi.python.org/pypi/virtualenvwrapper
-.. _pip: http://pypi.python.org/pypi/pip
 .. -*- restructuredtext -*-
 
+##################
 importfs extension
-******************
+##################
 
 Imports a set of files from a given file-system into a Mercurial
 repository as a changeset.
+
+The development of this extension was paid for by `Lantiq`_. It was
+written and released as Open Source by `Markus Zapke-Gründemann`_.
+
+Installation
+============
+
+As a Python package
+-------------------
+
+The easiest way is to install the importfs extension is to use `pip`_::
+
+    $ pip install hg-importfs
+
+Using easy_install instead of pip is also possible::
+
+    $ easy_install hg-importfs
+
+Now add the extension to the extensions section in your
+``.hgrc``/``mercurial.ini`` file::
+
+    [extensions]
+    importfs =
+
+As a Mercurial repository
+-------------------------
+
+Instead of installing the Python package you can also clone the repository::
+
+    $ hg clone https://bitbucket.org/keimlink/hg-importfs
+
+To activate the extension you have to add the full path to
+``importfs.py`` to your ``.hgrc``/``mercurial.ini`` file::
+
+    [extensions]
+    importfs = /path/to/hg-importfs/importfs.py
+
+Usage
+=====
+
+Use the following command to show the full help with all options::
+
+    $ hg help importfs
+
+Example
+=======
+
+Assuming you have a project on your file system which has different
+versions in different directories. Maybe because you never used a
+version control system (VCS) for your project. Or maybe because there is
+no convert extension available for the VCS you are using. In our
+scenario the three versions of the project look like this::
+
+    .
+    ├── myproject-v1
+    │   ├── LICENSE
+    │   ├── README
+    │   ├── doc
+    │   │   ├── index.rst
+    │   │   ├── start.rst
+    │   │   └── widgets.rst
+    │   └── src
+    │       ├── cmdutils.py
+    │       ├── dispatcher.py
+    │       └── widgets.py
+    ├── myproject-v2
+    │   ├── LICENSE
+    │   ├── README
+    │   ├── doc
+    │   │   ├── index.rst
+    │   │   ├── start.rst
+    │   │   └── widgets.rst
+    │   └── src
+    │       ├── cmdutils.py
+    │       ├── dispatcher.py
+    │       ├── resources.py
+    │       └── widgets.py
+    └── myproject-v3
+        ├── LICENSE
+        ├── README
+        ├── doc
+        │   ├── index.rst
+        │   ├── start.rst
+        │   └── widgets.rst
+        └── src
+            ├── dispatcher.py
+            ├── resources.py
+            └── widgets.py
+
+Run the following command to import the first version of the project
+into a Mercurial repository ``myrepo``. The repository does not exist so
+it will be created for you::
+
+    $ hg importfs myrepo myproject-v1
+    created repository myrepo
+    0 files updated, 0 files merged, 0 files removed, 0 files unresolved
+    adding LICENSE
+    adding README
+    adding doc/index.rst
+    adding doc/start.rst
+    adding doc/widgets.rst
+    adding src/cmdutils.py
+    adding src/dispatcher.py
+    adding src/widgets.py
+
+Now you have a repository with one changeset. This changeset contains
+all your files from ``myproject-v1``.
+
+::
+
+    $ hg log -R myrepo
+    changeset:   0:60304fa41a49
+    tag:         tip
+    user:        Markus Zapke-Gründemann <markus@keimlink.de>
+    date:        Tue Jul 10 10:19:10 2012 +0200
+    summary:     importfs commit.
+
+As you can see importfs created a commit message for you because you
+didn't specify one for the first import.
+
+The second import will put all the files from ``myproject-v2`` as a new
+changeset on top of changeset 0. And this time we want to use our own
+commit message and tag the changeset::
+
+    $ hg importfs myrepo myproject-v2 -m "Second import." -t second_import
+    8 files updated, 0 files merged, 0 files removed, 0 files unresolved
+    adding src/resources.py
+
+Now there are two new changesets::
+
+    $ hg log -R myrepo
+    changeset:   2:c8ff824da6c8
+    tag:         tip
+    user:        Markus Zapke-Gründemann <markus@keimlink.de>
+    date:        Tue Jul 10 10:27:10 2012 +0200
+    summary:     Added tag second_import for changeset 825c9a9356fd
+
+    changeset:   1:825c9a9356fd
+    tag:         second_import
+    user:        Markus Zapke-Gründemann <markus@keimlink.de>
+    date:        Tue Jul 10 10:27:10 2012 +0200
+    summary:     Second import.
+
+    changeset:   0:60304fa41a49
+    user:        Markus Zapke-Gründemann <markus@keimlink.de>
+    date:        Tue Jul 10 10:19:10 2012 +0200
+    summary:     importfs commit.
+
+Let's import the last version of the project into a new branch with
+changeset 0 as parent::
+
+    $ hg importfs myrepo myproject-v3 -m "Third import." -t third_import -b branch_2 -r 0
+    8 files updated, 0 files merged, 1 files removed, 0 files unresolved
+    marked working directory as branch branch_2
+    (branches are permanent and global, did you want a bookmark?)
+    removing src/cmdutils.py
+    adding src/resources.py
+
+The repository history looks now like this::
+
+    $ hg glog -R myrepo
+    @  changeset:   4:3ec5adb0448e
+    |  branch:      branch_2
+    |  tag:         tip
+    |  user:        Markus Zapke-Gründemann <markus@keimlink.de>
+    |  date:        Tue Jul 10 10:32:32 2012 +0200
+    |  summary:     Added tag third_import for changeset bfcf48ac159e
+    |
+    o  changeset:   3:bfcf48ac159e
+    |  branch:      branch_2
+    |  tag:         third_import
+    |  parent:      0:60304fa41a49
+    |  user:        Markus Zapke-Gründemann <markus@keimlink.de>
+    |  date:        Tue Jul 10 10:32:32 2012 +0200
+    |  summary:     Third import.
+    |
+    | o  changeset:   2:c8ff824da6c8
+    | |  user:        Markus Zapke-Gründemann <markus@keimlink.de>
+    | |  date:        Tue Jul 10 10:27:10 2012 +0200
+    | |  summary:     Added tag second_import for changeset 825c9a9356fd
+    | |
+    | o  changeset:   1:825c9a9356fd
+    |/   tag:         second_import
+    |    user:        Markus Zapke-Gründemann <markus@keimlink.de>
+    |    date:        Tue Jul 10 10:27:10 2012 +0200
+    |    summary:     Second import.
+    |
+    o  changeset:   0:60304fa41a49
+       user:        Markus Zapke-Gründemann <markus@keimlink.de>
+       date:        Tue Jul 10 10:19:10 2012 +0200
+       summary:     importfs commit.
+
+.. include:: CHANGELOG
+
+How to set up a development environment
+=======================================
+
+If you havn't created a clone of the importfs repository yet do it now::
+
+    $ hg clone https://bitbucket.org/keimlink/hg-importfs
+
+Setup a virtualenv
+------------------
+
+The best way to do the development is to use a virtualenv_. So first
+create one using virtualenvwrapper_::
+
+    $ mkvirtualenv --no-site-packages --distribute hg-importfs
+
+Then install all packages needed for development into the virtualenv
+using pip_::
+
+    (hg-importfs)$ cd hg-importfs
+    (hg-importfs)$ pip install -r requirements.txt
+
+You also need a clone of the hg repository::
+
+    (hg-importfs)$ cd ..
+    (hg-importfs)$ hg clone http://selenic.com/repo/hg
+
+Update to your desired version (if you don't want to use *tip*) and
+build for local use::
+
+    (hg-importfs)$ cd hg
+    (hg-importfs)$ hg up VERSION
+    (hg-importfs)$ make local
+
+After creating the clone create a few symlinks in your importfs repository::
+
+    (hg-importfs)$ cd ../hg-importfs
+    (hg-importfs)$ ln -s ../hg/contrib/pylintrc
+    (hg-importfs)$ ln -s ../hg/tests/hghave
+    (hg-importfs)$ ln -s ../hg/tests/run-tests.py
+
+Finally add the hg directory to your virtualenv::
+
+    (hg-importfs)$ add2virtualenv ../hg
+
+Run the tests
+-------------
+
+To run all tests you can now execute the following command::
+
+    (hg-importfs)$ ./run-tests.py -l
+
+Create a new source distribution package
+----------------------------------------
+
+A new Python source distribution package can be created using this command::
+
+    (hg-importfs)$ python setup.py sdist
+
+.. _Lantiq: http://www.lantiq.com/
+.. _Markus Zapke-Gründemann: http://www.keimlink.de/
+.. _pip: http://www.pip-installer.org/
+.. _virtualenv: http://pypi.python.org/pypi/virtualenv
+.. _virtualenvwrapper: http://pypi.python.org/pypi/virtualenvwrapper

requirements-dev.txt

-docutils
-ipython
-pep8
-pylint
+docutils==0.9.1
+ipython==0.13
+pep8==1.3.3
+pylint==0.25.1
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.