threads / patch / 13519

patchRephrased git-describe description

Subject: [PATCH] Rephrased git-describe description

## tl;dr

5 messages between May 14, 2008 and May 17, 2008. Diffs are folded; open one to read it.

replies: 4people: 3as markdown or json

Ian Hilt· May 14, 2008, 18:30 UTC · lore
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(-)
Show changes to Documentation/git-describe.txt +4 −3
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
Junio C Hamano· May 14, 2008, 18:46 UTC · re: Ian Hilt · lore

Re: [PATCH] Rephrased git-describe description

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.

Show 20 quoted lines
> 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.
Dirk Süsserott· May 14, 2008, 20:01 UTC · re: Junio C Hamano · lore

Re: [PATCH] Rephrased git-describe description

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:
Show 38 quoted lines
> 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
>
>
Ian Hilt· May 14, 2008, 23:02 UTC · re: Junio C Hamano · lore

Re: [PATCH] Rephrased git-describe description

On Wed, 14 May 2008 at 11:46am -0700, Junio C Hamano wrote:
Show 6 quoted lines
> 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
Junio C Hamano· May 17, 2008, 00:03 UTC · re: Ian Hilt · lore

Re: [PATCH] Rephrased git-describe description

Ian Hilt <ian.hilt@gmail.com> writes:
Show 11 quoted lines
> 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 ;-)

← back to recent threads