On Mon, Oct 30, 2017 at 11:25 PM, Junio C Hamano <gitster@xxxxxxxxx> wrote: > Stefan Beller <sbeller@xxxxxxxxxx> writes: > >> diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt >> index c924c945ba..3d618b2445 100644 >> --- a/Documentation/git-describe.txt >> +++ b/Documentation/git-describe.txt >> @@ -3,7 +3,7 @@ git-describe(1) >> >> NAME >> ---- >> -git-describe - Describe a commit using the most recent tag reachable from it >> +git-describe - Describe a commit or blob using the most recent tag reachable from it > > If I am not mistaken, this series is about describing a blob as a > tuple of a recent commit-ish and a path in the tree in it. Blob > never reaches anything, so "desribing blob using X reachable from > it" is a mere nonsense. Agreed, though the commitish used for the blob description may refer to a tag. > The original is not great in that it ignores the "--contains" mode > and referring to "tagged commit" merely as "tag" for brevity, but > at least it made some sense. Maybe "git-describe - Describe a blob or commit using graph relations" though that sounds too generic, but it is accurate as all we do is a heuristic for graph walk ways. >> @@ -24,6 +24,16 @@ 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]. >> >> +If the given `<commit-ish>` refers to a blob, it will be described > > Perhaps this step should update the SYNOPSIS so that the command > takes not just commit-ish but a blob too. That is a good idea, as the --contains would not work for blobs currently. > Given the difficulty in > coming up with the single-liner description of what it does we saw > above, I suspect that splitting SYNOPSIS out into two very distinct > operating mode might make it easier to read. > > SYNOPSIS > -------- > [verse] > 'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] [<commit-ish>...] > +'git describe' [<options>...] <blob>... > > Then this additional paragraph can say "When describin a <blob>", > without using a (technically nonsense) phrase "if <commit-ish> > refers to a blob", which is never true. > ok, do we know about 'blob-ish' as a term?
