[PATCH] Rephrased git-describe description

[PATCH] Rephrased git-describe description

[Ian Hilt]

Made description more readable.

Signed-off-by: Ian Hilt <ian.hilt@gmail.com>
---
 Documentation/git-describe.txt |    7 ++++---
 1 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt
index d9aa2f2..f3f07e4 100644
--- a/Documentation/git-describe.txt
+++ b/Documentation/git-describe.txt
@@ -13,9 +13,10 @@ SYNOPSIS
 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.
 
 
 OPTIONS
-- 
1.5.3.7

Re: [PATCH] Rephrased git-describe description

[Kevin Ballard]

Sorry for the double-posting, Ian, but my first email was rejected  
from the list because my mail client attached an HTML part.

On May 14, 2008, at 9:22 AM, Ian Hilt wrote:

> Made description more readable.
>
> Signed-off-by: Ian Hilt <ian.hilt@gmail.com>
> ---
> Documentation/git-describe.txt |    7 ++++---
> 1 files changed, 4 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/git-describe.txt b/Documentation/git- 
> describe.txt
> index d9aa2f2..f3f07e4 100644
> --- a/Documentation/git-describe.txt
> +++ b/Documentation/git-describe.txt
> @@ -13,9 +13,10 @@ SYNOPSIS
> 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.

Also, you should use a more descriptive commit description. At the  
very least, do something like

git-describe: Make description more readable.

-Kevin Ballard

-- 
Kevin Ballard
http://kevin.sb.org
kevin@sb.org
http://www.tildesoft.com

Re: [PATCH] Rephrased git-describe description

[Ian Hilt]

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.

-- 
Ian Hilt
ian.hilt (at) gmail.com
GnuPG key: 0x4AFC1EE3

Re: [PATCH] Rephrased git-describe description

[Kevin Ballard]

On May 14, 2008, at 1:00 PM, Ian Hilt wrote:

> 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.

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 the tag name with 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.

Sure, you could say that, but I think that just "git-describe: Make  
description more readable" is enough.

-Kevin Ballard

-- 
Kevin Ballard
http://kevin.sb.org
kevin@sb.org
http://www.tildesoft.com

[PATCH] Rephrased git-describe description

[Ian Hilt]

git-describe: Make description more readable.

Signed-off-by: Ian Hilt <ian.hilt@gmail.com>
---
 Documentation/git-describe.txt |    7 ++++---
 1 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt
index d9aa2f2..69e1ab7 100644
--- a/Documentation/git-describe.txt
+++ b/Documentation/git-describe.txt
@@ -13,9 +13,10 @@ SYNOPSIS
 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, it suffixes the tag name with the number of
+additional commits on top of the tagged object and the
+abbreviated object name of the most recent commit.
 
 
 OPTIONS
-- 
1.5.3.7

Re: [PATCH] Rephrased git-describe description

[Junio C Hamano]

Ian Hilt <ian.hilt@gmail.com> writes:

> git-describe: Make description more readable.

Thanks, both.  I think the above is meant to be on the Subject: line, and
the text certainly is more readable.

> Signed-off-by: Ian Hilt <ian.hilt@gmail.com>
> ---
>  Documentation/git-describe.txt |    7 ++++---
>  1 files changed, 4 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt
> index d9aa2f2..69e1ab7 100644
> --- a/Documentation/git-describe.txt
> +++ b/Documentation/git-describe.txt
> @@ -13,9 +13,10 @@ SYNOPSIS
>  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, it suffixes the tag name with the number of
> +additional commits on top of the tagged object and the
> +abbreviated object name of the most recent commit.

Re: [PATCH] Rephrased git-describe description

[Dirk Süsserott]

While we're talking about 'git-describe': I always wondered what the '-g'
in front of the sha1 stands for when I issue 'git describe'. Is it for 
'generation'
or what? Actually I'd appreciate if that '-g' would be dropped as it is of
no use but I also recognize that git-describe is one of the plumbing tools.
I'm just curious.
  Dirk

Junio C Hamano schrieb:
> Ian Hilt <ian.hilt@gmail.com> writes:
>
>   
>> git-describe: Make description more readable.
>>     
>
> Thanks, both.  I think the above is meant to be on the Subject: line, and
> the text certainly is more readable.
>
>   
>> Signed-off-by: Ian Hilt <ian.hilt@gmail.com>
>> ---
>>  Documentation/git-describe.txt |    7 ++++---
>>  1 files changed, 4 insertions(+), 3 deletions(-)
>>
>> diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt
>> index d9aa2f2..69e1ab7 100644
>> --- a/Documentation/git-describe.txt
>> +++ b/Documentation/git-describe.txt
>> @@ -13,9 +13,10 @@ SYNOPSIS
>>  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, it suffixes the tag name with the number of
>> +additional commits on top of the tagged object and the
>> +abbreviated object name of the most recent commit.
>>     
>
> --
> To unsubscribe from this list: send the line "unsubscribe git" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
>
>   

Re: [PATCH] Rephrased git-describe description

[Ian Hilt]

On Wed, 14 May 2008 at 11:46am -0700, Junio C Hamano wrote:

> Ian Hilt <ian.hilt@gmail.com> writes:
>
>> git-describe: Make description more readable.
>
> Thanks, both.  I think the above is meant to be on the Subject: line, and
> the text certainly is more readable.

This is probably a stupid question, but is that all you want for
a commit message?

-- 
Ian Hilt
ian.hilt (at) gmail.com
GnuPG key: 0x4AFC1EE3

Re: [PATCH] Rephrased git-describe description

[Junio C Hamano]

Ian Hilt <ian.hilt@gmail.com> writes:

> On Wed, 14 May 2008 at 11:46am -0700, Junio C Hamano wrote:
>
>> Ian Hilt <ian.hilt@gmail.com> writes:
>>
>>> git-describe: Make description more readable.
>>
>> Thanks, both.  I think the above is meant to be on the Subject: line, and
>> the text certainly is more readable.
>
> This is probably a stupid question, but is that all you want for
> a commit message?

I think the following is clear enough to describe what your patch did.

    commit b7893cde53eb2834deb16820eccb709d2636b81b
    Author: Ian Hilt <ian.hilt@gmail.com>
    Date:   Wed May 14 14:30:55 2008 -0400

        Documentation/git-describe.txt: make description more readable

        Signed-off-by: Ian Hilt <ian.hilt@gmail.com>
        Credit-to: Kevin Ballard <kevin@sb.org>
        Signed-off-by: Junio C Hamano <gitster@pobox.com>

When made into a line in the shortlog, this makes it clear that it affects
the documentation (and documentation only), and it describes what the
patch did.

If there is a guiding principle that drove the change the patch did, and
that guiding principle is something other people can follow when fixing
similar breakages, it often is a good idea to describe what they are in
the body of the commit log message.  But I did not see such a clear,
reusable guiding principle for this change.

What I mean by a guiding principle in this case is something like...

 - command description should start with a clear description of what it
   does, so that the readers can decide if that is the command they want
   to solve their problem with by reading the very first part;

 - and then it should describe how it does it in an unambiguous and easy
   to read language.

Then you can have a comparison between the text before and after the
change to explain why the updated text is more unambiguous.  But you would
risk ending up with a textbook of English composition which is not what we
necessarily want to do here ;-)