convert

convert a foreign SCM repository to a Mercurial one.:

hg convert [OPTION]... SOURCE [DEST [REVMAP]]

Accepted source formats [identifiers]:

• Mercurial [hg]
• CVS [cvs]
• Darcs [darcs]
• git [git]
• Subversion [svn]
• Monotone [mtn]
• GNU Arch [gnuarch]
• Bazaar [bzr]
• Perforce [p4]

Accepted destination formats [identifiers]:

• 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 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:

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:

<source ID> <destination ID>

If the file doesn't exist, it's automatically created. It's updated on each commit copied, so hg convert can be interrupted and can be run repeatedly to copy new commits.

The authormap 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 (e.g.: CVS). One line per author mapping and the line format is:

source author = destination author

Empty lines and lines starting with a # are ignored.

The filemap is a file that allows filtering and remapping of files and directories. Each line can contain one of the following directives:

include path/to/file-or-dir

exclude path/to/file-or-dir

rename path/to/source path/to/destination

Comment lines start with #. A specified path matches if it equals the full relative name of a file or one of its parent directories. The include or exclude directive with the longest matching path applies, so line order does not matter.

The include directive causes a file, or all files under a directory, to be included in the destination repository. The default if there are no include statements is to include everything. If there are any include statements, nothing else is included. The exclude directive causes files or directories to be omitted. The rename directive renames a file or directory if it is converted. To rename from a subdirectory into the root of the repository, use . as the path to rename to.

--full will make sure the converted changesets contain exactly the right files with the right content. It will make a full conversion of all files, not just the ones that have changed. Files that already are correct will not be changed. This can be used to apply filemap changes when converting incrementally. This is currently only supported for Mercurial and Subversion.

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:

key parent1, parent2

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. For example, if you have merged "release-1.0" into "trunk", then you should specify the revision on "trunk" as the first parent and the one on the "release-1.0" branch as the second.

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

where "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. No whitespace is allowed in the new branch name. This can be used to (for instance) move code in one repository from "default" to a named branch.

# so convert knows the type when it sees a non empty destination
$ hg init converted

$ hg convert orig/sub1 converted/sub1
$ hg convert orig/sub2 converted/sub2
$ hg convert orig converted