Status: in progress, MartinGeisler is working on it

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

Contents

  1. The Problem
  2. The solution
    1. The hgrc File
    2. The .hg/subpaths File
  3. Distribution

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 will be two ways to define the mapping: one for the user to control, and one controlled by the project administrator.

The hgrc File

A new configuration section called subpaths is introduced. This is where the user can remap the paths. 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 left-hand sides specify a regular expression to search for and the right-hand side specifies a replacement string. The replacement string can use backreferences for more complex situations such as this example 

[subpaths]
http://server/(.*)-hg/ = http://hg.server/\1/

which replaces http://server/foo-hg/ with http://hg.server/foo/. Only the first matching pattern is used to avoid situations where a subsequent pattern accidentally matches an earlier replacement.

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.