Mercurial > hg-stable
changeset 9058:b10cee4bd2c1
convert: wrapped docstrings at 78 characters
| author | Martin Geisler <mg@lazybytes.net> |
|---|---|
| date | Tue, 07 Jul 2009 23:54:42 +0200 |
| parents | 07788bbb35e4 |
| children | 269764ecffe2 |
| files | hgext/convert/__init__.py tests/test-convert.out |
| diffstat | 2 files changed, 208 insertions(+), 221 deletions(-) [+] |
line wrap: on
line diff
--- a/hgext/convert/__init__.py Tue Jul 07 23:54:42 2009 +0200 +++ b/hgext/convert/__init__.py Tue Jul 07 23:54:42 2009 +0200 @@ -33,45 +33,45 @@ - 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: - --branchsort: convert from parent to child revision when - possible, which means branches are usually converted one after - the other. It generates more compact repositories. + 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. --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. - --sourcesort: try to preserve source revisions order, only - supported by Mercurial sources. + 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. 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 @@ -79,35 +79,32 @@ 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 ----------------- @@ -117,75 +114,73 @@ 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' + This option is deprecated and will be removed in Mercurial 1.4. The options shown are the defaults. Internal cvsps is selected by setting + --config convert.cvsps=builtin + 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. --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 @@ -194,9 +189,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. @@ -204,15 +199,14 @@ 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. @@ -237,14 +231,13 @@ 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"
--- a/tests/test-convert.out Tue Jul 07 23:54:42 2009 +0200 +++ b/tests/test-convert.out Tue Jul 07 23:54:42 2009 +0200 @@ -17,45 +17,45 @@ - 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: - --branchsort: convert from parent to child revision when - possible, which means branches are usually converted one after - the other. It generates more compact repositories. + 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. --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. - --sourcesort: try to preserve source revisions order, only - supported by Mercurial sources. + 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. 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 @@ -63,35 +63,32 @@ 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 ----------------- @@ -101,75 +98,73 @@ 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' + This option is deprecated and will be removed in Mercurial 1.4. The options shown are the defaults. Internal cvsps is selected by setting + --config convert.cvsps=builtin + 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. --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 @@ -178,9 +173,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. @@ -188,15 +183,14 @@ 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.