Re: [PATCH] Rephrased git-describe description

> On Wed, 14 May 2008 at 11:57am -0500, Kevin Ballard wrote:
>
>> On May 14, 2008, at 9:22 AM, Ian Hilt wrote:
>>> DESCRIPTION
>>> -----------
>>> The command finds the most recent tag that is reachable from a
>>> -commit, and if the commit itself is pointed at by the tag, shows
>>> -the tag.  Otherwise, it suffixes the tag name with the number of
>>> -additional commits and the abbreviated object name of the commit.
>>> +commit.  If the tag points to the commit, then only the tag is
>>> +shown.  Otherwise, the number of additional commits on top of the
>>> +tagged object and the abbreviated object name of the most recent
>>> +commit are suffixed to the tag name.
>>
>> I disagree that this is more readable. Specifically that last
>> sentence. In the original description it tells me what it's
>> doing (suffixing) before it tells me what objects it's
>> using. In your version, it tells me the objects, then tells me
>> what it's doing (suffixing), so I have to effectively process
>> the sentence in reverse. In other words, it took me two
>> readings of your last sentence to match the one reading of the
>> original last sentence.
>
> How about this?
>
>  The command finds the most recent tag that is reachable from a
>  commit.  If the tag points to the commit, then only the tag is
>  shown.  Otherwise, it suffixes to the tag name the number of
>  additional commits on top of the tagged object and the
>  abbreviated object name of the most recent commit.

>> Also, you should use a more descriptive commit description. At the  
>> very least, do something like
>>
>> git-describe: Make description more readable.
>
> Something like this:
>
> git-describe: Changed subject from commit to tag in the first
>              sentence, clarified what the number of commits is
>              referring to, and pointed out which object is
>              referenced by the suffixed object name.