From: Kevin Bracey <kevin@bracey.fi>
Date: Tue, 03 Jun 2014 19:48:49 GMT
Subject: Re: Reset by checkout?
Message-ID: <538E26A1.5020509@bracey.fi>
In-Reply-To: <xmqqmwdv2d08.fsf@gitster.dls.corp.google.com>

On 03/06/2014 00:54, Junio C Hamano wrote:
>
> Not that I can think of a better way to update these descriptions,
> and not that I am opposing to update these descriptions to make it
> easier for new people to learn, but I am not sure if these "treat
> ORIG_HEAD and the changes since that commit as separate entities"
> is a good approach to do so.
>
> Somewhat frustrated, not by your patch but by being unable to
> suggest a better way X-<.
>
>

I know. I started off myself knowing what I meant to say, and then got 
bogged down somewhat trying to be detailed enough for a full 
explanation. I think it's just inherently very hard for anyone to 
visualise what these do in the /general/ case.

This is one of those commands where the structure of a man page gets in 
the way. We have to give a summary of what the mode options /do/, but 
that's not what people want to know. They want to know what they're /for/.

(And, to some extent, reset, like checkout, is two separate commands. 
One being the path manipulator, the other being the HEAD manipulator. 
Just bogs us down further).

I think these are the most important HEAD resets, covering 95%+ of uses:

    git reset --soft HEAD~<n>
    git reset HEAD~<n>
    git reset --keep HEAD~<n>
    git reset --keep ORIG_HEAD
    git reset --keep @{<n>}
    git reset --keep <some other arbitary place>

(and possibly

    git reset --merge

although I think this should be fully covered by "git xxx --abort" - 
maybe a couple of those missing like git stash pop/apply --abort?)

Anything more than those, I think, are pretty far-fetched. I can't 100% 
grok "--soft/--mixed" onto a different branch, for example. (But at 
least we do define those cases in the A/B/C/D "discussion" section for 
the real geeks.)

Maybe we just need to tighten up the EXAMPLES section? Give it 
easy-to-locate <path>/--soft/--mixed/--keep subheadings, covering all 
those common use cases (in clean trees...), including a before/after git 
status views. Then normal users could skip the top technical section 
waffling about indexes and go straight there instead.

Kevin