mercurial - rough notes on creating a 'super' repository

In Mercurial, one way to share code amongst projects, is to create a 'super' repository for each project that wants to use common code.

You then have the common code in one or more Mercurial repositories.
You re-use the repositories, as sub repositories of what I call 'super' repositories.

The 'super' repository only contains 1 file .hgsub which tells Mercurial which sub repositories to pull/push.

Here are some rough notes on creating a Hg super repository:

1. create a directory for the new super repository
mkdir hg_PRS_with_Common
cd hg_PRS_with_Common

2. create a file .hgsub
echo # > .hgsub
The file should have contents like this, where the values are simply the names of the sub repositories (the top level directory of each repository that shows the green Hg icon)
hg_OdinCommon = hg_OdinCommon
hg_PRS_main = hg_PRS_main

3. copy the sub repositories to the appropriate sub directory.
For example, hg_OdinCommon should be in the subdirectory hg_OdinCommon (and not intermediate directories)


C:\shared\hg_PRS_with_OdinCommon>tree /f | more
Folder PATH listing for volume OS
Volume serial number is BCE0-FD4B
C:.
│   .hgsub
│   .hgsubstate
│   fetch_all.bat
│
├───.hg
│   │   00changelog.i
│   │   dirstate

.....
.....



├───hg_OdinCommon
│   ├───.hg
│   │   │   00changelog.i
│   │   │   branch
│   │   │   dirstate
│   │   │   hgrc
│   │   │   requires
│   │   │   thgstatus
│   │   │

.....
.....


└───hg_PRS_main
    │   .hgignore
    │
    ├───.hg
    │   │   00changelog.i
    │   │   branch
    │   │   dirstate
    │   │   hgrc
    │   │   requires
    │   │   thgstatus


4. only now should you create the new super-repo:
hg init

hg add

hg ci -m"creating new super repo"

5. test the new super repo, by opening a cmd line at a new location, and cloning the super repo

hg clone ...\super-repo

you should get a full copy of all of the sub-repos.

hg commands + sub-repos
the following commands work automagically from the super-repo:
hg fetch
hg pull

other commands have a special -subrepo switch:
hg diff --subrepo

hg st --subrepo


and hg ci is different again!
hg ci --subrepos


the official documentation:  http://mercurial.selenic.com/wiki/Subrepository