path: root/builtin/describe.c
diff options
authorStefan Beller <>2017-11-16 02:00:39 (GMT)
committerJunio C Hamano <>2017-12-19 19:17:16 (GMT)
commit644eb60bd01a15f665b63774fd80e3b6316073a1 (patch)
tree67e1d0cd9e08fa002a71e25571eaa30ab8ff6efc /builtin/describe.c
parent4dbc59a4cce418ff8428a9d2ecd67c34ca50db56 (diff)
builtin/describe.c: describe a blob
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] Signed-off-by: Stefan Beller <> Signed-off-by: Junio C Hamano <>
Diffstat (limited to 'builtin/describe.c')
1 files changed, 57 insertions, 5 deletions
diff --git a/builtin/describe.c b/builtin/describe.c
index 9e9a5ed..5b4bfab 100644
--- a/builtin/describe.c
+++ b/builtin/describe.c
@@ -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;
@@ -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);