Re: [PATCH] doc: enhance git describe --tags help

["Shawn O. Pearce" <spearce@spearce.org>]

Uwe Kleine-KKKnig <ukleinek@strlen.de> wrote:
> On Tue, Sep 30, 2008 at 12:04:49PM -0700, Shawn O. Pearce wrote:
> > Uwe Kleine-KKKnig <ukleinek@strlen.de> wrote:
> > >
> > > IMHO --tags should behave as Erez expected (because it's what I
> > > expected, too).
> > 
> > I don't disagree.  I've been tempted to write a patch to change the
> > behavior of git-describe so that --tags and --all control what names
> > are inserted into the candidate list, but don't control the ordering
> > of their selection.
> > 
> > I think this is all that is needed to make the behavior do what you
> > and Erez expected.  But its a pretty big change in the results if
> > you are passing in --all or --tags today.
>
> But it matches the documentation, and the expectations of Erez, me and
> (at least initially) Pierre.
> 
> My POV is still:  If you pass --all or --tags you have to be able to
> handle if a lw tag is used in the answer.

I was agreeing with you.  I've long felt that the --tags and --all
behavior of git-describe was wrong.  But something in the back of
my mind tells me Junio felt otherwise.

Its a change in behavior.  Today users are getting annotated tags
back from `git describe --tags` even if lightweight tags are closer.
Once this code change is in they'll start to get lightweight tags.

Previously `git describe --tags` never gave a lightweight tag if
there was at least one annotated tag in the history.  Now it will
start to give the lightweight tags.  Some users may see that as a
breakage.  Especially after the 1.6 "dashless" change...

> > -static int all;	/* Default to annotated tags only */
> > -static int tags;	/* But allow any tags if --tags is specified */
> > +static int all;	/* Any valid ref can be used */
> > +static int tags;	/* Either lightweight or annotated tags */
>
> Mmmh, IMHO the comment for tags is misleading, its either annotated only
> or both.

Oh, yes, right.  Thanks.  I'll clean it up.

-- 
Shawn.