patchgit-reset.txt: Use commit~1 notation over commit^

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

In order to easily read paragraphs, use same notation and do not mixed both ^ and ~N. This helps digesting the information more easier as the tokens stay the same (dcumentation uniformity).

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

On Wed, 2010-12-01 at 20:14 +0200, jari.aalto@cante.net wrote:

I have to disagree here. Part of the task of good documentation is to show not just what any one user may prefer (unless it is an accepted standard, such as an RFC) but also what is possible. Removing the non "~" examples is actually a disservice to the documentation reader in a great many cases. What makes more sense in this case is to refer at some point to the documentation which describes the allowed reference formats. This makes it clear that: (1) There are several allowed reference formats, and these are examples using them; (2) These, over here, are descriptions of the allowed reference formats.

Also, strictly speaking, each separate operation example is a "paragraph" inside of a subsection and "EXAMPLES" is the containing section. If you look at it this way it is already reasonably internally consistent.

2010-12-01 21:13 Drew Northup <drew.northup@maine.edu>:

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?

Besides, the "^" key was probably inverted to work easily in US keybord. It is not so in other parts of the world.

The fine print can be reserved to git-rev-parse(1) where you can get all the details.

Jari

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

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

2010-12-02 00:01 Kevin Ballard <kevin@sb.org>:

Yes of course:

    >> What people appreciate, while learning, is constency. Sticking to one
    >> notation is better than giving multiple choices.

Whatever you feel. Consistency is important viewpoint. Try explaining to a group of people these two variations. The make them write scripts to use git commands. Guess which notation they choose? The "^" isnt' even scriptable.

Jari

On Dec 1, 2010, at 2:49 PM, Jari Aalto wrote:

What do you mean? I've personally taught nearly everybody at my office how to use git, and every single one of them uses ^ when they want to go to the previous commit and ~n when they want to go n commits back (where n > 1). Even the few people who knew git before I talked to them use this convention. And guess where those people learned it? By seeing the different syntaxes in the manpage. Even for the people I taught, I never told them expressly to use HEAD^ vs HEAD~3, but through the combination of my examples and the examples in the manpages, they all understood both operators and how to use them without any difficulty whatsoever.

You stated that you have "witnessed close hand for thousands of learners." And you state that these people don't understand this sort of documentation. I don't mean to give offense, but have you ever considered what the common element here is?

-Kevin Ballard

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

There is no question that you need to really count them, and that is why we invented HEAD~8 notation in the first place. It however is wrong to use the above illustration to defend your change that replaces "HEAD^" with "HEAD~1".

The thing is, you need to name/call the previous one a lot more often than you need to call the eighth previous one. The previous one "HEAD~1" is special because it directly relates to the current commit (it is the first parent of the current commit) and that is why people often need to access it.

And "HEAD^" is shorter and much easier to type, and more importantly, it is more often used in the wild, so the readers of the documentation needs to know it anyway to understand what other people do.

2010-12-02 00:06 Junio C Hamano <gitster@pobox.com>:

I don't know in which part of world that is, probably only using US keyboard. Not so elsewhere with keyboards more than just only ASCII characters.

Jari

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

On a German keyboard ~ is awkward to type (AltGr-+) whereas ^ is on an unshifted key.

Andreas.

2010-12-02 02:07 Andreas Schwab <schwab@linux-m68k.org>:

And notebook/laptops in German? For FI-keyboards everything is pain.

Jari

On Wed, Dec 1, 2010 at 11:06 PM, Junio C Hamano <gitster@pobox.com> wrote:

Additionaly, you must know about the ^ notation. That is the only way refer to the second parent HEAD^2, for example.

HTH, Santi

2010-12-02 00:56 Santi Béjar <santi@agolina.net>:

If "must" is a requirement, I have to regret that there has yet to have been a situation where I would ahve a need to refer to "second parent".

I guess most of the basic features can be used without it.

Jari

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

It doesn't matter. There needs to be a better reason than "Jari doesn't like it."

-Miles

2010-12-02 08:17 Miles Bader <miles@gnu.org>:

This has nothing to do with liking. It how infomation is read. When information is consistent, it lessens cognitive load.

In the  "fine print" git-rev-parse(1) there can be the gory details.

most of the commenters probably are already experts and therefor wear "expert glasses on". It's not necessarily the same for starters. Certainly not when you try to teach 100 people. One form is much better in that situation than variations. You only do it at the end:

    "[After finishing 6 week training] Btw, if you need more details
    look at...."

Experts can later pick anything they want.

Jari

On Thu, 2010-12-02 at 14:14 +0200, Jari Aalto wrote:

I have worked in instructional settings, as the instructor. I can say flat out that this is an incomplete view of the learning patterns of people being newly exposed to a concept or a technology. Besides, many people who consult manpages often think of themselves as experts (and may think better of the idea after consulting the documentation).

The reality is that learning is not nearly as proscribed and rote a process as you are making it out to be. Rote memorization is good for learning multiplications tables, alphabets, and the approximate values of e and pi. It is not particularly suited for learning grammars and syntaxes--which is why language and algebra are typically not taught that way. Programming and using computers benefits greatly from presenting multiple varied examples--even to the supposed experts who probably don't know it all either.

Leave the odd examples in the manpages--people depend on them being there.

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

No, it has to do with your trying to impose your personal tastes.

^ (and ^^, etc) is a simpler and easier concept to deal with, and sufficient for the vast majority of tasks -- beyond 1 or 2 levels, it's typically easier to just use an absolute reference cut-and-pasted from git log output than it is to count commits and get the right value to use with ~ (and from experience, unless you're careful, it's very easy to get counts for ~ wrong). So it's ~ that's the "expert notation", not ^.

[How do I know? Because I've _been_ a git beginner, and spent a long time trying to learn git.]

-Miles

| ^ (and ^^, etc) is a simpler and easier concept to deal with, and
| ... very easy to get counts for ~ wrong).  So it's ~ that's the
| "expert notation", not ^.

Not that it matters, but have you happende to notice that all git outputs use

    commit~N

notation. Not the

    commit^

Jari

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

Did you try "git show-branch -a" recently?

Andreas.

Andreas Schwab <schwab@linux-m68k.org> writes:

Perhaps we need to also fix "git name-rev master^" which currently does not try to reduce "master~1" to "master^".

On Thu, Dec 02, 2010 at 09:55:03AM -0800, Junio C Hamano wrote:

This patch does it:

Jeff King <peff@peff.net> writes:

Curious. Why does the "first take the first parent of rc2" is left as-is, while "then lastly take its parent" does get shortened?

On Thu, Dec 02, 2010 at 10:54:03AM -0800, Junio C Hamano wrote:

Because my patch is crappy and I didn't spend more than 30 seconds testing it? :)

It needs a similar change elsewhere, so the full patch should be:

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

Seriously:  People like ^.

This doc change is not good (and seems to demonstrate a lack of familiarity with typical git usage)....

-Miles