Skip to content

Hg subrepositories: a how-to guide for the “svn:externals” junkie (Part 1)

This is the first post from a multi-part article about using Mercurial subrepositories when you are switching from Subversion to Mercurial and you heavily used Subversion subrepositories configured via the svn:externals property.

Often a common scenario in software development is to have a main project that depends on other projects. Here is an example of how the Subversion “trunk” for such projects might look like:

``` text svn://svnserver/SandboxSvn trunk SandboxSvn (main source code) SanboxDep1Svn (svn:externals link from svn://svnserver/SandboxDep1Svn/trunk) SanboxDep2Svn (svn:externals link from svn://svnserver/SandboxDep2Svn/trunk)

Basically we have a repository at *svn://svnserver/SandboxSvn* that includes the main project called *SandboxSvn* and two projects* SandboxDep1Svn* and *SandboxDep2Svn* on which *SandboxSvn* depends. The dependency projects are linked from two separate Subversion repositories, hosted at *svn://svnserver/SandboxDep1Svn/trunk* and *svn://svnserver/SandboxDep2Svn/trunk* respectively.

You can create a similar structure in Mercurial by using the Mercurial subrepositories. In the example below, I use BitBucket, so I can test my setup later, but the same steps should be valid for any other shared Mercurial setup. For more information on how to use BitBucket, see the [BitBucket 101]( "BitBucket 101") wiki.

Steps to setup a main project with two dependencies in Mercurial:

1) Create a repository called SandboxRootHg. This will be a containerrepository for both the main project and the dependencies. I set that up at

2) Create a repository for your main project, e.g. SandboxHg at **.

3) Create a repository for each of the dependencies:

- SandboxDep1Hg at **
- SandboxDep2Hg at **

4) Setup the three dependencies in the container project.

You first have to clone the container repository locally to your machine. In our case the containeris *SandboxRootHg*, so I cloned that in a new*SandboxRootHg* folder. In the *SandboxRootHg* folder create a *.hgsub* file(note the dot in the*.hgsub*name), and add the *SandboxHg*, *SandboxDep1Hg* and *SandboxDep2Hg* projects to in the *.hgsub* file. Your final *.hgsub* will have three lines in it and will look similar to this:

``` text 
SandboxHg =
SandboxDep1Hg =
SandboxDep2Hg =

5) In the SandboxRootHg folder, do a Hg/Add to add the .hgsub file to Mercurial, then Hg/Commit. And last, do not forget to do a Hg/Push to update the remote shared repository with your changes.

Continue to Hg subrepositories: a how-to guide for the “svn:externals” junkie (Part 2).