threads / discuss / 47357

"git describe" documentation and behavior mismatch

Subject: "git describe" documentation and behavior mismatch

## tl;dr

6 messages between Nov 30, 2017 and Dec 15, 2017.

replies: 5people: 2as markdown or json

Daniel Knittl-Frank· Nov 30, 2017, 18:47 UTC · lore
Hi Git list,

the help page/manpage of the git describe command has an example with the --all flag which should prepend the ref namespace (tags/ or heads/):

Show 7 quoted lines
> With --all, the command can use branch heads as references, so the output shows the reference path as well:
>
>          [torvalds@g5 git]$ git describe --all --abbrev=4 v1.0.5^2
>          tags/v1.0.0-21-g975b
>
>          [torvalds@g5 git]$ git describe --all --abbrev=4 HEAD^
>          heads/lt/describe-7-g975b
Running the above commands in the git.git repository yields a different result:
>     $ git describe --all --abbrev=4 v1.0.5^2
>     v1.0.0-21-g975b3

No "reference path" to see. It is however shown, when the output is a branch name:

>     $ git describe --all --abbrev=4 origin/next
>     heads/next

Is this expected behavior? IOW is the documentation outdated or is the git describe command misbehaving?

Thanks, Daniel

-- 
typed with http://neo-layout.org
Daniel Knittl-Frank· Nov 30, 2017, 19:26 UTC · re: Daniel Knittl-Frank · lore

Re: "git describe" documentation and behavior mismatch

On Thu, Nov 30, 2017 at 7:47 PM, Daniel Knittl-Frank <knittl89@googlemail.com> wrote:

Show 15 quoted lines
> […]
>
> Running the above commands in the git.git repository yields a different result:
>
>>     $ git describe --all --abbrev=4 v1.0.5^2
>>     v1.0.0-21-g975b3
>
> No "reference path" to see. It is however shown, when the output is a
> branch name:
>
>>     $ git describe --all --abbrev=4 origin/next
>>     heads/next
>
> Is this expected behavior? IOW is the documentation outdated or is the
> git describe command misbehaving?

Bisecting history goes as far back as Feb 2008: commit 212945d4a85dfa172ea55ec73b1d830ef2d8582f

> Teach git-describe to verify annotated tag names before output

The warning mentioned in the commit message has since been gone. So I guess the documentation is outdated? Nobody has complained for the past 9 years, so we could call this a "feature" :)

An interesting fact (and intentional behavior?) is that describing a commit with only a lightweight tag will properly display the tags/ prefix. I assume this is because the annotated tags only store the tagname without any ref namespace, which is then picked up by git describe and displayed.

I will try to come up with a patch for the man page.
Daniel
-- 
typed with http://neo-layout.org
Junio C Hamano· Dec 3, 2017, 05:39 UTC · re: Daniel Knittl-Frank · lore

Re: "git describe" documentation and behavior mismatch

Daniel Knittl-Frank <knittl89@googlemail.com> writes:
Show 5 quoted lines
> An interesting fact (and intentional behavior?) is that describing a
> commit with only a lightweight tag will properly display the tags/
> prefix. I assume this is because the annotated tags only store the
> tagname without any ref namespace, which is then picked up by git
> describe and displayed.

I suspect that "see if the name recorded in the tag object matches the name of the ref that stores the tag after refs/tags/" code *is* not just verifying what it claims to (which may be good) but also unintentionally affecting the output (i.e. "--all" promises that the prefix tags/ should be shown). Perhaps the code needs to be fixed if that is the case.

Daniel Knittl-Frank· Dec 11, 2017, 18:34 UTC · re: Junio C Hamano · lore

Re: "git describe" documentation and behavior mismatch

On Sun, Dec 3, 2017 at 6:39 AM, Junio C Hamano <gitster@pobox.com> wrote:
Show 6 quoted lines
> I suspect that "see if the name recorded in the tag object matches
> the name of the ref that stores the tag after refs/tags/" code *is*
> not just verifying what it claims to (which may be good) but also
> unintentionally affecting the output (i.e. "--all" promises that the
> prefix tags/ should be shown).  Perhaps the code needs to be fixed
> if that is the case.

What is the course of action then? I wrote up a really dumb 2-line patch which simply checks if --all was specified and prepends the output with "tags/".

Good enough? Should we instead update the documentation? Still not sure, what the behavior _should_ be in the case of annotated tags with embedded names.

-- >8 --
From 7243d700aad280b11e647e04ade027c412dde54c Mon Sep 17 00:00:00 2001
From: Daniel Knittl-Frank <knittl89+git@googlemail.com>
Date: Mon, 11 Dec 2017 19:24:54 +0100
Subject: [PATCH] Prepend "tags/" when describing tags with embedded name
Signed-off-by: Daniel Knittl-Frank <knittl89+git@googlemail.com>
---
 builtin/describe.c | 2 ++
 1 file changed, 2 insertions(+)
diff --git a/builtin/describe.c b/builtin/describe.c
index e14e162ef6..54aaf30562 100644
--- a/builtin/describe.c
+++ b/builtin/describe.c
@@ -272,6 +272,8 @@ static void display_name(struct commit_name *n)
     }

     if (n->tag)
+        if (all)
+            printf("tags/");
         printf("%s", n->tag->tag);
     else
         printf("%s", n->path);

-- 
2.15.GIT



-- 
typed with http://neo-layout.org
Daniel Knittl-Frank· Dec 11, 2017, 18:37 UTC · re: Daniel Knittl-Frank · lore

Re: "git describe" documentation and behavior mismatch

Forget the above patch. I should compile my code after refactoring ...
Here is the fixed version.
-- >8 --
From 8203bd0ad5baab7024ebff597c9f35a0250d09ff Mon Sep 17 00:00:00 2001
From: Daniel Knittl-Frank <knittl89+git@googlemail.com>
Date: Mon, 11 Dec 2017 19:24:54 +0100
Subject: [PATCH] Prepend "tags/" when describing tags with embedded name
Signed-off-by: Daniel Knittl-Frank <knittl89+git@googlemail.com>
---
 builtin/describe.c | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)
diff --git a/builtin/describe.c b/builtin/describe.c
index e14e162ef6..9da6d85ea3 100644
--- a/builtin/describe.c
+++ b/builtin/describe.c
@@ -271,10 +271,13 @@ static void display_name(struct commit_name *n)
         n->name_checked = 1;
     }

-    if (n->tag)
+    if (n->tag) {
+        if (all)
+            printf("tags/");
         printf("%s", n->tag->tag);
-    else
+    } else {
         printf("%s", n->path);
+    }
 }

 static void show_suffix(int depth, const struct object_id *oid)

-- 
2.15.GIT

-- 
typed with http://neo-layout.org
Junio C Hamano· Dec 15, 2017, 19:25 UTC · re: Daniel Knittl-Frank · lore

Re: "git describe" documentation and behavior mismatch

Daniel Knittl-Frank <knittl89@googlemail.com> writes:
Show 15 quoted lines
> Forget the above patch. I should compile my code after refactoring ...
>
> Here is the fixed version.
>
> -- >8 --
>
> From 8203bd0ad5baab7024ebff597c9f35a0250d09ff Mon Sep 17 00:00:00 2001
> From: Daniel Knittl-Frank <knittl89+git@googlemail.com>
> Date: Mon, 11 Dec 2017 19:24:54 +0100
> Subject: [PATCH] Prepend "tags/" when describing tags with embedded name
>
> Signed-off-by: Daniel Knittl-Frank <knittl89+git@googlemail.com>
> ---
>  builtin/describe.c | 7 +++++--
>  1 file changed, 5 insertions(+), 2 deletions(-)

I think the code makes sense, but it won't be understandable by those who do not know what you discussed in the original thread.

A proper commit log message, with a new test or two in t6120, would be an appropriate way to fix that.

Care to follow through, along the lines in Documentation/SubmittingPatches?

Thanks.
Show 22 quoted lines
> diff --git a/builtin/describe.c b/builtin/describe.c
> index e14e162ef6..9da6d85ea3 100644
> --- a/builtin/describe.c
> +++ b/builtin/describe.c
> @@ -271,10 +271,13 @@ static void display_name(struct commit_name *n)
>          n->name_checked = 1;
>      }
>
> -    if (n->tag)
> +    if (n->tag) {
> +        if (all)
> +            printf("tags/");
>          printf("%s", n->tag->tag);
> -    else
> +    } else {
>          printf("%s", n->path);
> +    }
>  }
>
>  static void show_suffix(int depth, const struct object_id *oid)
> -- 
> 2.15.GIT

← back to recent threads