Remapping Clone URLs in .hgsub Files

Status: draft

This plan proposes a scheme for remapping the URLs used when cloning and pulling subrepos.

The Problem

Consider a .hgsub file that reads

libs/libfoo = http://hg.company.com/libraries/libfoo

Now imagine that the company is bought by another company and that the Mercurial server changes its name. It could also happen that the repository is simply renamed because the server layout is reorganized. To handle this, one updates the .hgsub file to point to the new location of the repository.

This creates a problem when updating to old revisions: Mercurial will use the old version of the .hgsub file, the one that still refers to the old server, which is long gone.

A solution to this would be to keep a remapping table around that lets users remap old URLs to new URLs.

The solution

The solution is to introduce a level of indirection, which allows the right side of entries in .hgsub to be interpreted with respect to revision-independent information. This allows entries in .hgsub to use "symbolic" names rather than fixed paths:

libs/foo = libfoo

With the application of the extra information, libfoo can be remapped to http://hg.company.com/libraries/libfoo.

This mechanism can also be used by people who have hard coded paths and now need to remap them because of repository reorganization. In that case, there will be no symbolic names, instead there will only be URLs and the remapping will work on URLs only.

There should be two different ways to provide this path remapping/expansion information:

The hgrc File

A new section called subpaths is introduced for hgrc files. Each entry maps the right side of an entry in .hgsub to a path. Example ~/.hgrc file:

[subpaths]
libfoo = http://hg.company.com/libraries/libfoo

The .hg/subpaths File

This is a new file that resides in the .hg directory of a repository. It is not version controlled. Entries are the same as for hgrc files except that there is no subpaths section header. Example .hg/subpaths file:

libfoo = http://hg.company.com/libraries/libfoo

If present, the subpaths file is used to remap subrepository paths. Mappings defined in hgrc files override those in the subpaths file.

Distribution

The entries in the subpaths file are propagated via the PushkeyConcept: the subpaths file is reproduced in clones of a repository and refreshed with every pull from the repository. The local subpaths file is completely overwritten with the entries obtained from the repository you pull from.

This allows the project manager to maintain the mappings in the subpaths file in a central repository and be sure that the entire team, which is perhaps distributed in different sites, is using the up-to-date mappings in their clones without having to set up some additional proocedure to synchronize hgrc files.

Teams can still override the subpaths file with their local hgrc files, as explained above.