Re: [PATCH] Rephrased git-describe description

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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@xxxxxx
http://www.tildesoft.com


--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[Index of Archives]     [Linux Kernel Development]     [Gcc Help]     [IETF Annouce]     [DCCP]     [Netdev]     [Networking]     [Security]     [V4L]     [Bugtraq]     [Yosemite]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Linux SCSI]     [Fedora Users]

  Powered by Linux