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](https://confluence.atlassian.com/display/BITBUCKET/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 https://bitbucket.org/your-team-name/SandboxRootHg.

2) Create a repository for your main project, e.g. SandboxHg at *https://bitbucket.org/your-team-name/SandboxHg*.

3) Create a repository for each of the dependencies:

- SandboxDep1Hg at *https://bitbucket.org/your-team-name/SandboxDep1Hg*
- SandboxDep2Hg at *https://bitbucket.org/your-team-name/sandboxDep1Hg*

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 = https://bitbucket.org/your-team-name/SandboxHg
SandboxDep1Hg = https://bitbucket.org/your-team-name/SandboxDep1Hg
SandboxDep2Hg = https://bitbucket.org/your-team-name/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).