Stefan Beller <[email protected]> writes:
>>> -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?
>> (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.
