Re: [PATCHv4 7/7] builtin/describe.c: describe a blob

From: Junio C Hamano <gitster@pobox.com>
Date: Nov 16, 2017, 01:43 UTC
Message-ID: <xmqq7eurxak0.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <CAGZ79kaum5py=14kdFy1a+K_0MzfaD5boYStixh=1aY2tUCV-Q@mail.gmail.com>

Stefan Beller <sbeller@google.com> writes:

Show 7 quoted lines

>>> -git-describe - Describe a commit using the most recent tag reachable from it
>>> +git-describe - Describe a commit or blob using the graph relations
>>
>> I would write "Describe a commit or blob using a tag reachable from it".
>
> using a ref, as we also can use refs.
> I think 'the graph' is technically correct here, but may be too confusing.

Without saying graph over what, "graph relations" is not just confusing but an insufficient explanation for a technically correct explanation. Even though we have "--contains", we say "reachable from" and nobody has complained---so perhaps we can keep the white lie to keep the synopsis simpler?

If I were writing this sentence from scratch, perhaps I wouldn't even use the word "describe". How about

    Give an object a human readable name based on an available ref

or something like that?

Show 18 quoted lines

>>  (Should we also test the case where a blob is directly
>> tagged?)
>
> We do a bad job at describing tags that point at a blob currently:
>
>   git tag test-blob HEAD:Makefile
>   git describe test-blob
> error: object cd75985991f4535c45e2589222a9e6a38fb1d613 is a blob, not a commit
> fatal: test-blob is not a valid 'commit' object
>
> This series changes this to
>
>   git describe test-blob
>   v2.15.0-rc0-43-g54bd705a95:Makefile
>
> which might not be expected (you'd expect "test-blob"),
> so I think I can write a test telling that this is suboptimal
> behavior?

Or a sentence in BUGS section.

A case (or two) I find more interesting is to see how the code behaves against these:

	git tag -a -m "annotated blob" a-blob HEAD:Makefile
	git tag -a -m "annotated tree" a-tree HEAD:t
	git describe a-blob a-tree

Thanks.