Re: [PATCH 6/7] builtin/describe.c: describe a blob
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Oct 31, 2017, 06:25 UTC
- Message-ID
- <xmqqinevzvel.fsf@gitster.mtv.corp.google.com>
- In-Reply-To
- <20171031003351.22341-7-sbeller@google.com>
Stefan Beller <sbeller@google.com> writes:
Show 10 quoted lines
> 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.
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.
Show 5 quoted lines
> @@ -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. 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.