[PATCH 1/2] git-describe: introduce --first-parent

[Michael J Gruber]

so that git-describe searches first-parent history only when looking for
a named commit. This is useful for describing commits by tags on their
"main" (first-parent) branch; for example, on git.git:

git describe 22ffc39
v1.7.2.3-223-g22ffc39

git describe --first-parent 22ffc39
v1.7.2-104-g22ffc39

git describe --contains --first-parent is forbidden because git name-rev
(which is called by that) favors first-parent transversal already,
although not strictly so.

Signed-off-by: Michael J Gruber <***@drmicha.warpmail.net>
---
builtin/describe.c | 8 +++++++-
1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/builtin/describe.c b/builtin/describe.c
index 9fe11ed..aa60f5c 100644
--- a/builtin/describe.c
+++ b/builtin/describe.c
@@ -25,6 +25,7 @@ static int abbrev = -1; /* unspecified */
static int max_candidates = 10;
static struct hash_table names;
static int have_util;
+static int first_parent;
static const char *pattern;
static int always;
static const char *dirty;
@@ -336,7 +337,7 @@ static void describe(const char *arg, int last_one)
if (!(p->object.flags & SEEN))
commit_list_insert_by_date(p, &list);
p->object.flags |= c->object.flags;
- parents = parents->next;
+ parents = first_parent ? NULL : parents->next;
}
}

@@ -414,6 +415,8 @@ int cmd_describe(int argc, const char **argv, const char *prefix)
N_("only consider tags matching <pattern>")),
OPT_BOOLEAN(0, "always", &always,
N_("show abbreviated commit object as fallback")),
+ OPT_BOOLEAN(0, "first-parent", &first_parent,
+ "follow first parents only"),
{OPTION_STRING, 0, "dirty", &dirty, N_("mark"),
N_("append <mark> on dirty working tree (default: \"-dirty\")"),
PARSE_OPT_OPTARG, NULL, (intptr_t) "-dirty"},
@@ -435,6 +438,9 @@ int cmd_describe(int argc, const char **argv, const char *prefix)
if (longformat && abbrev == 0)
die(_("--long is incompatible with --abbrev=0"));

+ if (contains && first_parent)
+ die(_("--contains is incompatible with --first-parent"));
+
if (contains) {
const char **args = xmalloc((7 + argc) * sizeof(char *));
int i = 0;

[Michael J Gruber]

Signed-off-by: Michael J Gruber <***@drmicha.warpmail.net>
---
Documentation/git-describe.txt | 16 +++++++++++++++-
t/t6120-describe.sh | 7 +++++++
2 files changed, 22 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt
index 72d6bb6..9fb5c84 100644
--- a/Documentation/git-describe.txt
+++ b/Documentation/git-describe.txt
@@ -84,6 +84,10 @@ OPTIONS
Only consider tags matching the given pattern (can be used to avoid
leaking private tags made from the repository).

+--first-parent::
+ Only consider tags which can be reached from '<committish>' by a first
+ parent walk, i.e. only those which are not on side branches.
+
--always::
Show uniquely abbreviated commit object as fallback.

@@ -129,6 +133,14 @@ closest tagname without any suffix:
[***@g5 git]$ git describe --abbrev=0 v1.0.5^2
tags/v1.0.0

+With --first-parent, tags on side branches are not considered:
+
+ $ git describe v1.1.0^
+ v1.0.7-44-ge77f489
+
+ $ git describe --first-parent v1.1.0^
+ v1.0.0-41-ge77f489
+
Note that the suffix you get if you type these commands today may be
longer than what Linus saw above when he ran these commands, as your
git repository may have new commits whose object names begin with
@@ -148,7 +160,9 @@ is found, its name will be output and searching will stop.
If an exact match was not found, 'git describe' will walk back
through the commit history to locate an ancestor commit which
has been tagged. The ancestor's tag will be output along with an
-abbreviation of the input committish's SHA1.
+abbreviation of the input committish's SHA1. With '--first-parent',
+'git describe' will walk the history only along the first parent
+of each commit.

If multiple tags were found during the walk then the tag which
has the fewest commits different from the input committish will be
diff --git a/t/t6120-describe.sh b/t/t6120-describe.sh
index f67aa6f..2524236 100755
--- a/t/t6120-describe.sh
+++ b/t/t6120-describe.sh
@@ -103,6 +103,13 @@ check_describe c-* --tags HEAD^^2
check_describe B --tags HEAD^^2^
check_describe e --tags HEAD^^^

+check_describe R-* --first-parent HEAD
+check_describe R-* --first-parent HEAD^
+check_describe R-* --first-parent HEAD^^
+check_describe B-* --first-parent HEAD^^2
+check_describe B --first-parent HEAD^^2^
+check_describe R-* --first-parent HEAD^^^
+
check_describe heads/master --all HEAD
check_describe tags/c-* --all HEAD^
check_describe tags/e --all HEAD^^^

[Junio C Hamano]

Post by Michael J Gruber
---
Documentation/git-describe.txt | 16 +++++++++++++++-
t/t6120-describe.sh | 7 +++++++
2 files changed, 22 insertions(+), 1 deletion(-)
diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt
index 72d6bb6..9fb5c84 100644
--- a/Documentation/git-describe.txt
+++ b/Documentation/git-describe.txt
@@ -84,6 +84,10 @@ OPTIONS
Only consider tags matching the given pattern (can be used to avoid
leaking private tags made from the repository).
+ Only consider tags which can be reached from '<committish>' by a first
+ parent walk, i.e. only those which are not on side branches.
+

[PATCH 1/2] says:

git describe --contains --first-parent is forbidden because git name-rev
(which is called by that) favors first-parent transversal already,
although not strictly so.

but the end-users won't read the log message, so something like that
need to be here, I guess.

But if "name-rev" does more-or-less first-parent anyway, perhaps
simply ignoring --first-parent when doing --contains may make more
sense?

[Junio C Hamano]

While "git describe" behaves as documented, the notion of "most recent tag"
is not really easy to grab, and it's not always the way you want to describe
a commit.
"--first-parent" is the option which answers the question: Which is the
most recent tag on this branch which can be reached from this commit?
("This branch" being defined as "--first-parent" walk.)

I see a confused message here. If it is "the" option which answers,
what is the question? If the "question" is the only question people
would ask, you wouldn't make this an option, but update the default
to do this, but you obviously did not want to do so, so there must
be cases where using this option is inappropirate and is not "the"
option to answer the question the user wants to ask.

Also, how would this interact with "--contains"? Should it and if
so why? If it shouldn't, why?

[Junio C Hamano]

Post by Michael J Gruber
so that git-describe searches first-parent history only when looking for

Please make sure your first paragraph of the log message start with
a full sentence, not an incomplete tail part of a sentence as if the
title of the commit were repeated in front of it.

Post by Michael J Gruber
a named commit. This is useful for describing commits by tags on their

This is useful only when the history does not have fast-forward
merges from a sideline; otherwise it will produce unexpected
results, no?

Post by Michael J Gruber
git describe 22ffc39
v1.7.2.3-223-g22ffc39
git describe --first-parent 22ffc39
v1.7.2-104-g22ffc39

The output is wrong in that 22ffc39 is v1.7.2-336-g22ffc39, not 104.
Putting an arbitrary number that can change depending on how the
traversal went will close the door to possible follow-up work on the
recent sha1-name-more series (0958a24^2, most importantly aa1dec9e)
to prolong the shelf-life of describe output by filtering candidate
commits with reachability from the tag and the number of commits
from the tag.

In any case, it is not clear to me if this is a useful example to
help readers of this commit to understand why this new feature is
useful. 22ffc39 was created to mark that the work done for 1.7.2.x
maintenance track back then were all contained in the 'master' by
merging 'maint' when it was pointing at v1.7.2.3. Saying the commit
is newer than v1.7.2.3 gives more information than it is newer than
v1.7.2, as by convention v1.7.2 must be older than v1.7.2.3, no?