* [PATCH] Rephrased git-describe description
@ 2008-05-14 18:30 Ian Hilt
2008-05-14 18:46 ` Junio C Hamano
0 siblings, 1 reply; 9+ messages in thread
From: Ian Hilt @ 2008-05-14 18:30 UTC (permalink / raw)
To: git; +Cc: 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
^ permalink raw reply related [flat|nested] 9+ messages in thread
* Re: [PATCH] Rephrased git-describe description
2008-05-14 18:30 [PATCH] Rephrased git-describe description Ian Hilt
@ 2008-05-14 18:46 ` Junio C Hamano
2008-05-14 20:01 ` Dirk Süsserott
2008-05-14 23:02 ` Ian Hilt
0 siblings, 2 replies; 9+ messages in thread
From: Junio C Hamano @ 2008-05-14 18:46 UTC (permalink / raw)
To: Ian Hilt; +Cc: git, Kevin Ballard
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.
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PATCH] Rephrased git-describe description
2008-05-14 18:46 ` Junio C Hamano
@ 2008-05-14 20:01 ` Dirk Süsserott
2008-05-14 23:02 ` Ian Hilt
1 sibling, 0 replies; 9+ messages in thread
From: Dirk Süsserott @ 2008-05-14 20:01 UTC (permalink / raw)
To: Junio C Hamano; +Cc: Ian Hilt, git, Kevin Ballard
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
>
>
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PATCH] Rephrased git-describe description
2008-05-14 18:46 ` Junio C Hamano
2008-05-14 20:01 ` Dirk Süsserott
@ 2008-05-14 23:02 ` Ian Hilt
2008-05-17 0:03 ` Junio C Hamano
1 sibling, 1 reply; 9+ messages in thread
From: Ian Hilt @ 2008-05-14 23:02 UTC (permalink / raw)
To: Junio C Hamano; +Cc: Git Mailing List, Kevin Ballard
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
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PATCH] Rephrased git-describe description
2008-05-14 23:02 ` Ian Hilt
@ 2008-05-17 0:03 ` Junio C Hamano
0 siblings, 0 replies; 9+ messages in thread
From: Junio C Hamano @ 2008-05-17 0:03 UTC (permalink / raw)
To: Ian Hilt; +Cc: Git Mailing List, Kevin Ballard
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 ;-)
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PATCH] Rephrased git-describe description
2008-05-14 18:00 ` Ian Hilt
@ 2008-05-14 18:03 ` Kevin Ballard
0 siblings, 0 replies; 9+ messages in thread
From: Kevin Ballard @ 2008-05-14 18:03 UTC (permalink / raw)
To: Ian Hilt; +Cc: Git Mailing List
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
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PATCH] Rephrased git-describe description
2008-05-14 16:57 ` Kevin Ballard
@ 2008-05-14 18:00 ` Ian Hilt
2008-05-14 18:03 ` Kevin Ballard
0 siblings, 1 reply; 9+ messages in thread
From: Ian Hilt @ 2008-05-14 18:00 UTC (permalink / raw)
To: Kevin Ballard; +Cc: Git Mailing List
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
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PATCH] Rephrased git-describe description
2008-05-14 14:22 Ian Hilt
@ 2008-05-14 16:57 ` Kevin Ballard
2008-05-14 18:00 ` Ian Hilt
0 siblings, 1 reply; 9+ messages in thread
From: Kevin Ballard @ 2008-05-14 16:57 UTC (permalink / raw)
To: Ian Hilt; +Cc: git
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
^ permalink raw reply [flat|nested] 9+ messages in thread
* [PATCH] Rephrased git-describe description
@ 2008-05-14 14:22 Ian Hilt
2008-05-14 16:57 ` Kevin Ballard
0 siblings, 1 reply; 9+ messages in thread
From: Ian Hilt @ 2008-05-14 14:22 UTC (permalink / raw)
To: git; +Cc: 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
^ permalink raw reply related [flat|nested] 9+ messages in thread
end of thread, other threads:[~2008-05-17 0:04 UTC | newest]
Thread overview: 9+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2008-05-14 18:30 [PATCH] Rephrased git-describe description Ian Hilt
2008-05-14 18:46 ` Junio C Hamano
2008-05-14 20:01 ` Dirk Süsserott
2008-05-14 23:02 ` Ian Hilt
2008-05-17 0:03 ` Junio C Hamano
-- strict thread matches above, loose matches on Subject: below --
2008-05-14 14:22 Ian Hilt
2008-05-14 16:57 ` Kevin Ballard
2008-05-14 18:00 ` Ian Hilt
2008-05-14 18:03 ` Kevin Ballard
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.