# [PATCH] Rephrased git-describe description 5 messages from 2008-05-14 to 2008-05-17. Participants: Ian Hilt, Junio C Hamano, Dirk Süsserott. Thread: https://gitlist.dev/t/13519 ## Ian Hilt, 2008-05-14 18:30 Subject: [PATCH] Rephrased git-describe description Message-ID: <1210789855-29413-1-git-send-email-ian.hilt@gmail.com> URL: https://gitlist.dev/e/1210789855-29413-1-git-send-email-ian.hilt%40gmail.com ``` git-describe: Make description more readable. Signed-off-by: Ian Hilt --- 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 ``` ## Junio C Hamano, 2008-05-14 18:46 Subject: Re: [PATCH] Rephrased git-describe description Message-ID: <7v7idwoh9m.fsf@gitster.siamese.dyndns.org> URL: https://gitlist.dev/e/7v7idwoh9m.fsf%40gitster.siamese.dyndns.org In-Reply-To: <1210789855-29413-1-git-send-email-ian.hilt@gmail.com> ``` Ian Hilt 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 > --- > 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, 2008-05-14 20:01 Subject: Re: [PATCH] Rephrased git-describe description Message-ID: <482B4526.9020905@dirk.my1.cc> URL: https://gitlist.dev/e/482B4526.9020905%40dirk.my1.cc In-Reply-To: <7v7idwoh9m.fsf@gitster.siamese.dyndns.org> ``` 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 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 >> --- >> 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, 2008-05-14 23:02 Subject: Re: [PATCH] Rephrased git-describe description Message-ID: URL: https://gitlist.dev/e/alpine.LNX.1.10.0805141856380.30187%40sys-0.hiltweb.site In-Reply-To: <7v7idwoh9m.fsf@gitster.siamese.dyndns.org> ``` On Wed, 14 May 2008 at 11:46am -0700, Junio C Hamano wrote: > Ian Hilt 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, 2008-05-17 00:03 Subject: Re: [PATCH] Rephrased git-describe description Message-ID: <7vej81er0r.fsf@gitster.siamese.dyndns.org> URL: https://gitlist.dev/e/7vej81er0r.fsf%40gitster.siamese.dyndns.org In-Reply-To: ``` Ian Hilt writes: > On Wed, 14 May 2008 at 11:46am -0700, Junio C Hamano wrote: > >> Ian Hilt 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 Date: Wed May 14 14:30:55 2008 -0400 Documentation/git-describe.txt: make description more readable Signed-off-by: Ian Hilt Credit-to: Kevin Ballard Signed-off-by: Junio C Hamano 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 ;-) ```