git-describe doesn't show the most recent tag

git-describe doesn't show the most recent tag

[Erez Zilber]

Hi,

I'm trying to run git-describe on the open-iscsi git tree
(git://git.kernel.org/pub/scm/linux/kernel/git/mnc/open-iscsi.git):

[erez.zilber@erez-lx:/tmp/open-iscsi.git]$ git-branch -a
* master
  origin/2.0-869-bugfix
  origin/HEAD
  origin/bnx2i
  origin/cxgb3i
  origin/master
[erez.zilber@erez-lx:/tmp/open-iscsi.git]$ git-describe
2.0-868-rc1-81-g31c9d42

However, there are newer tags than 2.0-868-rc1:
[erez.zilber@erez-lx:/tmp/open-iscsi.git]$ git-tag
2.0-868-rc1
2.0-869
2.0-869-rc2
2.0-869-rc3
2.0-869-rc4
2.0-869.1
2.0-869.2
2.0-870-rc1

>From what I see in the man page "git-describe - Show the most recent
tag that is reachable from a commit". In this repository, it doesn't
look like that...

Now, I switch to the "2.0-869-bugfix" branch:
[erez.zilber@erez-lx:/tmp/open-iscsi.git]$ git-checkout -b
2.0-869-bugfix origin/2.0-869-bugfix
Branch 2.0-869-bugfix set up to track remote branch
refs/remotes/origin/2.0-869-bugfix.
Switched to a new branch "2.0-869-bugfix"

and running again git-describe:
[erez.zilber@erez-lx:/tmp/open-iscsi.git]$ git-describe
2.0-868-rc1-33-g81133dd

Only if I use the --tags flag, I get what I expected:
[erez.zilber@erez-lx:/tmp/open-iscsi.git]$ git-describe --tags
2.0-869.2

Why is this happening?

Thanks,
Erez

Re: git-describe doesn't show the most recent tag

[Pierre Habouzit]

[-- Attachment #1: Type: text/plain, Size: 440 bytes --]

On Sun, Sep 28, 2008 at 01:48:42PM +0000, Erez Zilber wrote:
> Why is this happening?

       --tags
           Instead of using only the annotated tags, use any tag found in
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
           .git/refs/tags.

-- 
·O·  Pierre Habouzit
··O                                                madcoder@debian.org
OOO                                                http://www.madism.org

[-- Attachment #2: Type: application/pgp-signature, Size: 197 bytes --]

Re: git-describe doesn't show the most recent tag

[Erez Zilber]

On Sun, Sep 28, 2008 at 4:55 PM, Pierre Habouzit <madcoder@debian.org> wrote:
> On Sun, Sep 28, 2008 at 01:48:42PM +0000, Erez Zilber wrote:
>> Why is this happening?
>
>       --tags
>           Instead of using only the annotated tags, use any tag found in
>           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>           .git/refs/tags.
>

I'm not sure that I understand the difference between tags and annotated tags.

Anyway, if I move to the master branch, I see the following tags:

[erez.zilber@erez-lx:/tmp/open-iscsi.git]$ ls .git/refs/tags/
2.0-868-rc1  2.0-869  2.0-869.1  2.0-869.2  2.0-869-rc2  2.0-869-rc3
2.0-869-rc4  2.0-870-rc1
[erez.zilber@erez-lx:/tmp/open-iscsi.git]$ git-tag
2.0-868-rc1
2.0-869
2.0-869-rc2
2.0-869-rc3
2.0-869-rc4
2.0-869.1
2.0-869.2
2.0-870-rc1

However:
[erez.zilber@erez-lx:/tmp/open-iscsi.git]$ git-describe --tags
2.0-868-rc1-81-g31c9d42

I was expecting to see 2.0-870-rc1 here.

Erez

Re: git-describe doesn't show the most recent tag

[Pierre Habouzit]

[-- Attachment #1: Type: text/plain, Size: 2157 bytes --]

On Sun, Sep 28, 2008 at 02:29:21PM +0000, Erez Zilber wrote:
> On Sun, Sep 28, 2008 at 4:55 PM, Pierre Habouzit <madcoder@debian.org> wrote:
> > On Sun, Sep 28, 2008 at 01:48:42PM +0000, Erez Zilber wrote:
> >> Why is this happening?
> >
> >       --tags
> >           Instead of using only the annotated tags, use any tag found in
> >           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> >           .git/refs/tags.
> >
> 
> I'm not sure that I understand the difference between tags and annotated tags.

  a lightweight tag is just a reference. an annotated tag has a message
associated. Usually tags are meant as local help, whereas annotated tags
are the ones pushed to the repositories and that never change. That's
why many tools ignore non annotated tags by default unless you pass
--tags to them.

> Anyway, if I move to the master branch, I see the following tags:
> 
> [erez.zilber@erez-lx:/tmp/open-iscsi.git]$ ls .git/refs/tags/
> 2.0-868-rc1  2.0-869  2.0-869.1  2.0-869.2  2.0-869-rc2  2.0-869-rc3
> 2.0-869-rc4  2.0-870-rc1
> [erez.zilber@erez-lx:/tmp/open-iscsi.git]$ git-tag
> 2.0-868-rc1
> 2.0-869
> 2.0-869-rc2
> 2.0-869-rc3
> 2.0-869-rc4
> 2.0-869.1
> 2.0-869.2
> 2.0-870-rc1
> 
> However:
> [erez.zilber@erez-lx:/tmp/open-iscsi.git]$ git-describe --tags
> 2.0-868-rc1-81-g31c9d42
> 
> I was expecting to see 2.0-870-rc1 here.

  That's because master is not at -rc1 exactly, but some commits
afterwards. Please read the git-describe manpage fully, it's _really_
well explained:

       The command finds the most recent tag that is reachable from a commit.
       If the tag points to the commit, then only the tag is shown. Otherwise,
       it suffixes the tag name with the number of additional commits on top
       of the tagged object and the abbreviated object name of the most recent
       commit.


Which means that your master is 81 commits ahead of the exact 2.0-860-rc1 tag,
at sha1 31c9d42

-- 
·O·  Pierre Habouzit
··O                                                madcoder@debian.org
OOO                                                http://www.madism.org

[-- Attachment #2: Type: application/pgp-signature, Size: 197 bytes --]

Re: git-describe doesn't show the most recent tag

[Andreas Ericsson]

Erez Zilber wrote:
> On Sun, Sep 28, 2008 at 4:55 PM, Pierre Habouzit <madcoder@debian.org> wrote:
>> On Sun, Sep 28, 2008 at 01:48:42PM +0000, Erez Zilber wrote:
>>> Why is this happening?
>>       --tags
>>           Instead of using only the annotated tags, use any tag found in
>>           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>>           .git/refs/tags.
>>
> 
> I'm not sure that I understand the difference between tags and annotated tags.
> 

An annotated tag is one created with "git tag -a" or "git tag -s".
Other tags are considered "lightweight". They are supported for
creating immutable quick-and-dirty savepoints for private use,
while published tags are supposed to be annotated to give them
some extra weight.

You can use lightweight tags like normal tags (ie, and publish
them), but then some assumptions in git will not be correct and
you need to tell it so.

Btw, the default update hook prevents lightweight (unannotated)
tags from entering a repository you're pushing to, so this
assumption is not something that's unique to just "describe".

-- 
Andreas Ericsson                   andreas.ericsson@op5.se
OP5 AB                             www.op5.se
Tel: +46 8-230225                  Fax: +46 8-230231

Re: git-describe doesn't show the most recent tag

[Pierre Habouzit]

[-- Attachment #1: Type: text/plain, Size: 2103 bytes --]

On Sun, Sep 28, 2008 at 02:39:49PM +0000, Pierre Habouzit wrote:
> On Sun, Sep 28, 2008 at 02:29:21PM +0000, Erez Zilber wrote:
> > On Sun, Sep 28, 2008 at 4:55 PM, Pierre Habouzit <madcoder@debian.org> wrote:
> > > On Sun, Sep 28, 2008 at 01:48:42PM +0000, Erez Zilber wrote:
> > >> Why is this happening?
> > >
> > >       --tags
> > >           Instead of using only the annotated tags, use any tag found in
> > >           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > >           .git/refs/tags.
> > >
> > 
> > I'm not sure that I understand the difference between tags and annotated tags.
> 
>   a lightweight tag is just a reference. an annotated tag has a message
> associated. Usually tags are meant as local help, whereas annotated tags
> are the ones pushed to the repositories and that never change. That's
> why many tools ignore non annotated tags by default unless you pass
> --tags to them.
> 
> > Anyway, if I move to the master branch, I see the following tags:
> > 
> > [erez.zilber@erez-lx:/tmp/open-iscsi.git]$ ls .git/refs/tags/
> > 2.0-868-rc1  2.0-869  2.0-869.1  2.0-869.2  2.0-869-rc2  2.0-869-rc3
> > 2.0-869-rc4  2.0-870-rc1
> > [erez.zilber@erez-lx:/tmp/open-iscsi.git]$ git-tag
> > 2.0-868-rc1
> > 2.0-869
> > 2.0-869-rc2
> > 2.0-869-rc3
> > 2.0-869-rc4
> > 2.0-869.1
> > 2.0-869.2
> > 2.0-870-rc1
> > 
> > However:
> > [erez.zilber@erez-lx:/tmp/open-iscsi.git]$ git-describe --tags
> > 2.0-868-rc1-81-g31c9d42
> > 
> > I was expecting to see 2.0-870-rc1 here.

  Scratch my previous answer, I was confused with too many digits (868
vs 870). In fact looking at the code, if there is an annotated tag in
the ancestry, git describe will always prefer it to lightweight tags.

  the problem with lightweight tags is that they are meant to be moved,
hence are not really something you want to base on to chose a uuid
(which git-describe generates).


-- 
·O·  Pierre Habouzit
··O                                                madcoder@debian.org
OOO                                                http://www.madism.org

[-- Attachment #2: Type: application/pgp-signature, Size: 197 bytes --]

Re: git-describe doesn't show the most recent tag

[Erez Zilber]

On Sun, Sep 28, 2008 at 5:39 PM, Pierre Habouzit <madcoder@debian.org> wrote:
> On Sun, Sep 28, 2008 at 02:29:21PM +0000, Erez Zilber wrote:
>> On Sun, Sep 28, 2008 at 4:55 PM, Pierre Habouzit <madcoder@debian.org> wrote:
>> > On Sun, Sep 28, 2008 at 01:48:42PM +0000, Erez Zilber wrote:
>> >> Why is this happening?
>> >
>> >       --tags
>> >           Instead of using only the annotated tags, use any tag found in
>> >           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>> >           .git/refs/tags.
>> >
>>
>> I'm not sure that I understand the difference between tags and annotated tags.
>
>  a lightweight tag is just a reference. an annotated tag has a message
> associated. Usually tags are meant as local help, whereas annotated tags
> are the ones pushed to the repositories and that never change. That's
> why many tools ignore non annotated tags by default unless you pass
> --tags to them.

Thanks for the explanation.

>
>> Anyway, if I move to the master branch, I see the following tags:
>>
>> [erez.zilber@erez-lx:/tmp/open-iscsi.git]$ ls .git/refs/tags/
>> 2.0-868-rc1  2.0-869  2.0-869.1  2.0-869.2  2.0-869-rc2  2.0-869-rc3
>> 2.0-869-rc4  2.0-870-rc1
>> [erez.zilber@erez-lx:/tmp/open-iscsi.git]$ git-tag
>> 2.0-868-rc1
>> 2.0-869
>> 2.0-869-rc2
>> 2.0-869-rc3
>> 2.0-869-rc4
>> 2.0-869.1
>> 2.0-869.2
>> 2.0-870-rc1
>>
>> However:
>> [erez.zilber@erez-lx:/tmp/open-iscsi.git]$ git-describe --tags
>> 2.0-868-rc1-81-g31c9d42
>>
>> I was expecting to see 2.0-870-rc1 here.
>
>  That's because master is not at -rc1 exactly, but some commits
> afterwards. Please read the git-describe manpage fully, it's _really_
> well explained:
>
>       The command finds the most recent tag that is reachable from a commit.
>       If the tag points to the commit, then only the tag is shown. Otherwise,
>       it suffixes the tag name with the number of additional commits on top
>       of the tagged object and the abbreviated object name of the most recent
>       commit.
>
>
> Which means that your master is 81 commits ahead of the exact 2.0-860-rc1 tag,
> at sha1 31c9d42

I read that, but I still don't understand what happens in the open-iscsi tree:

[erez.zilber@erez-lx:/tmp/open-iscsi.git]$ cat .git/refs/tags/2.0-870-rc1
5e80c8167c112687ae7b30b1e40af6f03088c56c

The head is 12 commits from the 2.0-870-rc1 tag. Therefore, I expected
to see something like 2.0-870-rc1-12-some_hash (not
2.0-868-rc1-81-g31c9d42).

Erez

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

[Pierre Habouzit]

[-- Attachment #1: Type: text/plain, Size: 714 bytes --]

Signed-off-by: Pierre Habouzit <madcoder@debian.org>
---
 Documentation/git-describe.txt |    3 ++-
 1 files changed, 2 insertions(+), 1 deletions(-)

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.
 
 --contains::
 	Instead of finding the tag that predates the commit, find
-- 
1.6.0.2.516.g12936.dirty

[-- Attachment #2: Type: application/pgp-signature, Size: 197 bytes --]

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

[Shawn O. Pearce]

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.

?

-- 
Shawn.

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

[Pierre Habouzit]

[-- Attachment #1: Type: text/plain, Size: 1293 bytes --]

On Mon, Sep 29, 2008 at 03:01:27PM +0000, Shawn O. Pearce wrote:
> 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.

sounds better indeed.
-- 
·O·  Pierre Habouzit
··O                                                madcoder@debian.org
OOO                                                http://www.madism.org

[-- Attachment #2: Type: application/pgp-signature, Size: 197 bytes --]

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

[Uwe Kleine-König]

Hello,

On Mon, Sep 29, 2008 at 08:01:27AM -0700, Shawn O. Pearce wrote:
> --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.
IMHO --tags should behave as Erez expected (because it's what I
expected, too).  As --tags currently behaves it's only usable in very
rare cases (most of the time it only makes a difference on repos without
any annotated tag).

When do you pass --tags?  Only if a lightweight tag is OK for an answer.
And then I would prefer a "near" lightweight tag to a "farer" annotated
one.

Best regards
Uwe

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

[Andreas Ericsson]

Uwe Kleine-König wrote:
> Hello,
> 
> On Mon, Sep 29, 2008 at 08:01:27AM -0700, Shawn O. Pearce wrote:
>> --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.
> IMHO --tags should behave as Erez expected (because it's what I
> expected, too).  As --tags currently behaves it's only usable in very
> rare cases (most of the time it only makes a difference on repos without
> any annotated tag).
> 
> When do you pass --tags?  Only if a lightweight tag is OK for an answer.
> And then I would prefer a "near" lightweight tag to a "farer" annotated
> one.
> 

The reason lightweight tags aren't considered is that they're often put
somewhere to just mark some refs one wants to keep around, or as a sort
of movable snapshot marker (we have "latest/build", "latest/tested" etc
as lightweight tags). It's nifty to use lw tags for that since they can't
be committed to by accident. That doesn't mean we want 'git describe' to
start outputting "latest-build" whenever we want to pull a version number
from it though.

This was especially true before the creation of "git stash" and the reflog,
but quite a lot of people still use them for similar purposes.

In short; "git describe" output stays the way it is, or things will start
unexpectedly breaking for quite a lot of people.

-- 
Andreas Ericsson                   andreas.ericsson@op5.se
OP5 AB                             www.op5.se
Tel: +46 8-230225                  Fax: +46 8-230231

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

[Shawn O. Pearce]

Uwe Kleine-KKKnig <ukleinek@strlen.de> wrote:
> On Mon, Sep 29, 2008 at 08:01:27AM -0700, Shawn O. Pearce wrote:
> > --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.
>
> IMHO --tags should behave as Erez expected (because it's what I
> expected, too).  As --tags currently behaves it's only usable in very
> rare cases (most of the time it only makes a difference on repos without
> any annotated tag).
> 
> When do you pass --tags?  Only if a lightweight tag is OK for an answer.
> And then I would prefer a "near" lightweight tag to a "farer" annotated
> one.

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.

--8<--
[WIP] Change meaning of --tags and --all

---
 builtin-describe.c |    6 ++----
 1 files changed, 2 insertions(+), 4 deletions(-)

diff --git a/builtin-describe.c b/builtin-describe.c
index ec404c8..fd54fec 100644
--- a/builtin-describe.c
+++ b/builtin-describe.c
@@ -15,8 +15,8 @@ static const char * const describe_usage[] = {
 };
 
 static int debug;	/* Display lots of verbose info */
-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 */
 static int longformat;
 static int abbrev = DEFAULT_ABBREV;
 static int max_candidates = 10;
@@ -112,8 +112,6 @@ static int compare_pt(const void *a_, const void *b_)
 {
 	struct possible_tag *a = (struct possible_tag *)a_;
 	struct possible_tag *b = (struct possible_tag *)b_;
-	if (a->name->prio != b->name->prio)
-		return b->name->prio - a->name->prio;
 	if (a->depth != b->depth)
 		return a->depth - b->depth;
 	if (a->found_order != b->found_order)
-- 
1.6.0.2.513.g6dbd


-- 
Shawn.

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

[Uwe Kleine-König]

Hi Shawn,

On Tue, Sep 30, 2008 at 12:04:49PM -0700, Shawn O. Pearce wrote:
> Uwe Kleine-KKKnig <ukleinek@strlen.de> wrote:
> > On Mon, Sep 29, 2008 at 08:01:27AM -0700, Shawn O. Pearce wrote:
> > > --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.
> >
> > IMHO --tags should behave as Erez expected (because it's what I
> > expected, too).  As --tags currently behaves it's only usable in very
> > rare cases (most of the time it only makes a difference on repos without
> > any annotated tag).
> > 
> > When do you pass --tags?  Only if a lightweight tag is OK for an answer.
> > And then I would prefer a "near" lightweight tag to a "farer" annotated
> > one.
> 
> 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.

> -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.

Best regards and thanks,
Uwe

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

[Shawn O. Pearce]

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.

[RFC PATCH] describe: Make --tags and --all match lightweight tags more often

[Shawn O. Pearce]

If the caller supplies --tags they want the lightweight, unannotated
tags to be searched for a match.  If a lightweight tag is closer
in the history, it should be matched, even if an annotated tag is
reachable further back in the commit chain.

The same applies with --all when matching any other type of ref.

Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
---

 This come out of the discussions earlier last week, where folks
 were confused about the meaning of --tags and wanted to see it
 behave as they expected, which was to match the nearest tag,
 no matter its "type".

 The code is unchanged from what I sent out before, but now it has
 updated test vectors and a commit message.

 Thoughts?

 builtin-describe.c  |    6 ++----
 t/t6120-describe.sh |    8 ++++----
 2 files changed, 6 insertions(+), 8 deletions(-)

diff --git a/builtin-describe.c b/builtin-describe.c
index ec404c8..fd54fec 100644
--- a/builtin-describe.c
+++ b/builtin-describe.c
@@ -15,8 +15,8 @@ static const char * const describe_usage[] = {
 };
 
 static int debug;	/* Display lots of verbose info */
-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 */
 static int longformat;
 static int abbrev = DEFAULT_ABBREV;
 static int max_candidates = 10;
@@ -112,8 +112,6 @@ static int compare_pt(const void *a_, const void *b_)
 {
 	struct possible_tag *a = (struct possible_tag *)a_;
 	struct possible_tag *b = (struct possible_tag *)b_;
-	if (a->name->prio != b->name->prio)
-		return b->name->prio - a->name->prio;
 	if (a->depth != b->depth)
 		return a->depth - b->depth;
 	if (a->found_order != b->found_order)
diff --git a/t/t6120-describe.sh b/t/t6120-describe.sh
index 16cc635..e6c9e59 100755
--- a/t/t6120-describe.sh
+++ b/t/t6120-describe.sh
@@ -91,10 +91,10 @@ check_describe D-* HEAD^^
 check_describe A-* HEAD^^2
 check_describe B HEAD^^2^
 
-check_describe A-* --tags HEAD
-check_describe A-* --tags HEAD^
-check_describe D-* --tags HEAD^^
-check_describe A-* --tags HEAD^^2
+check_describe c-* --tags HEAD
+check_describe c-* --tags HEAD^
+check_describe e-* --tags HEAD^^
+check_describe c-* --tags HEAD^^2
 check_describe B --tags HEAD^^2^
 
 check_describe B-0-* --long HEAD^^2^
-- 
1.6.0.2.687.g8544f

-- 
Shawn.

Re: [RFC PATCH] describe: Make --tags and --all match lightweight tags more often

[Pierre Habouzit]

[-- Attachment #1: Type: text/plain, Size: 1429 bytes --]

On Fri, Oct 10, 2008 at 04:59:52PM +0000, Shawn O. Pearce wrote:
> If the caller supplies --tags they want the lightweight, unannotated
> tags to be searched for a match.  If a lightweight tag is closer
> in the history, it should be matched, even if an annotated tag is
> reachable further back in the commit chain.
> 
> The same applies with --all when matching any other type of ref.
> 
> Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
> ---
> 
>  This come out of the discussions earlier last week, where folks
>  were confused about the meaning of --tags and wanted to see it
>  behave as they expected, which was to match the nearest tag,
>  no matter its "type".
> 
>  The code is unchanged from what I sent out before, but now it has
>  updated test vectors and a commit message.
> 
>  Thoughts?

I would like to see an enhanced information in the documentation so that
people remember that lightweight tags are not meant to be constant over
time and that's a bad idea to use them.

What the discussion showed, is that the people don't know about
annotated tags, and git-describe should have a stub of documentation
that points to git-tag(1) so that people learn about it.

Apart from that, it feels fine.

-- 
·O·  Pierre Habouzit
··O                                                madcoder@debian.org
OOO                                                http://www.madism.org

[-- Attachment #2: Type: application/pgp-signature, Size: 197 bytes --]

Re: [RFC PATCH] describe: Make --tags and --all match lightweight tags more often

[Junio C Hamano]

Pierre Habouzit <madcoder@debian.org> writes:

> I would like to see an enhanced information in the documentation so that
> people remember that lightweight tags are not meant to be constant over
> time and that's a bad idea to use them.
>
> What the discussion showed, is that the people don't know about
> annotated tags, and git-describe should have a stub of documentation
> that points to git-tag(1) so that people learn about it.
>
> Apart from that, it feels fine.

The primary mode of operation without --tags of "describe" is about coming
up with version numbers, and as such, it should try to base its output on
immutable anchors as much as possible.  For that reason, I think it should
use "tag " line from the tag object, not the name of the ref, to describe
the committish.  They should match (otherwise fsck would say something
about it) in practice, though...

The patch is about --tags, which is not about such a strict "version
number" generation, but about "come up with a closest ref", so in that
light it feels perfectly fine.

Re: [RFC PATCH] describe: Make --tags and --all match lightweight tags more often

[Andreas Ericsson]

Shawn O. Pearce wrote:
> If the caller supplies --tags they want the lightweight, unannotated
> tags to be searched for a match.  If a lightweight tag is closer
> in the history, it should be matched, even if an annotated tag is
> reachable further back in the commit chain.
> 
> The same applies with --all when matching any other type of ref.
> 

In 99% of the cases, "--all" will then give back the currently
checked out branch unless a revision is specified, right?

-- 
Andreas Ericsson                   andreas.ericsson@op5.se
OP5 AB                             www.op5.se
Tel: +46 8-230225                  Fax: +46 8-230231

Re: [RFC PATCH] describe: Make --tags and --all match lightweight tags more often

[Shawn O. Pearce]

Andreas Ericsson <ae@op5.se> wrote:
> Shawn O. Pearce wrote:
>> If the caller supplies --tags they want the lightweight, unannotated
>> tags to be searched for a match.  If a lightweight tag is closer
>> in the history, it should be matched, even if an annotated tag is
>> reachable further back in the commit chain.
>>
>> The same applies with --all when matching any other type of ref.
>>
>
> In 99% of the cases, "--all" will then give back the currently
> checked out branch unless a revision is specified, right?

Yup.

`git describe --all` or `git describe --all HEAD`

would kick back the current branch you have checked out, assuming
you have a real branch under refs/heads and not some detached HEAD.

IMHO, that's what the user asked for.

-- 
Shawn.

Re: [RFC PATCH] describe: Make --tags and --all match lightweight tags more often

[Andreas Ericsson]

Shawn O. Pearce wrote:
> Andreas Ericsson <ae@op5.se> wrote:
>> Shawn O. Pearce wrote:
>>> If the caller supplies --tags they want the lightweight, unannotated
>>> tags to be searched for a match.  If a lightweight tag is closer
>>> in the history, it should be matched, even if an annotated tag is
>>> reachable further back in the commit chain.
>>>
>>> The same applies with --all when matching any other type of ref.
>>>
>> In 99% of the cases, "--all" will then give back the currently
>> checked out branch unless a revision is specified, right?
> 
> Yup.
> 
> `git describe --all` or `git describe --all HEAD`
> 
> would kick back the current branch you have checked out, assuming
> you have a real branch under refs/heads and not some detached HEAD.
> 
> IMHO, that's what the user asked for.
> 

True. I think this will raise questions of its usability though,
in particular if it considers remote branches too.

Otoh, I've never seen the use for "git describe --all" earlier
either, so I guess I think differently from those who want this
feature.

-- 
Andreas Ericsson                   andreas.ericsson@op5.se
OP5 AB                             www.op5.se
Tel: +46 8-230225                  Fax: +46 8-230231

Re: [RFC PATCH] describe: Make --tags and --all match lightweight tags more often

[Uwe Kleine-König]

On Fri, Oct 10, 2008 at 09:59:52AM -0700, Shawn O. Pearce wrote:
> If the caller supplies --tags they want the lightweight, unannotated
> tags to be searched for a match.  If a lightweight tag is closer
> in the history, it should be matched, even if an annotated tag is
> reachable further back in the commit chain.
> 
> The same applies with --all when matching any other type of ref.
> 
> Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
> ---
> 
>  This come out of the discussions earlier last week, where folks
>  were confused about the meaning of --tags and wanted to see it
>  behave as they expected, which was to match the nearest tag,
>  no matter its "type".
> 
>  The code is unchanged from what I sent out before, but now it has
>  updated test vectors and a commit message.
> 
>  Thoughts?
As I already told earlier, this is exactly how I would expect it.

>  static int debug;	/* Display lots of verbose info */
> -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 */
Maybe the last comment should better read:

	/* allow lightweight tags */

?  Apart from this one nitpick:

Acked-By: Uwe Kleine-König <ukleinek@strlen.de>

Thanks
Uwe

Re: [RFC PATCH] describe: Make --tags and --all match lightweight tags more often

[Shawn O. Pearce]

Junio C Hamano <gitster@pobox.com> wrote:
> 
> The primary mode of operation without --tags of "describe" is about coming
> up with version numbers, and as such, it should try to base its output on
> immutable anchors as much as possible.  For that reason, I think it should
> use "tag " line from the tag object, not the name of the ref, to describe
> the committish.  They should match (otherwise fsck would say something
> about it) in practice, though...

FWIW the use of "tag " line for an annotated tag being output is what
212945d4 (Teach git-describe to verify annotated tag names before
output) was all about.  That has been in tree since v1.5.5-rc0~86^2.

So we already are doing (have been doing) exactly what you are
asking for.

Or did I misunderstand you?

-- 
Shawn.

[PATCH v2] describe: Make --tags and --all match lightweight tags more often

[Shawn O. Pearce]

If the caller supplies --tags they want the lightweight, unannotated
tags to be searched for a match.  If a lightweight tag is closer
in the history, it should be matched, even if an annotated tag is
reachable further back in the commit chain.

The same applies with --all when matching any other type of ref.

Signed-off-by: Shawn O. Pearce <spearce@spearce.org>
Acked-By: Uwe Kleine-K�nig <ukleinek@strlen.de>
---
 Changes since v1 of this patch:

 - Documentation updates were added.
 - Comment for "tags" flag modified per Uwe's suggestion.

 Documentation/git-describe.txt |    9 +++++++--
 builtin-describe.c             |    6 ++----
 t/t6120-describe.sh            |    8 ++++----
 3 files changed, 13 insertions(+), 10 deletions(-)

diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt
index c4dbc2a..40e061f 100644
--- a/Documentation/git-describe.txt
+++ b/Documentation/git-describe.txt
@@ -18,6 +18,9 @@ shown.  Otherwise, it suffixes the tag name with the number of
 additional commits on top of the tagged object and the
 abbreviated object name of the most recent commit.
 
+By default (without --all or --tags) `git describe` only shows
+annotated tags.  For more information about creating annoated tags
+see the -a and -s options to linkgit:git-tag[1].
 
 OPTIONS
 -------
@@ -26,11 +29,13 @@ OPTIONS
 
 --all::
 	Instead of using only the annotated tags, use any ref
-	found in `.git/refs/`.
+	found in `.git/refs/`.  This option enables matching
+	any known branch, remote branch, or lightweight tag.
 
 --tags::
 	Instead of using only the annotated tags, use any tag
-	found in `.git/refs/tags`.
+	found in `.git/refs/tags`.  This option enables matching
+	a lightweight (non-annotated) tag.
 
 --contains::
 	Instead of finding the tag that predates the commit, find
diff --git a/builtin-describe.c b/builtin-describe.c
index ec404c8..d2cfb1b 100644
--- a/builtin-describe.c
+++ b/builtin-describe.c
@@ -15,8 +15,8 @@ static const char * const describe_usage[] = {
 };
 
 static int debug;	/* Display lots of verbose info */
-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;	/* Allow lightweight tags */
 static int longformat;
 static int abbrev = DEFAULT_ABBREV;
 static int max_candidates = 10;
@@ -112,8 +112,6 @@ static int compare_pt(const void *a_, const void *b_)
 {
 	struct possible_tag *a = (struct possible_tag *)a_;
 	struct possible_tag *b = (struct possible_tag *)b_;
-	if (a->name->prio != b->name->prio)
-		return b->name->prio - a->name->prio;
 	if (a->depth != b->depth)
 		return a->depth - b->depth;
 	if (a->found_order != b->found_order)
diff --git a/t/t6120-describe.sh b/t/t6120-describe.sh
index 16cc635..e6c9e59 100755
--- a/t/t6120-describe.sh
+++ b/t/t6120-describe.sh
@@ -91,10 +91,10 @@ check_describe D-* HEAD^^
 check_describe A-* HEAD^^2
 check_describe B HEAD^^2^
 
-check_describe A-* --tags HEAD
-check_describe A-* --tags HEAD^
-check_describe D-* --tags HEAD^^
-check_describe A-* --tags HEAD^^2
+check_describe c-* --tags HEAD
+check_describe c-* --tags HEAD^
+check_describe e-* --tags HEAD^^
+check_describe c-* --tags HEAD^^2
 check_describe B --tags HEAD^^2^
 
 check_describe B-0-* --long HEAD^^2^
-- 
1.6.0.2.706.g340fc

-- 
Shawn.

Re: [PATCH v2] describe: Make --tags and --all match lightweight tags more often

[Santi Béjar]

> diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt
> index c4dbc2a..40e061f 100644
> --- a/Documentation/git-describe.txt
> +++ b/Documentation/git-describe.txt

[...]

> +annotated tags.  For more information about creating annoated tags

s/annoated/annotated/

Santi

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

[Uwe Kleine-König]

Hi Shawn,

On Tue, Sep 30, 2008 at 03:26:46PM -0700, Shawn O. Pearce wrote:
> 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.
Right, and previously `git describe` didn't differ from `git describe
--tags` in the presence of at least one annotated tag.  This is the main
reason for me to believe that this breakage doesn't hurt that much.

>            Especially after the 1.6 "dashless" change...
I didn't get why the "dashless" change is relevant here.  IMHO this one
is/was harder for the user because it changed every command, and they
had to start using bash completion if they didn't before.  This one
should only hurt the users of "git describe --tags", and I assume there
are not that many.  Still more as the documentation describes the
behaviour the patch implements.

Best regards
Uwe