Re: [PATCH] git-reset.txt: Use commit~1 notation over commit^

From: Kevin Ballard <kevin@sb.org>
Date: Dec 1, 2010, 22:01 UTC
Message-ID: <26B3CE3C-0C45-4D0B-8588-3769467AF527@sb.org>
In-Reply-To: <877hftuvvz.fsf@picasso.cante.net>

On Dec 1, 2010, at 11:37 AM, Jari Aalto wrote:

Show 15 quoted lines

> 2010-12-01 21:13 Drew Northup <drew.northup@maine.edu>:
>> "~" examples is actually a disservice to the documentation reader in a
> 
> Well. What I can say. I have witnessed close hand for thousands of
> learners. Unfortunately they don't get educated that way. Bright people
> may. But I'd rather address average Joe who is switching from SVN or the
> like.
> 
> What people appreciate, while learning, is constency. Sticking to one
> notation is better than giving multiple choices. And the "^" isn't
> exactly readable, don't you agree?
> 
>    HEAD^^^^^^^^
> 
> Right. How many was there again?

Your patch isn't touching any example of HEAD^^^^^^^. Every single one that you've changed was a simple HEAD^. And this, I feel, is absolutely wrong. HEAD^ is far more common notation than HEAD~1, and should be preserved as such in the manpage. I also agree with Drew that giving examples with different notation is useful to show alternative syntax. If the manpages all use a single notation when there are several options, it gives the impression that this one notation is what you should always use. And that's not what the manpage is trying to say.

-Kevin Ballard