describe blob

When describing commits, we try to anchor them to tags or refs, as these are conceptually on a higher level than the commit. And if there is no ref or tag that matches exactly, we're out of luck. So we employ a heuristic to make up a name for the commit. These names are ambiguous, there might be different tags or refs to anchor to, and there might be different path in the DAG to travel to arrive at the commit precisely.

When describing a blob, we want to describe the blob from a higher layer as well, which is a tuple of (commit, deep/path) as the tree objects involved are rather uninteresting. The same blob can be referenced by multiple commits, so how we decide which commit to use? This patch implements a rather naive approach on this: As there are no back pointers from blobs to commits in which the blob occurs, we'll start walking from any tips available, listing the blobs in-order of the commit and once we

found the blob, we'll take the first commit that listed the blob. For example

  git describe --tags v0.99:Makefile
  conversion-901-g7672db20c2:Makefile

tells us the Makefile as it was in v0.99 was introduced in commit 7672db20.

The walking is performed in reverse order to show the introduction of a blob rather than its last occurrence.

builtin/describe.c +3 -0

+	argv_array_pushl(&args, "internal: The first arg is not parsed",
+		"--objects", "--in-commit-order", "--reverse", "HEAD",
+		NULL);

I am not sure if "And if there is ..." is adding much value here (I do not think it is even technically correct for that matter). If there are more than one tag that point at the commit the user is interested in, we use one of the tags, as tags conceptually sit at a higher level. And we use a heuristic to use one or the other tag to make up a name for the commit, so the same commit can have two valid names. ---So what? Neither of these two valid names is "ambigous"; the commit object the user wanted to name _is_ correctly identified (I would assume that we are not discussing a hash collision).

Lucikly, if we remove "And if...precisely", the logic still flows nicely, if not more, to the next paragraph.

Quoted 7 lines

When describing a blob, we want to describe the blob from a higher layer as well, which is a tuple of (commit, deep/path) as the tree objects involved are rather uninteresting. The same blob can be referenced by multiple commits, so how we decide which commit to use? This patch implements a rather naive approach on this: As there are no back pointers from blobs to commits in which the blob occurs, we'll start walking from any tips available, listing the blobs in-order of the commit and once we

Is "any tips" still the case? I was wondering why you start your traversal at HEAD and nothing else in this iteration. There seems to be no mention of this design decision in the documentation and no justification in the log.

The reversing may improve the chance of an older commit to be chosen rather than the newer one, but it does not even guarantee to show the "introduction".

What this guarantees is that a long history will be traversed fully before we start considering which commit has the blob of interest, I am afraid. Is this a sensible trade-off?

...
fixed.
...
fixed the text...
...
I am not fully convinced all descriptions are in recent history, but I tend to agree that most are, so probably the trade off is a wash.

Quoted 7 lines · Stefan Beller

...
fixed.
...
fixed the text...
...
I am not fully convinced all descriptions are in recent history, but I tend to agree that most are, so probably the trade off is a wash.

So what do we want with this topic? I think the "teach 'git log' to highlight commits whose changes involve the given blob" is a more or less an orthogonal thing,

and I suspect that it is something users
may (although I personally do not) find valuable to have a related but different feature in "git describe".

Quoted 10 lines · Junio C Hamano

Quoted 7 lines · Stefan Beller

...
fixed.
...
fixed the text...
...
I am not fully convinced all descriptions are in recent history, but I tend to agree that most are, so probably the trade off is a wash.

Quoted 3 lines

So what do we want with this topic? I think the "teach 'git log' to highlight commits whose changes involve the given blob" is a more or less an orthogonal thing,

Well, both of them solve our immediate needs, so I'd be fine with pursuing just one of them, but I do not oppose taking both.

Quoted 3 lines

and I suspect that it is something users
may (although I personally do not) find valuable to have a related but different feature in "git describe".

agreed.

Quoted 18 lines · Stefan Beller

Quoted 10 lines · Junio C Hamano

Quoted 7 lines · Stefan Beller

...
fixed.
...
fixed the text...
...
I am not fully convinced all descriptions are in recent history, but I tend to agree that most are, so probably the trade off is a wash.

Quoted 3 lines

So what do we want with this topic? I think the "teach 'git log' to highlight commits whose changes involve the given blob" is a more or less an orthogonal thing,

Well, both of them solve our immediate needs, so I'd be fine with pursuing just one of them, but I do not oppose taking both.

Quoted 5 lines

Quoted 3 lines

and I suspect that it is something users
may (although I personally do not) find valuable to have a related but different feature in "git describe".

agreed.

I was reacting to your "fixed". So will we see a rerolled series or not?

Quoted 2 lines

I was reacting to your "fixed". So will we see a rerolled series or not?

I was not planning on rerolling it.

Sometimes users are given a hash of an object and they want to identify it further (ex.: Use verify-pack to find the largest blobs, but what are these? or [1])

When describing commits, we try to anchor them to tags or refs, as these are conceptually on a higher level than the commit. And if there is no ref or tag that matches exactly, we're out of luck. So we employ a heuristic to make up a name for the commit. These names are ambiguous, there might be different tags or refs to anchor to, and there might be different path in the DAG to travel to arrive at the commit precisely.

When describing a blob, we want to describe the blob from a higher layer as well, which is a tuple of (commit, deep/path) as the tree objects involved are rather uninteresting. The same blob can be referenced by multiple commits, so how we decide which commit to use? This patch implements a rather naive approach on this: As there are no back pointers from blobs to commits in which the blob occurs, we'll start walking from any tips available, listing the blobs in-order of the commit and once we found the blob, we'll take the first commit that listed the blob. For example

git describe --tags v0.99:Makefile
conversion-901-g7672db20c2:Makefile

tells us the Makefile as it was in v0.99 was introduced in commit 7672db20.

The walking is performed in reverse order to show the introduction of a blob rather than its last occurrence.

[1] https://stackoverflow.com/questions/223678/which-commit-has-this-blob

Signed-off-by Stefan Beller <[email protected]>

---
Documentation/git-describe.txt | 18 ++++++++++--
builtin/describe.c | 62
++++++++++++++++++++++++++++++++++++++----
t/t6120-describe.sh | 34 +++++++++++++++++++++++

3 files changed, 107 insertions(+), 7 deletions(-)

Documentation/git-describe.txt +0 -0

index c924c945ba..e027fb8c4b 100644
@@ -3,14 +3,14 @@ git-describe(1)
 

NAME
----
-git-describe - Describe a commit using the most recent tag reachable from it

Documentation/git-describe.txt +1 -1

-
+git-describe - Give an object a human readable name based on an available 

ref

SYNOPSIS
--------
[verse]
'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] [<commit-ish>...] 'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] --dirty[=<mark>] +'git describe' <blob>

DESCRIPTION
-----------

Documentation/git-describe.txt +0 -0

@@ -24,6 +24,12 @@ By default (without --all or --tags) `git describe` 

only shows
annotated tags. For more information about creating annotated tags see the -a and -s options to linkgit:git-tag[1].

Documentation/git-describe.txt +6 -0

+If the given object refers to a blob, it will be described
+as `<commit-ish>:<path>`, such that the blob can be found
+at `<path>` in the `<commit-ish>`, which itself describes the
+first commit in which this blob occurs in a reverse revision walk
+from HEAD.
+

OPTIONS
-------
<commit-ish>...::

Documentation/git-describe.txt +0 -0

@@ -186,6 +192,14 @@ selected and output.  Here fewest commits different 

is defined as
the number of commits which would be shown by git log tag..input will be the smallest number of commits possible.

Documentation/git-describe.txt +4 -0

+BUGS
+----
+
+Tree objects as well as tag objects not pointing at commits, cannot be 

described.

GIT
---
Part of the linkgit:git[1] suite

builtin/describe.c +50 -1

index 9e9a5ed5d4..5b4bfaba3f 100644
@@ -3,6 +3,7 @@
 #include "lockfile.h"
 #include "commit.h"
 #include "tag.h"
+#include "blob.h"
 #include "refs.h"
 #include "builtin.h"
 #include "exec_cmd.h"

@@ -11,8 +12,9 @@
 #include "hashmap.h"
 #include "argv-array.h"
 #include "run-command.h"
+#include "revision.h"
+#include "list-objects.h"
 
-#define SEEN (1u << 0)
 #define MAX_TAGS (FLAG_BITS - 1)
 
 static const char * const describe_usage[] = {

@@ -434,6 +436,53 @@ static void describe_commit(struct object_id *oid, 
 struct strbuf *dst)
 strbuf_addstr(dst, suffix);
 }
 
+struct process_commit_data {
+ struct object_id current_commit;
+ struct object_id looking_for;
+ struct strbuf *dst;
+ struct rev_info *revs;
+};
+
+static void process_commit(struct commit *commit, void *data)
+{
+ struct process_commit_data *pcd = data;
+ pcd->current_commit = commit->object.oid;
+}
+
+static void process_object(struct object *obj, const char *path, void 
 *data)
+{
+ struct process_commit_data *pcd = data;
+
+ if (!oidcmp(&pcd->looking_for, &obj->oid) && !pcd->dst->len) {
+ reset_revision_walk();
+ describe_commit(&pcd->current_commit, pcd->dst);
+ strbuf_addf(pcd->dst, ":%s", path);
+ free_commit_list(pcd->revs->commits);
+ pcd->revs->commits = NULL;
+ }
+}
+
+static void describe_blob(struct object_id oid, struct strbuf *dst)
+{
+ struct rev_info revs;
+ struct argv_array args = ARGV_ARRAY_INIT;
+ struct process_commit_data pcd = { null_oid, oid, dst, &revs};
+
+ argv_array_pushl(&args, "internal: The first arg is not parsed",
+ "--objects", "--in-commit-order", "--reverse", "HEAD",
+ NULL);
+
+ init_revisions(&revs, NULL);
+ if (setup_revisions(args.argc, args.argv, &revs, NULL) > 1)
+ BUG("setup_revisions could not handle all args?");
+
+ if (prepare_revision_walk(&revs))
+ die("revision walk setup failed");
+
+ traverse_commit_list(&revs, process_commit, process_object, &pcd);
+ reset_revision_walk();
+}
+
 static void describe(const char *arg, int last_one)

{
struct object_id oid;

builtin/describe.c +7 -4

@@ -445,11 +494,14 @@ static void describe(const char *arg, int last_one)
 
 if (get_oid(arg, &oid))
 die(_("Not a valid object name %s"), arg);
- cmit = lookup_commit_reference(&oid);
- if (!cmit)
- die(_("%s is not a valid '%s' object"), arg, commit_type);
+ cmit = lookup_commit_reference_gently(&oid, 1);
 
- describe_commit(&oid, &sb);
+ if (cmit)
+ describe_commit(&oid, &sb);
+ else if (lookup_blob(&oid))
+ describe_blob(oid, &sb);
+ else
+ die(_("%s is neither a commit nor blob"), arg);
 
 puts(sb.buf);
 

t/t6120-describe.sh +0 -0

index c8b7ed82d9..4668f0058e 100755
@@ -310,6 +310,40 @@ test_expect_success 'describe ignoring a broken 

submodule' '
grep broken out
'

t/t6120-describe.sh +34 -0

+test_expect_success 'describe a blob at a directly tagged commit' '
+ echo "make it a unique blob" >file &&
+ git add file && git commit -m "content in file" &&
+ git tag -a -m "latest annotated tag" unique-file &&
+ git describe HEAD:file >actual &&
+ echo "unique-file:file" >expect &&
+ test_cmp expect actual
+'
+
+test_expect_success 'describe a blob with its first introduction' '
+ git commit --allow-empty -m "empty commit" &&
+ git rm file &&
+ git commit -m "delete blob" &&
+ git revert HEAD &&
+ git commit --allow-empty -m "empty commit" &&
+ git describe HEAD:file >actual &&
+ echo "unique-file:file" >expect &&
+ test_cmp expect actual
+'
+
+test_expect_success 'describe directly tagged blob' '
+ git tag test-blob unique-file:file &&
+ git describe test-blob >actual &&
+ echo "unique-file:file" >expect &&
+ # suboptimal: we rather want to see "test-blob"
+ test_cmp expect actual
+'
+
+test_expect_success 'describe tag object' '
+ git tag test-blob-1 -a -m msg unique-file:file &&
+ test_must_fail git describe test-blob-1 2>actual &&
+ grep "fatal: test-blob-1 is neither a commit nor blob" actual
+'
+

test_expect_failure ULIMIT_STACK_SIZE 'name-rev works in a deep repo' '
i=1 &&
while test $i -lt 8000

Signature · 1 line

2.15.0.128.gcadd42da22

I had to squash in the following to make 'pu' pass under gettext-poison build. Is this ready for 'next' otherwise?

With the "log --find-object" thing, it may be that this no longer is needed, but then again we haven't done anything with the other Jonathan's idea to unify the --find-object thing into the --pickaxe framework.

It seems that we tend to open and then abandon new interests without seeing them through completion, leaving too many loose ends untied. This has to stop.

Quoted 2 lines · Junio C Hamano

I had to squash in the following to make 'pu' pass under gettext-poison build. Is this ready for 'next' otherwise?

I saw that in pu, thanks for squashing. I should have spoken up earlier confirming it.

Quoted 4 lines

With the "log --find-object" thing, it may be that this no longer is needed, but then again we haven't done anything with the other Jonathan's idea to unify the --find-object thing into the --pickaxe framework.

I'll look into that after I finish looking at a submodule related bug.

Quoted 3 lines

It seems that we tend to open and then abandon new interests without seeing them through completion, leaving too many loose ends untied. This has to stop.

I'll try to find my balance again.