On Tue, Oct 31, 2017 at 8:34 PM, Junio C Hamano <gitster@xxxxxxxxx> wrote: > Stefan Beller <sbeller@xxxxxxxxxx> 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>. But now we have a path as well, the notation of <commit-ish> COLON <path> is not a unique description of the blob, because * there can be multiple <commit-ish>s depending on the tags and walking * in boilerplate code cases, we might even have the blob at different places (e.g. pristine copies of a license file in subdirectories) When calling for a tree-ish, we also accept commits and tags plus walking directions. So I find it hard to think we have to take in exact blob names, but we would also accept blob-ishs (i.e. commit+path)
