/!\ Note: a subset of the functionality of this extension is now available in the  {latesttag}  and  {latesttagdistance}  template keywords.

Nearest Extension

This extension is not distributed with Mercurial.

Author: Gilles Moris (morisgi)

Repository: https://nearest-hgext.googlecode.com/hg/


The goal of the nearest mercurial extension is to find the nearest tag(s) from a given changeset, either backward or forward in the changesets history tree.

By default, tags are searched in both directions, except if overriden by a command option. If no revision is given, then the working directory revision is assumed.

Tags are searched on all branches, ordered by dates. However, tags that are ancestors (resp. descendants) of the first tags found are not reported, i.e. there should be no merge between the tags and the searched root revision.

Tags can be filtered by named branch, or using regexp or shell matching patterns. Case are ignored for pattern matching.

In addition, the latest version adds the nearest tags at the end of the summary command.


Enable the extension by adding following lines to your configuration file (~/.hgrc):



/!\ The extension have been completely rewritten with a completely new and incompatible command line interface on June 1st 2010.

The first implementation was made to mimic 'git describe' and to provide version numbers for package. This part is pretty outdated since the introduction of the {latesttag} keyword in hg 1.4. Note also that this first implementation did not return correct distance to the tags in some cases.

The second implementation has broken the CLI to beeasier to use, with no option needed most of the time. Also several features of the first implementation have been dropped. Those were normally only needed for the latest tags. It is compatible from hg 1.1.


hg nearest hg nearest [-pn1l] [-b branch] [REV]

If no argument is provided, it returns the nearest tags backward and forward in hitory, from the revision on which the working directory is based on:

$ hg nearest 9612
previous tag: 1.3.1 @9216 (-250 [default])
next tag: 1.4 @9869 (+202 [default])

The --match option can be used to filter the tags. For instance to find a 0.9.x tag:

# The "*" replace any sequence of character
# The "?" replaces a single character
# To match characters "a", "b" or "c", use [abc]
$ hg nearest --match "0.9.*"
previous tag: 0.9.5 @5472 (-4422 [default])


NearestExtension (last edited 2011-04-03 10:32:41 by GillesMoris)