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

> Pierre Habouzit <madcoder@debian.org> wrote:
> > diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt
> > index c4dbc2a..9cc8c2f 100644
> > --- a/Documentation/git-describe.txt
> > +++ b/Documentation/git-describe.txt
> > @@ -30,7 +30,8 @@ OPTIONS
> >  
> >  --tags::
> >  	Instead of using only the annotated tags, use any tag
> > -	found in `.git/refs/tags`.
> > +	found in `.git/refs/tags`. Though if an annotated tag is found in the
> > +	ancestry, it will always be preferred to lightweight tags.
> 
> As technically correct as the statement is, I read this and go
> "why do we even have --tags?".
> 
> If I read builtin-describe.c right we only honor --tags on an exact
> match, or if there are no annotated tags at all in the history.
> I wonder if docs like this aren't better for --tags:
> 
> --tags::
> 	If a lightweight tag exactly matches, output it.  If no
> 	annotated tag is found in the ancestry but a lightweight
> 	tag is found, output the lightweight tag.