Diff for "ConvertExtension"

Convert extension

This extension is distributed with Mercurial.

Author: several people

1. Overview

The convert extension converts repositories from other SCMs (or even Mercurial itself) into Mercurial repositories, with options for filtering and renaming. It's also useful to filter Mercurial repositories to get subsets of an existing one.

It currently supports the following repository types as sources:

• CVS
• Darcs
• Git
• Mercurial
• Subversion

It supports branches and incremental or ongoing conversion, as well as some features for tidying up new repositories, such as pruning parts of the tree and rewriting author names.

2. Configuration

Configure your .hgrc to enable the extension by adding following lines:

[extensions]
hgext.convert=

3. Usage

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

SOURCE points to a foreign SCM repository.

DEST is a directory name where the conversion data will go to. If DEST is not provided, it will be created as SOURCE-hg.

MAPFILE is a a simple text file that maps each source commit ID to the destination ID for each revision.

3.1. Options

3.1.1. --rev

Convert can optionally stop importing at a given revision, if the --rev option is provided. The argument should be given in terms the source understands (e.g. a revision number for Subversion sources, or a hash for git sources). This can also be useful to do incremental conversions. Incremental conversions may be useful not only when tracking newer changes in the source repo but also in very huge repos which would need huge resources for a whole conversion and can be better handled with an incremental one.

Is it possible to convert the last 100 revisions, because the old stuff is not interesting any more?

3.1.2. --authors

Convert can also remap author names during conversion, if the --authors option is provided. The argument should be a simple text file 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

3.1.3. --filemap

Convert can also filter or rename files during conversion, when you supply it a mapping via the --filemap option. The filemap is a file that allows filtering and remapping of files and directories and the paths are rooted subpaths, with complete subparts. Comment lines start with #.

Each line can contain one of the following directives:

• include path/to/file

• exclude path/to/file

• 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 any other element that's not under an inclusion rule.

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.

3.1.4. --datesort

Normally convert will import revisions in an order that produces the fewest jumps between branches in the commit log. If you want to make the revision order in the destination more closely match that of the parent, use the --datesort flag.

4. Converting from CVS

cvs client and [http://www.cobite.com/cvsps/ cvsps] are prerequisites. On Windows, cvsps requires cygwin. Work is underway to make cvsps work without cygwin - see http://repo.or.cz/w/cvsps/4msysgit.git/.

cvsps compression is not enabled by default, but can be activated in cvspsrc configuration file.

The convert extension uses a CVS "working directory" since it uses cvsps.

5. Converting from Darcs

The converter does not currently handle patch conflicts very well. For more detail, see the notes in [http://selenic.com/repo/hg/file/tip/tests/test-convert-darcs tests/test-convert-darcs]. If you encounter this problem, try using the deprecated contrib/darcs2hg.py script instead.

6. Converting from Subversion

Subversion's Python bindings are a prerequisite. The bindings (generated with SWIG) are installed separately on Windows, and can be found on http://subversion.tigris.org/ . The converter works best with local repositories (file://...), so you may want to use svnsync to create one if your access method is remote (especially if it is via http). The source may be a URL or a path to a repository or working directory. The converter supports a few Subversion-specific options:

svn.trunk

Relative path to the trunk (default: "trunk")

svn.branches

Relative path to tree of branches (default: "branches")

svn.tags

Relative path to tree of tags (default: "tags")

Set these under [convert] in a .hgrc, or on the command line as follows:

hg convert --config convert.svn.trunk=wackoname [...]

A child mercurial process is spawned to fetch subversion revision information. The heuristic used to find the mercurial executable is simple but good enough for basic setups. If you are running the convert extension from a mercurial installation which is not the primary one (not in $PATH), you should set the $HG environment variable to the location of your mercurial executable or script, so the child process will be spawned with the expected mercurial version.

6.1. Working around Network and Bindings Issues

Sometimes, conversion of remote repositories is complicated by poor network connectivity, remote server misconfiguration, SVN bindings issues or bugs in the converter when handling remote sources. Often, you would like to have the SVN repository locally to play and replay the conversion with different parameters or track bugs more quickly. One solution is to mirror it locally using the svnsync script provided along SVN distributions. Documentation about svnsync can be found here: http://svn.collab.net/repos/svn/trunk/notes/svnsync.txt.

7. Converting to Mercurial

The Mercurial back end supports the following configuration options:

hg.usebranchnames

Use named branches to record source branches (default: true)

hg.clonebranches

Create branches as clones of their parent branches. All branches will be created as subdirectories of the convert destination. (default: false)

hg.tagsbranch

Put tags on the given branch (default: default)

An example of using these settings in a .hgrc file is:

[convert]
hg.usebranchnames=0
hg.clonebranches=1

CategoryExtension CategoryConversion