|
Size: 3396
Comment: added mention of lattesttag and latesttagdistance
|
Size: 2594
Comment: Changed the documentation of the Nearest extension to explain its rewrite
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 4: | Line 4: |
| Line 12: | Line 11: |
| Line 15: | Line 13: |
| By default, tags are searched backward in history, but using the `--contains` option will make it search forward. It answers the following questions:<<BR>> * On which tag this changeset is based on ? '''(without `--contains`)''' * Which tag will include / contain this changeset ? '''(with `--contains`)''' |
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. |
| Line 19: | Line 15: |
| The tags are searched by date, so that the nearest tag in time will be reported. However, the `--all` option will make the extension search the first tag on all possible branches. | 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. |
| Line 22: | Line 23: |
| Enable the extension by adding following lines to your configuration file (~/.hgrc): | |
| Line 23: | Line 25: |
| Enable the extension by adding following lines to your configuration file (~/.hgrc): | |
| Line 29: | Line 30: |
| === Versions === /!\ The extension have been completely rewritten with a completely new 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. |
|
| Line 30: | Line 40: |
| {{{ 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: |
|
| Line 32: | Line 46: |
| hg nearest [--contains] [--all] [--match pattern] [--format outputspec] [--tagsep char] REV ... | $ hg nearest 9612 previous tag: 1.3.1 @9216 (-250 [default]) next tag: 1.4 @9869 (+202 [default]) |
| Line 35: | Line 51: |
| If no argument is provided, it returns the nearest tag on which the working directory is based on: {{{ $ hg nearest 1.1+55 }}} |
The `--match` option can be used to filter the tags. For instance to find a 0.9.x tag: |
| Line 41: | Line 53: |
| Which versions will include revision 5500: {{{ $ hg nearest --contains --all 5500 1.0-727 1.0.1-633 1.1-1361 }}} Note that even though there are more commits to 1.0, it is reported first due to its older date. The `--match` option can be used to filter the tags. For instance to find a 0.9.x tag: |
|
| Line 56: | Line 58: |
| 0.9.5+652 | previous tag: 0.9.5 @5472 (-4422 [default]) |
| Line 59: | Line 61: |
| === Output customization === The default output format is "tag+dist", and "tag-dist" with the `--contains` option, where "dist" is the longest path to the tag. The format output can be customized using the `--format` option with the following rules: || %% || literal "%" character || || %r || the revision of the given changeset || || %h || the short changeset hash of the given changeset || || %H || the full changeset hash of the given changeset || || %i || the date of the given changeset || || %I || the date and time of the given changeset || || %d || the longest path from the found tag || || %t || the first tag of the found changeset || || %T || all the tags of the found changeset || || %s || the revision of the found tag || || %x || the short changeset hash of the found tag || || %X || the full changeset hash of the found tag || || %u || the date of the found tag || || %U || the date and time of the found tag || You can use `\n` or `\t` to include special characters. You can use the following section in the configuration file to save the format: {{{ [nearest] format = this is the generic format for backward and forward if they are not set below format.forward = format specialized for --contains format.backward = format specialized without --contains format.exact = format in case of exact match tagsep = string that separates tags for the %T format }}} |
![/!\](/moin-static/modernized/img/alert.png "/!\"){kind=small}
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)
Download site: http://code.google.com/p/nearest-hgext/source/checkout
Overview
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.
Configuration
Enable the extension by adding following lines to your configuration file (~/.hgrc):
[extensions] nearest=/path/to/nearest.py
Versions
The extension have been completely rewritten with a completely new 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.
Usage
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])