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
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html