Overlay Repositories

Hard links are deficient or unavailable on some file systems, so it'd be nice to be able to do cheap branching without them. One way would be to support overlay repositories, in which another repository is consulted if a revision isn't available locally. This could possibly also be used for a form of history rewriting where missing revisions are synthesized according to a policy. It could also be used as the basis for a partial history clone (eg a clone from revisions 1000-1500; see ShallowClone for another way to address this particular problem).

Mechanism:

• Add a [repository] parent path in hgrc.

• Create parent repo in localrepository init.

• Pass along parent revlogs in revlog constructors (via repo.file, changelog() and manifest())

• Create overlayindex and overlaymap types to unify the index and map of the revlog and its parent (shifting the offset and revision numbers in the local revlog according to the point it forked from the parent)

• Add an OVERLAY flag to revlogng. When this flag is set, the base entry of the first revision in the revlog doubles as the fork point from the parent.

• On commit, if no local revlog exists, find the base node of the parent in the parent repository. Copy from the base to the tip into the new revlog, with the offsets adjusted. Commit on top of that.

Deficiencies:

• As soon as a commit happens, any new file revisions are forked to the new repo. This is because the overlay deliberately ignores revisions with linkrevs past the fork point, since it doesn't know whether the linkrev points to the same changeset. One (slow) possibility would be to match up the linkrevs in the filelog to their corresponding entries in the changelog. Or we could consult the parent datafile for the contents of the change, but use the local index.

For partial history:

• Allow fork to take a revision argument

• Have clone fork the changelog and manifest at that revision, and each file in that revision's manifest
• pull up to desired revision
• Allow overlay to instantiate when the parent is missing
• gracefully handle missing revisions

Testing patch queue: http://hg.kublai.com/mercurial/patches/overlay/

Getting started with the patch queue

1. Clone crew:  hg clone http://hg.intevation.org/mercurial/crew overlay

2. Clone the patch queue into your new repository:  hg clone http://hg.kublai.com/mercurial/patches/overlay overlay/.hg/patches 

3. Push the patches onto crew (some are guarded and will not be applied -- this is fine):  hg qpush -a 

4. Make your crew repository runnable, eg with  cd overlay && make local 

5. Your new hg will have a --base option to clone:  overlay/hg clone --base tip overlay overlay-test 

That's it. You now have an overlay repository.