Rev 38: Update use cases and description for conversion. in http://bzr.arbash-meinel.com/plugins/cvsps_import

[John Arbash Meinel]

At http://bzr.arbash-meinel.com/plugins/cvsps_import

------------------------------------------------------------
revno: 38
revision-id: john at arbash-meinel.com-20070128173437-wz8226sw82dmav0y
parent: john at arbash-meinel.com-20070128170159-fzix4a1tpr07nrd7
committer: John Arbash Meinel <john at arbash-meinel.com>
branch nick: cvsps_import
timestamp: Sun 2007-01-28 11:34:37 -0600
message:
  Update use cases and description for conversion.
modified:
  README.rst                     readme.rst-20061130225749-9010g8f1k7l1tmgl-1
-------------- next part --------------
=== modified file 'README.rst'
--- a/README.rst	2006-11-30 23:01:18 +0000
+++ b/README.rst	2007-01-28 17:34:37 +0000
@@ -6,7 +6,7 @@
 into a bzr repository, preserving the project history.
 
 You can find the Launchpad_ project (including the bug tracker) at
-http://launchpad.net/products/bzr-cvsps-import
+https://launchpad.net/bzr-cvsps-import
 
 .. _Launchpad: http://launchpad.net
 
@@ -26,5 +26,85 @@
 
 .. _Tailor: http://www.darcs.net/DarcsWiki/Tailor
 
+
+Example Usage
+=============
+
+There are a few ways to use ``cvsps-import`` depending on the complexity of
+the project.
+
+
+Normal Usage
+------------
+
+Most project can be simply imported with::
+
+  bzr cvsps-import path/to/cvsroot module output
+ 
+Obviously this has 3 portions
+
+``path/to/cvsroot``
+  This can be a relative or absolute path, but at the moment must be a local
+  path. (``:pserver:`` and ``:ext:`` are not yet supported).
+  Underneath this directory should be the cvs control files. Most notably
+  ``CVSROOT`` which is how cvs tells that it is a repository.
+  You should be able to ``cvs -d /absolute/path/to/cvsroot rlog module``.
+
+``module``
+  The cvs module to converted. This can be "." to convert the entire
+  repository.
+  It can be any path inside the repository (ie it can be a sub-module with
+  "``path/to/module``").
+
+``output``
+  An output directory to store the conversion, and any intermediate
+  information.
+
+
+When things get tricky
+----------------------
+
+Usually ``bzr cvsps-import`` runs ``cvsps`` itself with appropriate flags to
+generate the changeset file. ``cvsps`` has some limited support for extracting
+the log of all revisions. However, sometimes that is insufficient and you need
+to generate a dump file manually. To do so, create a cvs checkout of the base
+module (you can checkout just the top-level directory with ``-l``). And then
+run ``cvsps`` from there to generate the dump file.
+
+For example::
+
+  cvs -d /path/to/cvsroot co -l module
+  cd module
+  cvsps -A -q -u > ../module.dump
+  cd ..
+  bzr cvsps-import --cvsps-dump module.dump /path/to/cvsroot module out
+
+
+Options
+=======
+
+There are a few options which can be used to change how the conversion will be
+done.
+
+``--use-rcs``
+  When extracting texts from the control files, use the rcs command "``co``".
+  This is slightly faster than ``--use-cvs``.
+
+``--use-cvs``
+  Use ``cvs co -p`` to extract the texts from the control files. This is
+  useful when you don't have the rcs tools installed. It seems to be slightly
+  slower than ``--use-rcs``.
+
+``--encoding=ENCODING``
+  Set the encoding to use when reading author names and commit logs. The
+  default encoding is ``iso-8859-1`` (``latin-1``).
+
+
+BUGS
+====
+
+The bug tracker for ``cvsps-import`` is hosted on launchpad at
+https://launchpad.net/bzr-cvsps-import/+bugs
+
 .. 
    vim: tw=78 spell ft=rst