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:
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 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 newSandboxRootHg folder. In the SandboxRootHg folder create a .hgsub file(note the dot in the.hgsubname), 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:
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).