hgsubversion / hgsubversion / help / subversion.rst

Full commit

Basic Use

Converting a Subversion repository to Mercurial with hgsubversion is done by cloning it. Subversion repositories are specified using the same, regular URL syntax that Subversion uses. hgsubversion accepts URIs such as the following:

In the case of the two first schemas, HTTP and HTTPS, the repository is first treated as a Mercurial repository, and a Subversion pull attempted should it fail. As this can be particularly annoying for repositories that require authentication, such repositories may also specified using a svn+http or svn+https schema.

To create a new Mercurial clone, you can use a command such as the following:

$ hg clone <repository URI> [destination]

Or with a real example:

$ hg clone nose-hg

Please note that there are two slightly different ways of cloning repositories:

The most common desire is to have the full history of a repository, including all its tags and branches. In such cases you should clone from one level above trunk, as in the example above. This is known as standard layout, and works with repositories that use the conventional trunk, tags and branches directories. By default, hgsubversion will use this layout whenever it finds any of these directories at the specified directory on the server.

If you instead want to clone just a single directory or branch, clone the specific directory path. In the example above, to get only trunk, you would issue hg clone nose-trunk. This works with any directory with a Subversion repository, and is known as a single directory clone. Normally, converted changesets will be marked as belonging to the default branch, but this can be changed by using the -b/--branch option when using Mercurial 1.5 or later. To force single directory clone, use hgsubversion.layout option (see below for detailed help)

$ hg clone --layout single svn+ nose-hg

Pulling new revisions into an already-converted repository is the same as from any other Mercurial source. Within the first example above, the following three commands are all equivalent:

$ hg pull
$ hg pull default
$ hg pull

Sometimes, past repository history is of little or no interest, and all one wants is to start from today and work forward. Using --startrev HEAD causes the initial clone to only convert the latest revision; later pulls will convert all subsequent revisions. Please note that this only works for single-directory clones:

$ hg clone --startrev HEAD nose-hg

Finding and displaying Subversion revisions

For revealing the relationship between Mercurial changesets and Subversion revisions, hgsubversion provides three template keywords:

svnrev:Expanded to the original Subversion revision number.
svnpath:The path within the repository that the changeset represents.
svnuuid:The Universally Unique Identifier of the Subversion repository.

An example:

$ hg log --template='{rev}:{node|short} {author|user}\nsvn: {svnrev}\n'

The template keywords are available when using Mercurial 1.5 or later.

For finding changesets from Subversion, hgsubversion extends revsets to provide two new selectors:

fromsvn:Select changesets that originate from Subversion. Takes no arguments.
svnrev:Select changesets that originate in a specific Subversion revision. Takes a revision argument.

For example:

$ hg log -r 'fromsvn()'
$ hg log -r 'svnrev(500)'

Revsets are available when using Mercurial 1.6 or later and are accepted by several Mercurial commands for specifying revisions. See hg help revsets for details.

Support for externals

Subversion externals conversion is implemented for standard layouts.

Using .hgsvnexternals (default mode)

.hgsvnexternals has been implemented before Mercurial supported proper subrepositories. Externals as subrepositories should now be preferred as they offer almost all .hgsvnexternals features with the benefit of a better integration with Mercurial commands.

svn:externals properties are serialized into a single .hgsvnexternals file having the following syntax:

 common1 http://path/to/external/svn/repo1
 ...additional svn:externals properties lines...
 common2 -r123 http://path/to/external/svn/repo2
 ...additional svn:externals properties lines...

A header line in brackets specifies the directory the property applies to, where '.' indicates the project root directory. The property content follows the header, with every content line being prefixed by a single space. Note that the property lines have a format identical to svn:externals properties as used in Subversion, and do not support the hgsubversion extended svn+http:// URL format.

Issuing the command hg svn updateexternals with the .hgsvnexternals example above would fetch the latest revision of repo1 into the subdirectory ./common1, and revision 123 of repo2 into dir2/common2. Note that .hgsvnexternals must be tracked by Mercurial before this will work. If .hgsvnexternals is created or changed, it will not be pushed to the related Subversion repository, but its contents will be used to update svn:externals properties on the related Subversion repository.

Alternatively, one can use the hgsubversion.externals in hgrc to specify subrepos as the externals mode. In this mode, .hgsub and .hgsubstate files will be used instead of .hgsvnexternals. This feature requires Mercurial 1.7.1 or later.

Using Subrepositories


[hgsubversion] externals = subrepos

to enable this mode.

svn:externals properties are serialized into the subrepositories metadata files, .hgsub and .hgsubstate. The following svn:externals entry:

-r23 ^/externals/project1 deps/project1

set on the "subdir" directory becomes:

(.hgsub) subdir/deps/project1 = [hgsubversion] subdir:-r{REV} ^/externals/project1 deps/project1

(.hgsubstate) 23 subdir/deps/project1

At this point everything works like a regular svn subrepository. The right part of the .hgsub entry reads like:


where REWRITTEN_EXTERNAL_DEFINITION is like the original definition with the revision identifier replaced with {REV}.

This mode has the following limitations:

  • Require Mercurial >= 1.7.1 to work correctly on all platforms.
  • "hgsubversion" subrepositories require hgsubversion extension to be available. To operate transparently on svn:externals we have to stay as close as possible to their original property format. Besides, relative externals require a parent subversion repository to be resolved while stock Mercurial only supports absolute subversion paths.
  • Leading or trailing whitespaces in the external definitions are lost
  • Leading or trailing whitespaces in the target directory are lost
  • The external definition should not contain {REV}
  • Unversioned definitions are pulled but the behaviour upon update/merge is not clearly defined. We tried to preserve the .hgsubstate as "HEAD" but the subrepository will probably not be updated when the hg repository is updated. Given subrepositories were designed not to support unversioned dependencies, this is unlikely to be fixed.
  • .hgsub and .hgsubstate are currently overwritten and non-[hgsubversion] subrepos entries are lost. This could be fixed by editing these files more carefully.


Currently, pushing to Subversion destroys the original changesets and replaces them with new ones converted from the resulting commits. Due to the intricacies of Subversion semantics, these converted changesets may differ in subtle ways from the original Mercurial changesets. For example, the commit date almost always changes. This makes hgsubversion unsuitable for use as a two-way bridge.

When converting from Subversion, hgsubversion does not recognize merge-info, and does not create merges based on it. Similarly, Mercurial merges cannot be pushed to Subversion.

Changesets that create tags cannot be pushed to Subversion, as support for creating Subversion tags has not yet been implemented.

Standard layout does not work with repositories that use unconventional layouts. Thus, only single directory clones can be made of such repositories.

When interacting with Subversion, hgsubversion relies on information about the previously converted changesets. This information will not be updated if pushing or pulling converted changesets to or from any other source. To regenerate the stored metadata, run hg svn rebuildmeta [URI]. This must also be done if any converted changesets are ever removed from the repository.

Under certain circumstances a long-running conversion can leak substantial amounts of memory, on the order of 100MB per 1000 converted revisions. The leaks appear to be persistent and unavoidable using the SWIG bindings. When using the new experimental Subvertpy bindings, leaks have only been observed accessing FSFS repositories over the file protocol.

Should the initial clone fail with an error, Mercurial will delete the entire repository, including any revisions successfully converted. This can be particularly undesirable for long-running clones. In these cases, we suggest using the -r/--rev option to only clone a few revisions initially. After that, an hg pull in the cloned repository will be perfectly safe.

It is not possible to interact with more than one Subversion repository per Mercurial clone. Please note that this also applies to more than one path within the same Subversion repository.

Mercurial does not track directories, and as a result, any empty directories in Subversion cannot be represented in the resulting Mercurial repository.

Externals support requires that the svn command line utility is available. In addition, externals support has been disabled for single directory clones, due to known bugs.

Advanced Configuration

The operation of hgsubversion can be customized by the following configuration settings:


Path to a file for mapping usernames from Subversion to Mercurial. For example:

joe = Joe User <>

Some Subversion conversion tools create revisions without specifying an author. Such author names are mapped to (no author), similar to how svn log will display them.


This option specifies the hostname to append to unmapped Subversion usernames. The default is to append the UUID of the Subversion repository as a hostname. That is, an author of bob may be mapped to bob@0b1d8996-7ded-4192-9199-38e2bec458fb.

If this option set to an empty string, the Subversion authors will be used with no hostname component.


This option selects what to substitute for an empty log message. The default is to substitute three dots, or ....


Setting this boolean option to false will cause hgsubversion to abort a conversion if a revision has an author not listed in the author map.


Mark converted changesets as belonging to this branch or, if unspecified, default. Please note that this option is not supported for standard layout clones.


Path to a file for changing branch names during the conversion from Subversion to Mercurial.


Name of the Mercurial branch Subversion trunk changesets must belong to or, if unspecified, default. Useful if you set your branchmap for the default branch to come from another Subversion branch.


Path to a file for filtering files during the conversion. Files may either be included or excluded. See the documentation for hg convert for more information on filemaps.

hgsubversion.username, hgsubversion.password

Set the username or password for accessing Subversion repositories.
Setting this boolean option to true will force using a slower method for pulling revisions from Subversion. This method is compatible with servers using very old versions of Subversion, and hgsubversion falls back to it when necessary.
Set to subrepos to switch to subrepos-based externals support (requires Mercurial 1.7.1 or later.) Default is svnexternals, which uses a custom hgsubversion-specific format and works on older versions of Mercurial. Use ignore to avoid converting externals.

The following options only have an effect on the initial clone of a repository:


Set the layout of the repository. standard assumes a normal trunk/branches/tags layout. single means that the entire repository is converted into a single branch. The default, auto, causes hgsubversion to assume a standard layout if any of trunk, branches, or tags exist within the specified directory on the server.


Convert Subversion revisions starting at the one specified, either an integer revision or HEAD; HEAD causes only the latest revision to be pulled. The default is to pull everything.


Specifies one or more paths in the Subversion repository that contain tags. The default is to only look in tags. This option has no effect for single-directory clones.

Please note that some of these options may be specified as command line options as well, and when done so, will override the configuration. If an authormap, filemap or branchmap is specified, its contents will be read and stored for use in future pulls.

Finally, the following environment variables can be used for testing a deployment of hgsubversion:


By default, hgsubversion will use Subvertpy, but fall back to the SWIG bindings. Set this variable to either SWIG or Subvertpy (case- insensitive) to force that set of bindings.