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>. You accept blob object name in this mode, so just saying <blob> is sufficient.
