Re: Reset by checkout?

From: Kevin Bracey <kevin@bracey.fi>
Date: Jun 3, 2014, 19:48 UTC
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:

Show 11 quoted lines

>
> 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