From: Junio C Hamano <gitster@pobox.com>
Date: Wed, 01 Nov 2017 03:34:36 GMT
Subject: Re: [PATCH 6/7] builtin/describe.c: describe a blob
Message-ID: <xmqq4lqewu2b.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <CAGZ79kYO=4SWzfKY6bU8Spn5Ubw39ghOH6wanFhFEsKD8q9vrA@mail.gmail.com>

Stefan Beller <sbeller@google.com> writes:

>>  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?

No, and I do not think there is any need to say -ish at all for this
use case.

After all, when we accept a <commit> when a <tree-ish> is called
for, that is only because there is only one way to use the commit in
place of the wanted <tree>; we take the top-level tree contained in
it.  You cannot say you take <blob-ish> and take a <tree>, as it is
unclear which entry in the <tree> can act as the substitute for the
wanted <blob>.

You accept blob object name in this mode, so just saying <blob> is
sufficient.