patchgit-reset.txt: Use uniform HEAD~N notation in all examples

The manual mixed both caret(HEAD^) and tilde (HEAD~N) notation in examples. This may be xconfusing to new users. The "counting" notation HEAD~N likely to be grasped more easily because it allow successive numbering 1, 2, 3 etc.

Signed-off-by: Jari Aalto <jari.aalto@cante.net>
---
 Documentation/git-reset.txt |    6 +++---
 1 files changed, 3 insertions(+), 3 deletions(-)

Jari Aalto <jari.aalto@cante.net> writes:

I am mildly negative on this change.

Referring to (rather, "having to refer to" to fix mistakes) the previous commit happens far more often than referring to an ancestor of an arbitrary generation away (i.e. HEAD~$n). I think it is a better idea to expose users early on that HEAD^ notation which is shorter to type.

Junio C Hamano <gitster@pobox.com> writes:

If the page contains/combines many different ways of doing things, this creates confusion, especially if the distictions are not explained. And it would be unnecessary to explain the HEAD^ and HEAD~1 similarities in every page where these two get mixed.

PRICPLES:

1. The novice user is best served by making things simple and uniform.

2. Utilize concepts that may already be familar. E.g. other VCS/SCM tools
   have concept of counting back revisions with negative numbers: -1,
   -2, -3; so following this same idea in git manual pages would 
   already rang associated bells.

Like:

    HEAD, HEAD~1, HEAD~2

If the syntax is changed in the middle (as it was in manual page), that interrupts the kognitive flow of reading.

    HEAD, HEAD^, HEAD~2

I'm sure when user progresses with his learning, the differences or similarities of the notations become no-op.

But manual pages are served for wide audience. They are most important to new users.

I hope we could strive for KISS is possible.

Jari Aalto <jari.aalto@cante.net> writes:

I still would prefer to teach people HEAD^ earlier. If you _REALLY_ insist, I can live with spelling the HEAD~2 as HEAD^^ for consistency.

Wasn't with you that earlier I discussed that very basic things such as revision naming and range notation should be moved from rev-list documentation to more central place, and sructure the documentation in such a way that these should be read even before individual manual pages are consulted? If we follow that, then by the time people read these examples, they _ought_ to know that HEAD~1 is a longer-to-type way to say HEAD^ already.

On Sat, Sep 01, 2007 at 02:40:22AM -0700, Junio C Hamano wrote:

Well I am a new user to git and I didn't find the mixed notation confusing at all. Perhaps this is because I read the tutorial first, then the git user manual which both explain this clearly.

In either case I think eliminating either notation from the man pages is a bad idea. I'm quite confident that in the worst case a user will think that if they want to refer to the parent they have to say HEAD^ and if they want to refer to the grandparent they have to say HEAD~2. Most won't even find that strange since HEAD^ just seems shorter. I also think many users will be smart enough to infer that if they wanted to they could say HEAD~3 or perhaps HEAD~1, though unless I saw it somewhere I might not have guessed HEAD^^.

Shawn Bohrer <shawn.bohrer@gmail.com> writes:

Naturally one's learning path is naturally different. Did you come from other SCM/VCS before intorduced to git?

That was not proposed. There a mnay pages that use and shoudl use the ^ notations. I was proposing that only (git-COMMAND) were dealt with.

After all, the ^ very differento to what other SCM/VCSs use.

Jari

Jari Aalto <jari.aalto@cante.net> writes:

It's something I _constantly_ wished other SCM/VCSs had, as it's far, far, more usable than the typical absolute rev numbers. It really should be introduced as early as possible.

-Miles