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-lx:/tmp/open-iscsi.git]$ git-branch -a
* master
origin/2.0-869-bugfix
origin/HEAD
origin/bnx2i
origin/cxgb3i
origin/master
[***@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-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-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-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-lx:/tmp/open-iscsi.git]$ git-describe --tags
2.0-869.2

Why is this happening?

Thanks,
Erez

[Pierre Habouzit]

Post by Erez Zilber
Why is this happening?

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

[Erez Zilber]

Post by Erez Zilber

Post by Erez Zilber
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-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-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-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

[Pierre Habouzit]

Post by Erez Zilber

Post by Erez Zilber

Post by Erez Zilber
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.

Post by Erez Zilber
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
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
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

[Pierre Habouzit]

Post by Pierre Habouzit

Post by Erez Zilber

Post by Erez Zilber

Post by Erez Zilber
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.

Post by Erez Zilber
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
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
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).

[Pierre Habouzit]

Signed-off-by: Pierre Habouzit <***@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

[Shawn O. Pearce]

Post by Pierre Habouzit
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
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.

?

[Pierre Habouzit]

Post by Shawn O. Pearce

Post by Pierre Habouzit
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
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.
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.

[Uwe Kleine-König]

Hello,

Post by Shawn O. Pearce
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

[Andreas Ericsson]

Post by Uwe Kleine-König
Hello,
=20

Post by Shawn O. Pearce
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 with=

out

Post by Uwe Kleine-König
any annotated tag).
=20
When do you pass --tags? Only if a lightweight tag is OK for an answ=

er.

Post by Uwe Kleine-König
And then I would prefer a "near" lightweight tag to a "farer" annotat=

ed

Post by Uwe Kleine-König
one.
=20

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' t=
o
start outputting "latest-build" whenever we want to pull a version numb=
er
from it though.

This was especially true before the creation of "git stash" and the ref=
log,
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 sta=
rt
unexpectedly breaking for quite a lot of people.

--=20
Andreas Ericsson ***@op5.se
OP5 AB www.op5.se
Tel: [phone] Fax: [phone]

[Shawn O. Pearce]

Post by Uwe Kleine-König

Post by Shawn O. Pearce
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)

[Uwe Kleine-König]

Hi Shawn,

Post by Shawn O. Pearce

Post by Uwe Kleine-König

Post by Shawn O. Pearce
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.

Post by Shawn O. Pearce
-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

[Shawn O. Pearce]

Post by Uwe Kleine-König

Post by Shawn O. Pearce

Post by Uwe Kleine-König
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...

Post by Uwe Kleine-König

Post by Shawn O. Pearce
-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.

[Uwe Kleine-König]

Hi Shawn,

Post by Shawn O. Pearce
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.

Post by Shawn O. Pearce
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

[Erez Zilber]

Post by Pierre Habouzit

Post by Erez Zilber

Post by Erez Zilber

Post by Erez Zilber
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.

Post by Pierre Habouzit

Post by Erez Zilber
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
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
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_
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-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

[Andreas Ericsson]

Post by Erez Zilber

Post by Erez Zilber

Post by Erez Zilber
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".