[PATCH 0/2] git describe --first-parent

[PATCH 0/2] git describe --first-parent

[Michael J Gruber]

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 had suggested this before, but the discussion veered off quite a bit:
http://permalink.gmane.org/gmane.comp.version-control.git/156811

No need to discuss the way "git describe" behaves again ;)

Michael J Gruber (2):
  git-describe: introduce --first-parent
  describe: document and test --first-parent

 Documentation/git-describe.txt | 16 +++++++++++++++-
 builtin/describe.c             |  8 +++++++-
 t/t6120-describe.sh            |  7 +++++++
 3 files changed, 29 insertions(+), 2 deletions(-)

-- 
1.7.12.463.gbd9d638

[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 <git@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;
-- 
1.7.12.463.gbd9d638

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

[Junio C Hamano]

Michael J Gruber <git@drmicha.warpmail.net> writes:

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

> a named commit. This is useful for describing commits by tags on their
> "main" (first-parent) branch; for example, on git.git:

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

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

[PATCH 2/2] describe: document and test --first-parent

[Michael J Gruber]

Signed-off-by: Michael J Gruber <git@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:
 	[torvalds@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^^^
-- 
1.7.12.463.gbd9d638

Re: [PATCH 2/2] describe: document and test --first-parent

[Junio C Hamano]

Michael J Gruber <git@drmicha.warpmail.net> writes:

> Signed-off-by: Michael J Gruber <git@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.
> +

[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?

Re: [PATCH 0/2] git describe --first-parent

[Junio C Hamano]

Michael J Gruber <git@drmicha.warpmail.net> writes:

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