[ANNOUNCE] hg describe extension

[Michael Kleehammer]

On Wed, Jul 30, 2008 at 10:52 AM, Matt Mackall <mpm at selenic.com> wrote:
> That's an interesting notion. Perhaps something similar should be built
> into the hg id command, like a --nearest:
>
> $ hg id --nearest
> (1.0.1)

I think it would be very handy, but there are two other things I think people
would need along with it:

 1) The number of commits since the tag.
 2) Control over how tags from other branches are picked up.

Item (1) is pretty easy:

 $ hg id --nearest
 1.0.1

 $ hg id --nearest
 1.0.1-8

My goal here is have a unique, short name for tar files, installers,
etc. without requiring that every release be tagged.  A lot of people use
nightly builds, QA builds, etc. and tagging everything would be way
too much trouble.  The changeset ID is great, but I also need a shorter
name based on a tag.

 project-1.0.1-8.tgz

I include optional repository and branch names if they are not official ones.
(Not needed from 'id', but relevant to the use case.):

 project-mkleehammer-1.0.1-8.tgz         (unofficial repo)

 project-feature-1.0.1-8.tgz             (non-default branch)

 project-mkleehammer-feature-1.0.1-8.tgz (both)

These names also go into the logs, along with the changeset ID, so we
can quickly
see where the code came from.

Because the output is expected to be consumed by scripts, we would
want to bring over
the --long option which always prints the tag even on an exact match
(1.0.1-0) and
maybe the --spaces option which separates the items by spaces in case tags have
dashes.  (Can they?)

Finally, the current version adds the abbreviated changeset id if
there isn't an exact
match which makes it easy to identify the exact changeset; an idea copied from
git describe:

  $hg id --nearest
  1.0.1-8-c68f84448012


Item (2) is helpful in cases where branches have been merged and there are tags
on both branches:

The --prefer-branch option will prefer the nearest on-branch tag over
closer ones.

The --require-branch option will only consider tags on the same branch.

If we can also get these 2 items into identify, I'd be very happy to
switch to it.