Thomas Sampson

Getting Started With Mercurial Subrepositories

1 Comment

This evening I decided to investigate Mercurial Subrepositories (something which I had been putting off for some time due to their apparent non-trivial usage). Mercurial Subrepositories allow you to have a standalone repository included within a parent repository. An example of how you migh use this could be that your main application “repoA” wishes to include/house a particular library stored in remote “repoB” and wishes to keep fully in sync with “repoB”, pulling in new changesets (and also perhaps pushing new contributions / bug fixes).

As it turns out Mercurial’s support for subrepos works a treat and is definitely something I wish I had looked into sooner. After following the official mercurial subrepo docs, I found that getting a simple subrepo set up is fairly trivial. This post summarises my experience.

The task was simple. Take repository “repoB” and include it as a remote subrepo in the main repository “repoA”. This can be achieved fairly easily be carrying out the following steps..

    1. In your main repository, create a folder (ideally close to the root) to house your subrepository mkdir subrepo
    2. Navigate to the root of your main repository and create a file named .hgsub (this will store meta data about the subrepo mappings, similarly to how you might store ignore rules within the .hgignore file) touch .hgsub
    3. Use a text editor (or command line) to add a mapping to your .hgsub file. This mapping is very simple and exists as local_subrepo_path = external_repo_path (where local_subrepo_path is relative to the root of your main repository and external_repo_path can be a relative/absolute/url to your external sub repository). Example:echo subrepo = > .hgsub
    4. Finally make sure to hg add .hgsub and hg commit your changes


At this stage your subrepository is set up. Navigating to /subrepo and running hg commands will now effect the sub-repository whereas hg commands executed above /subrepo path affect the whole repository (in most cases recursing down into the sub repository). Make sure to run hg pull –update inside the sub repository to carry out the initial pull/update of the sub repository file structure. As hg clone works recursively, anyone who clones your main repository (to tip revision) should also automatically receive the /subrepo files (as they were at the tip of the main repository).


Author: tomtech999

I have recently graduated with a 1st class degree in MComp Games Software Development at Sheffield Hallam University, focusing primarily on application development in C++, with experience in graphics programming, scripting languages, DVCS/VCS and web technology. In my spare time I enjoy Drumming, Reading and Snowboarding!

One thought on “Getting Started With Mercurial Subrepositories

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s