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