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.


To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Reply via email to