changeset 9256:dd89dd090b47

convert: wrap docstrings at 70 characters
author Martin Geisler <mg@lazybytes.net>
date Sun, 26 Jul 2009 01:44:41 +0200
parents acfbb88c6ced
children 50ebe8845a1b
files hgext/convert/__init__.py
diffstat 1 files changed, 114 insertions(+), 104 deletions(-) [+]
line wrap: on
line diff
--- a/hgext/convert/__init__.py	Sun Jul 26 01:42:15 2009 +0200
+++ b/hgext/convert/__init__.py	Sun Jul 26 01:44:41 2009 +0200
@@ -35,48 +35,50 @@
     - Mercurial [hg]
     - Subversion [svn] (history on branches is not preserved)
 
-    If no revision is given, all revisions will be converted. Otherwise,
-    convert will only import up to the named revision (given in a format
-    understood by the source).
+    If no revision is given, all revisions will be converted.
+    Otherwise, convert will only import up to the named revision
+    (given in a format understood by the source).
 
-    If no destination directory name is specified, it defaults to the basename
-    of the source with '-hg' appended. If the destination repository doesn't
-    exist, it will be created.
+    If no destination directory name is specified, it defaults to the
+    basename of the source with '-hg' appended. If the destination
+    repository doesn't exist, it will be created.
 
-    By default, all sources except Mercurial will use --branchsort. Mercurial
-    uses --sourcesort to preserve original revision numbers order. Sort modes
-    have the following effects:
+    By default, all sources except Mercurial will use --branchsort.
+    Mercurial uses --sourcesort to preserve original revision numbers
+    order. Sort modes have the following effects:
 
-    --branchsort  convert from parent to child revision when possible, which
-                  means branches are usually converted one after the other. It
-                  generates more compact repositories.
+    --branchsort  convert from parent to child revision when possible,
+                  which means branches are usually converted one after
+                  the other. It generates more compact repositories.
 
     --datesort    sort revisions by date. Converted repositories have
-                  good-looking changelogs but are often an order of magnitude
-                  larger than the same ones generated by --branchsort.
+                  good-looking changelogs but are often an order of
+                  magnitude larger than the same ones generated by
+                  --branchsort.
 
-    --sourcesort  try to preserve source revisions order, only supported by
-                  Mercurial sources.
+    --sourcesort  try to preserve source revisions order, only
+                  supported by Mercurial sources.
 
     If <REVMAP> isn't given, it will be put in a default location
-    (<dest>/.hg/shamap by default). The <REVMAP> is a simple text file that
-    maps each source commit ID to the destination ID for that revision, like
-    so::
+    (<dest>/.hg/shamap by default). The <REVMAP> is a simple text file
+    that maps each source commit ID to the destination ID for that
+    revision, like so::
 
       <source ID> <destination ID>
 
-    If the file doesn't exist, it's automatically created. It's updated on
-    each commit copied, so convert-repo can be interrupted and can be run
-    repeatedly to copy new commits.
+    If the file doesn't exist, it's automatically created. It's
+    updated on each commit copied, so convert-repo can be interrupted
+    and can be run repeatedly to copy new commits.
 
-    The [username mapping] file is a simple text file that maps each source
-    commit author to a destination commit author. It is handy for source SCMs
-    that use unix logins to identify authors (eg: CVS). One line per author
-    mapping and the line format is: srcauthor=whatever string you want
+    The [username mapping] file is a simple text file that maps each
+    source commit author to a destination commit author. It is handy
+    for source SCMs that use unix logins to identify authors (eg:
+    CVS). One line per author mapping and the line format is:
+    srcauthor=whatever string you want
 
-    The filemap is a file that allows filtering and remapping of files and
-    directories. Comment lines start with '#'. Each line can contain one of
-    the following directives::
+    The filemap is a file that allows filtering and remapping of files
+    and directories. Comment lines start with '#'. Each line can
+    contain one of the following directives::
 
       include path/to/file
 
@@ -84,32 +86,35 @@
 
       rename from/file to/file
 
-    The 'include' directive causes a file, or all files under a directory, to
-    be included in the destination repository, and the exclusion of all other
-    files and directories not explicitly included. The 'exclude' directive
-    causes files or directories to be omitted. The 'rename' directive renames
-    a file or directory. To rename from a subdirectory into the root of the
-    repository, use '.' as the path to rename to.
+    The 'include' directive causes a file, or all files under a
+    directory, to be included in the destination repository, and the
+    exclusion of all other files and directories not explicitly
+    included. The 'exclude' directive causes files or directories to
+    be omitted. The 'rename' directive renames a file or directory. To
+    rename from a subdirectory into the root of the repository, use
+    '.' as the path to rename to.
 
-    The splicemap is a file that allows insertion of synthetic history,
-    letting you specify the parents of a revision. This is useful if you want
-    to e.g. give a Subversion merge two parents, or graft two disconnected
-    series of history together. Each entry contains a key, followed by a
-    space, followed by one or two comma-separated values. The key is the
-    revision ID in the source revision control system whose parents should be
-    modified (same format as a key in .hg/shamap). The values are the revision
-    IDs (in either the source or destination revision control system) that
+    The splicemap is a file that allows insertion of synthetic
+    history, letting you specify the parents of a revision. This is
+    useful if you want to e.g. give a Subversion merge two parents, or
+    graft two disconnected series of history together. Each entry
+    contains a key, followed by a space, followed by one or two
+    comma-separated values. The key is the revision ID in the source
+    revision control system whose parents should be modified (same
+    format as a key in .hg/shamap). The values are the revision IDs
+    (in either the source or destination revision control system) that
     should be used as the new parents for that node.
 
     The branchmap is a file that allows you to rename a branch when it is
     being brought in from whatever external repository. When used in
-    conjunction with a splicemap, it allows for a powerful combination to help
-    fix even the most badly mismanaged repositories and turn them into nicely
-    structured Mercurial repositories. The branchmap contains lines of the
-    form "original_branch_name new_branch_name". "original_branch_name" is the
-    name of the branch in the source repository, and "new_branch_name" is the
-    name of the branch is the destination repository. This can be used to (for
-    instance) move code in one repository from "default" to a named branch.
+    conjunction with a splicemap, it allows for a powerful combination
+    to help fix even the most badly mismanaged repositories and turn them
+    into nicely structured Mercurial repositories. The branchmap contains
+    lines of the form "original_branch_name new_branch_name".
+    "original_branch_name" is the name of the branch in the source
+    repository, and "new_branch_name" is the name of the branch is the
+    destination repository. This can be used to (for instance) move code
+    in one repository from "default" to a named branch.
 
     Mercurial Source
     ----------------
@@ -119,26 +124,28 @@
         repositories with missing revlogs, by converting from and to
         Mercurial.
     --config convert.hg.saverev=False         (boolean)
-        store original revision ID in changeset (forces target IDs to change)
+        store original revision ID in changeset (forces target IDs to
+        change)
     --config convert.hg.startrev=0            (hg revision identifier)
         convert start revision and its descendants
 
     CVS Source
     ----------
 
-    CVS source will use a sandbox (i.e. a checked-out copy) from CVS to
-    indicate the starting point of what will be converted. Direct access to
-    the repository files is not needed, unless of course the repository is
-    :local:. The conversion uses the top level directory in the sandbox to
-    find the CVS repository, and then uses CVS rlog commands to find files to
-    convert. This means that unless a filemap is given, all files under the
-    starting directory will be converted, and that any directory
-    reorganization in the CVS sandbox is ignored.
+    CVS source will use a sandbox (i.e. a checked-out copy) from CVS
+    to indicate the starting point of what will be converted. Direct
+    access to the repository files is not needed, unless of course the
+    repository is :local:. The conversion uses the top level directory
+    in the sandbox to find the CVS repository, and then uses CVS rlog
+    commands to find files to convert. This means that unless a
+    filemap is given, all files under the starting directory will be
+    converted, and that any directory reorganization in the CVS
+    sandbox is ignored.
 
     Because CVS does not have changesets, it is necessary to collect
-    individual commits to CVS and merge them into changesets. CVS source uses
-    its internal changeset merging code by default but can be configured to
-    call the external 'cvsps' program by setting::
+    individual commits to CVS and merge them into changesets. CVS
+    source uses its internal changeset merging code by default but can
+    be configured to call the external 'cvsps' program by setting::
 
       --config convert.cvsps='cvsps -A -u --cvs-direct -q'
 
@@ -153,40 +160,41 @@
     and has a few more configurable options:
 
     --config convert.cvsps.cache=True         (boolean)
-        Set to False to disable remote log caching, for testing and debugging
-        purposes.
+        Set to False to disable remote log caching, for testing and
+        debugging purposes.
     --config convert.cvsps.fuzz=60            (integer)
-        Specify the maximum time (in seconds) that is allowed between commits
-        with identical user and log message in a single changeset. When very
-        large files were checked in as part of a changeset then the default
-        may not be long enough.
+        Specify the maximum time (in seconds) that is allowed between
+        commits with identical user and log message in a single
+        changeset. When very large files were checked in as part of a
+        changeset then the default may not be long enough.
     --config convert.cvsps.mergeto='{{mergetobranch ([-\\w]+)}}'
-        Specify a regular expression to which commit log messages are matched.
-        If a match occurs, then the conversion process will insert a dummy
-        revision merging the branch on which this log message occurs to the
-        branch indicated in the regex.
+        Specify a regular expression to which commit log messages are
+        matched. If a match occurs, then the conversion process will
+        insert a dummy revision merging the branch on which this log
+        message occurs to the branch indicated in the regex.
     --config convert.cvsps.mergefrom='{{mergefrombranch ([-\\w]+)}}'
-        Specify a regular expression to which commit log messages are matched.
-        If a match occurs, then the conversion process will add the most
-        recent revision on the branch indicated in the regex as the second
-        parent of the changeset.
+        Specify a regular expression to which commit log messages are
+        matched. If a match occurs, then the conversion process will
+        add the most recent revision on the branch indicated in the
+        regex as the second parent of the changeset.
 
-    The hgext/convert/cvsps wrapper script allows the builtin changeset
-    merging code to be run without doing a conversion. Its parameters and
-    output are similar to that of cvsps 2.1.
+    The hgext/convert/cvsps wrapper script allows the builtin
+    changeset merging code to be run without doing a conversion. Its
+    parameters and output are similar to that of cvsps 2.1.
 
     Subversion Source
     -----------------
 
-    Subversion source detects classical trunk/branches/tags layouts. By
-    default, the supplied "svn://repo/path/" source URL is converted as a
-    single branch. If "svn://repo/path/trunk" exists it replaces the default
-    branch. If "svn://repo/path/branches" exists, its subdirectories are
-    listed as possible branches. If "svn://repo/path/tags" exists, it is
-    looked for tags referencing converted branches. Default "trunk",
-    "branches" and "tags" values can be overridden with following options. Set
-    them to paths relative to the source URL, or leave them blank to disable
-    auto detection.
+    Subversion source detects classical trunk/branches/tags layouts.
+    By default, the supplied "svn://repo/path/" source URL is
+    converted as a single branch. If "svn://repo/path/trunk" exists it
+    replaces the default branch. If "svn://repo/path/branches" exists,
+    its subdirectories are listed as possible branches. If
+    "svn://repo/path/tags" exists, it is looked for tags referencing
+    converted branches. Default "trunk", "branches" and "tags" values
+    can be overridden with following options. Set them to paths
+    relative to the source URL, or leave them blank to disable auto
+    detection.
 
     --config convert.svn.branches=branches    (directory name)
         specify the directory containing branches
@@ -195,9 +203,9 @@
     --config convert.svn.trunk=trunk          (directory name)
         specify the name of the trunk branch
 
-    Source history can be retrieved starting at a specific revision, instead
-    of being integrally converted. Only single branch conversions are
-    supported.
+    Source history can be retrieved starting at a specific revision,
+    instead of being integrally converted. Only single branch
+    conversions are supported.
 
     --config convert.svn.startrev=0           (svn revision number)
         specify start Subversion revision.
@@ -205,14 +213,15 @@
     Perforce Source
     ---------------
 
-    The Perforce (P4) importer can be given a p4 depot path or a client
-    specification as source. It will convert all files in the source to a flat
-    Mercurial repository, ignoring labels, branches and integrations. Note
-    that when a depot path is given you then usually should specify a target
-    directory, because otherwise the target may be named ...-hg.
+    The Perforce (P4) importer can be given a p4 depot path or a
+    client specification as source. It will convert all files in the
+    source to a flat Mercurial repository, ignoring labels, branches
+    and integrations. Note that when a depot path is given you then
+    usually should specify a target directory, because otherwise the
+    target may be named ...-hg.
 
-    It is possible to limit the amount of source history to be converted by
-    specifying an initial Perforce revision.
+    It is possible to limit the amount of source history to be
+    converted by specifying an initial Perforce revision.
 
     --config convert.p4.startrev=0            (perforce changelist number)
         specify initial Perforce revision.
@@ -236,13 +245,14 @@
 def debugcvsps(ui, *args, **opts):
     '''create changeset information from CVS
 
-    This command is intended as a debugging tool for the CVS to Mercurial
-    converter, and can be used as a direct replacement for cvsps.
+    This command is intended as a debugging tool for the CVS to
+    Mercurial converter, and can be used as a direct replacement for
+    cvsps.
 
-    Hg debugcvsps reads the CVS rlog for current directory (or any named
-    directory) in the CVS repository, and converts the log to a series of
-    changesets based on matching commit log entries and dates.
-    '''
+    Hg debugcvsps reads the CVS rlog for current directory (or any
+    named directory) in the CVS repository, and converts the log to a
+    series of changesets based on matching commit log entries and
+    dates.'''
     return cvsps.debugcvsps(ui, *args, **opts)
 
 commands.norepo += " convert debugsvnlog debugcvsps"