Subrepositories

(Translations : French)

This feature was introduced in a preliminary form in Mercurial 1.3 and has been improved steadily since then. There are still some commands that lack proper support for sub-repositories, but we will fix them as we come across them and as we figure out how to best make them subrepo-aware.

Subrepositories is a feature that allows you to treat a collection of repositories as a group. This will allow you to clone, commit to, push, and pull projects and their associated libraries as a group.

For those used to Subversion, this concept is closest to what you can achieve with Subversion directories marked with the svn:externals property. Mercurial 1.5 has support for using Subversion repositories as subrepos.

Contents

  1. Subrepositories
    1. Basic Usage
      1. Start
      2. Committing
      3. Directory structure
      4. Update
      5. Delete
    2. Caveats
    3. Internals
    4. To Do

1. Basic Usage

1.1. Start

To start using subrepositories, you need two repositories, a main repo and a nested repo: 

$ hg init main
$ cd main
$ hg init nested
$ echo test > nested/foo
$ hg -R nested add nested/foo

Now we'll mark nested as a subrepository by creating an entry for it in the special .hgsub file. The first 'nested' is the path in our working dir, and the second is a URL or path to pull from. Here we're simply going to pull from 'nested' using a path relative to main. This says 'anyone who can find our main repo can find the nested repo just by tacking nested onto that path'. 

$ echo nested = nested > .hgsub
$ hg add .hgsub

1.2. Committing

When we commit, Mercurial will attempt to recursively commit in all defined subrepos and then record their resulting states in a special .hgsubstate file: 

$ hg ci -mtest
committing subrepository nested
$ cat .hgsubstate
3f68b2f93426b6966b604536037b5d325ba00741 nested

1.3. Directory structure

At this point of our example, we have the following directory structure: 

  main/
      .hg/
      .hgsub
      .hgsubstate
      nested/
          .hg/
          foo

with .hgsub containing 

nested = nested

and .hgsubstate containing 

3f68b2f93426b6966b604536037b5d325ba00741 nested

1.4. Update

Whenever newer Mercurial versions encounter this .hgsubstate file when updating your working directory, they'll attempt to pull the specified subrepos and update them to the appropriate state: 

$ cd ..
$ hg clone main main2
updating working directory
pulling subrepo nested
requesting all changes
adding changesets
adding manifests
adding file changes
added 1 changesets with 1 changes to 1 files
2 files updated, 0 files merged, 0 files removed, 0 files unresolved
$ cat main2/nested/foo
test

Subrepos may also contain their own subrepos and Mercurial will recurse as necessary.

1.5. Delete

To remove a subrepo from the parent repo, you must delete the subrepo definition from the .hgsub file at the top level of the parent repo. Once you do this, the subrepo tree will show up as a set of unknown files when you run hg status, and you can delete the files from the file system if you like.

2. Caveats

As this is a complex new feature, there are a number of rough edges. Most commands such as diff and status are currently completely unaware of subrepositories. Currently only update, commit, and push are subrepo-aware.

Further, there are a number of behaviors that are currently poorly defined or implemented:

3. Internals

The .hgsub format uses the hgrc config format. It reserves a source prefix of [ for future expansion (see below). Future expansion may also used named sections in this file.

The .hgsubstate format is similar to the tags format, in the form <revision><space><path>. This file is not intended to be hand-edited, but will accept any identifier format that Mercurial accepts. It is also automatically merged when necessary. It is separated from .hgsub to keep automatic updates from muddling that file and to keep .hgsub's history tidy. The combined state can be viewed with hg debugsub.

Internally, subrepo states are represented as a hash of path to (source, revision) pairs that combine the elements of the above two files. There is also a new subrepo object type that exposes a limited set of operations on a subrepo. Subrepos can be traversed like this: 

# check whether subrepos are dirty
c = repo['tip']
for s in c.substate:
    subrepo = c.sub[s]
    print s, subrepo.dirty()

4. To Do