Skip to contentSkip to conversation

If abbrev is set to zero in git-describe, don't add the unique suffix

PATCH In review Shawn O. Pearce 3 participants 6 messages Jun 15, 2016 1 message not in the archive Documentation

lore
Share & tools
lore

A message that is not in the archive (sent off-list or not yet received): a23c4e55ca5c09f742fa2a047e45613e7797e720.1169880681.git.spearce@spearce.org

#1 lore raw

PATCH 2/4 If abbrev is set to zero in git-describe, don't add the unique suffix

From: Andy Parkins <[email protected]>

When on a non-tag commit, git-describe normally outputs descriptions of the form
v1.0.0-g1234567890
Some scripts (for example the update hook script) might just want to know the name of the nearest tag, so they then have to do
x=$(git-describe HEAD | sed 's/-g*//')
This is costly, but more importantly is fragile as it is relying on the output format of git-describe, which we would then have to maintain forever.

This patch adds support for setting the --abbrev option to zero. In that case git-describe does as it always has, but outputs only the nearest found tag instead of a completely unique name. This means that scripts would not have to parse the output format and won't need changing if the git-describe suffix is ever changed.

---

This is a resend of Andy's original patch. I added documentation updates and slighlty modified the code so it conformed to our conventions. Reason is, my next patch alters the same lines...

 Documentation/git-describe.txt |    7 ++++++-
 builtin-describe.c             |    9 ++++++---
 2 files changed, 12 insertions(+), 4 deletions(-)
Documentation/git-describe.txt +6 -1
index b87783c..a615996 100644
@@ -33,7 +33,9 @@ OPTIONS
 
 --abbrev=<n>::
 	Instead of using the default 8 hexadecimal digits as the
-	abbreviated object name, use <n> digits.
+	abbreviated object name, use <n> digits.  If set to 0
+	then abbreviated object name will not be displayed on
+	a non-exact match.
 
 --candidates=<n>::
 	Instead of considering only the 10 most recent tags as
@@ -70,6 +72,9 @@ the output shows the reference path as well:
 	[torvalds@g5 git]$ git describe --all --abbrev=4 v1.0.5^2
 	tags/v1.0.0-g975b
 
+	[torvalds@g5 git]$ git describe --all --abbrev=0 v1.0.5^2
+	tags/v1.0.0
+
 	[torvalds@g5 git]$ git describe --all HEAD^
 	heads/lt/describe-g975b
 
builtin-describe.c +6 -3
index f8afb9c..70578dc 100644
@@ -188,8 +188,11 @@ static void describe(const char *arg, int last_one)
 				sha1_to_hex(gave_up_on->object.sha1));
 		}
 	}
-	printf("%s-g%s\n", all_matches[0].name->path,
-		   find_unique_abbrev(cmit->object.sha1, abbrev));
+	if (!abbrev)
+		printf("%s\n", all_matches[0].name->path);
+	else
+		printf("%s-g%s\n", all_matches[0].name->path,
+			find_unique_abbrev(cmit->object.sha1, abbrev));
 
 	if (!last_one)
 		clear_commit_marks(cmit, -1);
@@ -212,7 +215,7 @@ int cmd_describe(int argc, const char **argv, const char *prefix)
 			tags = 1;
 		else if (!strncmp(arg, "--abbrev=", 9)) {
 			abbrev = strtoul(arg + 9, NULL, 10);
-			if (abbrev < MINIMUM_ABBREV || 40 < abbrev)
+			if (abbrev && (abbrev < MINIMUM_ABBREV || 40 < abbrev))
 				abbrev = DEFAULT_ABBREV;
 		}
 		else if (!strncmp(arg, "--candidates=", 13)) {
Signature · 1 line
1.5.0.rc2.g8a816
#2 lore raw

PATCH 3/4 Teach git-describe to display distances from tags.

In reply to a message not in the archive

Junio C Hamano <[email protected]>:

Quoted 8 lines

However, I suspect that we could do better with Shawn's new fangled describe implementation that actually counts the distance between what is described and the tag. We could add "number of commits since the tag" somewhere, to describe:

v2.6.20-rc5-256-g419dd83
v2.6.20-rc5-217-gde14569

Quoted 6 lines

to say that the first one has 256 commits accumulated since the given tag "v2.6.20-rc5" and the second one has only 217 commits, to get the sense of how busy the development activity is.

Is it useful? That is something I am not sure.

Yes, its very useful. If you get two different describes at different times from a non-rewinding branch and they both come up with the same tag name, you can tell which is the 'newer' one by distance. This is rather common in practice, so its incredibly useful.

Credit for this idea also goes to Jakub Narebski for suggesting:

    v2.6.20-rc5+256-g419dd83
    v2.6.20-rc5+217-gde14569

The + format is much easier to read and understand than the - format original proposed by Junio.

---
 Documentation/git-describe.txt |   23 ++++++++++++++---------
 builtin-describe.c             |    3 ++-
 2 files changed, 16 insertions(+), 10 deletions(-)
Documentation/git-describe.txt +14 -9
index a615996..b3e9276 100644
@@ -14,8 +14,8 @@ DESCRIPTION
 -----------
 The command finds the most recent tag that is reachable from a
 commit, and if the commit itself is pointed at by the tag, shows
-the tag.  Otherwise, it suffixes the tag name with abbreviated
-object name of the commit.
+the tag.  Otherwise, it suffixes the tag name with the number of
+additional commits and the abbreviated object name of the commit.
 
 
 OPTIONS
@@ -54,12 +54,17 @@ EXAMPLES
 With something like git.git current tree, I get:
 
 	[torvalds@g5 git]$ git-describe parent
-	v1.0.4-g2414721b
+	v1.0.4+14-g2414721
 
-i.e. the current head of my "parent" branch is based on v1.0.4,
-but since it has a few commits on top of that, it has added the
-git hash of the thing to the end: "-g" + 8-char shorthand for
-the commit `2414721b194453f058079d897d13c4e377f92dc6`.
+i.e. the current head of my "parent" branch is based on v1.0.4.
+But since my parent branch has a few commits on top of that,
+describe has added the number of additional commits ("+14") and
+the hash of the tip commit ("-g2414721") to the end.
+
+The number of additional commits is an estimate of the number
+of commits which would be displayed by "git log v1.0.4..parent".
+The hash suffix is "-g" + 8-char abbreviation for the tip commit
+of parent (which was `2414721b194453f058079d897d13c4e377f92dc6`).
 
 Doing a "git-describe" on a tag-name will just show the tag name:
 
@@ -70,13 +75,13 @@ 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-g975b
+	tags/v1.0.0+21-g975b
 
 	[torvalds@g5 git]$ git describe --all --abbrev=0 v1.0.5^2
 	tags/v1.0.0
 
 	[torvalds@g5 git]$ git describe --all HEAD^
-	heads/lt/describe-g975b
+	heads/lt/describe+5-g975b
 
 SEARCH STRATEGY
 ---------------
builtin-describe.c +2 -1
index 70578dc..6e59e75 100644
@@ -191,7 +191,8 @@ static void describe(const char *arg, int last_one)
 	if (!abbrev)
 		printf("%s\n", all_matches[0].name->path);
 	else
-		printf("%s-g%s\n", all_matches[0].name->path,
+		printf("%s+%d-g%s\n", all_matches[0].name->path,
+			all_matches[0].depth,
 			find_unique_abbrev(cmit->object.sha1, abbrev));
 
 	if (!last_one)
Signature · 1 line
1.5.0.rc2.g8a816
#3 lore raw

Re: [PATCH 3/4] Teach git-describe to display distances from tags.

Quoted 6 lines · Shawn O. Pearce

Junio C Hamano <[email protected]>:

Quoted 5 lines

However, I suspect that we could do better with Shawn's new fangled describe implementation that actually counts the distance between what is described and the tag. We could add "number of commits since the tag" somewhere, to describe:

Quoted 8 lines
Quoted 2 lines

v2.6.20-rc5-256-g419dd83
v2.6.20-rc5-217-gde14569

...

    v2.6.20-rc5+256-g419dd83
    v2.6.20-rc5+217-gde14569

The + format is much easier to read and understand than the - format original proposed by Junio.

I tend to disagree (I do not claim + is _less_ easier to read, though).

They are of comparable readability, and I think plus breaks GIT-VERSION-GEN (the primary reason it replaces '-' to '.' is to work around RPM limitation IIRC, and I do not know what '+' does to RPM offhand).

But I do not have a strong feeling either way.

#4 lore raw

Re: [PATCH 3/4] Teach git-describe to display distances from tags.

Hi,

Quoted 11 lines · Junio C Hamano
Quoted 2 lines · Shawn O. Pearce

The + format is much easier to read and understand than the - format original proposed by Junio.

I tend to disagree (I do not claim + is _less_ easier to read, though).

They are of comparable readability, and I think plus breaks GIT-VERSION-GEN (the primary reason it replaces '-' to '.' is to work around RPM limitation IIRC, and I do not know what '+' does to RPM offhand).

Note that scripts using git-describe to name archives break also on challenged file / operating systems. IIRC on DOS/FAT32 '+' has problems with it.

Quoted 1 line

But I do not have a strong feeling either way.

Neither have I.

Ciao,
Dscho

#5 lore raw

Re: [PATCH 3/4] Teach git-describe to display distances from tags.

Quoted 13 lines · Johannes Schindelin
Quoted 11 lines · Junio C Hamano
Quoted 2 lines · Shawn O. Pearce

The + format is much easier to read and understand than the - format original proposed by Junio.

I tend to disagree (I do not claim + is _less_ easier to read, though).

They are of comparable readability, and I think plus breaks GIT-VERSION-GEN (the primary reason it replaces '-' to '.' is to work around RPM limitation IIRC, and I do not know what '+' does to RPM offhand).

Quoted 7 lines

Note that scripts using git-describe to name archives break also on challenged file / operating systems. IIRC on DOS/FAT32 '+' has problems with it.

Quoted 1 line

But I do not have a strong feeling either way.

Neither have I.

Me neither, actually. The + just felt more right, as its literally "that tag, plus n commits".

But if + is going to cause pain on operating systems that somehow decided disallowing bytes other than NUL was OK and the right thing to do, then maybe - is the safer choice here.

Signature · 1 line
Shawn.
#6 lore raw

PATCH 4/4 Compute accurate distances in git-describe before output.

In reply to a message not in the archive

My prior change to git-describe attempts to print the distance between the input commit and the best matching tag, but this distance was usually only an estimate as we always aborted revision walking as soon as we overflowed the configured limit on the number of possible tags (as set by --candidates).

Displaying an estimated distance is not very useful and can just be downright confusing. Most users (heck, most Git developers) don't immediately understand why this distance differs from the output of common tools such as git rev-list | wc -l. Even worse, the estimated distance could change in the future (including decreasing despite no rebase occuring) if we find more possible tags earlier on during traversal. (This could happen if more tags are merged into the branch between queries.) These factors basically make an estimated distance useless.

Fortunately we are usually most of the way through an accurate distance computation by the time we abort (due to reaching the current --candidates limit). This means we can simply finish counting out the revisions still in our commit queue to present the accurate distance at the end. The number of commits remaining in the commit queue is probably less than the number of commits already traversed, so finishing out the count is not likely to take very long. This final distance will then always match the output of git rev-list | wc -l.

We can easily reduce the total number of commits that need to be walked at the end by stopping as soon as all of the commits in the commit queue are flagged as being merged into the already selected best possible tag. If that's true then there are no remaining unseen commits which can contribute to our best possible tag's depth counter, so further traversal is useless.

Basic testing on my Mac OS X system shows there is no noticable performance difference between this accurate distance counting version of git-describe and the prior version of git-describe, at least when run on git.git.

---
 Documentation/git-describe.txt |    2 +-
 builtin-describe.c             |   42 +++++++++++++++++++++++++++++++++++++++-
 2 files changed, 42 insertions(+), 2 deletions(-)
Documentation/git-describe.txt +1 -1
index b3e9276..160779a 100644
@@ -61,7 +61,7 @@ But since my parent branch has a few commits on top of that,
 describe has added the number of additional commits ("+14") and
 the hash of the tip commit ("-g2414721") to the end.
 
-The number of additional commits is an estimate of the number
+The number of additional commits shown after the tag is the number
 of commits which would be displayed by "git log v1.0.4..parent".
 The hash suffix is "-g" + 8-char abbreviation for the tip commit
 of parent (which was `2414721b194453f058079d897d13c4e377f92dc6`).
builtin-describe.c +41 -1

59 lines not on this page · raw message

Signature · 1 line
1.5.0.rc2.g8a816