git reset --keep (Re: What's cooking in git.git (Mar 2010, #01; Wed, 03))

Junio C Hamano wrote:

Do you think I finally understood what "reset --keep" is about?

Probably. :)  Let me take the opportunity to give some examples of what
I am hoping to use it for, to see if I am crazy.

Nah, what was I thinking.  If I rephrase your side note <2> and <3> a
little bit, everything makes sense.  Perhaps like so:

    <2> In the ideal world, you could have realized that the earlier
    commit did not belong to the new topic when you created and switched
    to branch2 (i.e. "git checkout -b branch2 start"), but nobody is
    perfect.

    <3> But you can use "reset --keep" to remove the unwanted commit after
    you switched to "branch2".

And it becomes very clear that "reset --keep" is a sensible way to recover
from this mistake.  No need to do "read-tree -m -u" followed by "reset"
anymore.

Yes, this (recovery from a wrong choice of starting commit for a new
branch) makes sense.  Here are some other planned uses:

1. Helping people new to git.

A person not very familiar with git comes to me asking how to undo
the last couple of commits.  After a quick conversation, it becomes
clear that the commits in question were not pushed out to any public
repository and that this person does not feel it would be useful to
publish the problem commits.

Currently, I would have to advise such a person to use

	git reset --hard HEAD^^

I would prefer to recommend

	git reset --keep HEAD^^

because if there are uncommitted changes then it will give a "needs
update" message (right?) and I can help the person to deal with it.

2. Splitting up a huge patch.

Suppose I have a huge patch consisting of several unrelated changes
applied to the work tree but not commited.  I want to split it into
logical changes, commiting each one, and when I am done I will use a
loop reading from git rev-list to test all the resulting commits
automatically.  A workflow for this looks something like the
following:

 git checkout -b series1
 git add -p
 git commit
 git add -p
 git commit
 git checkout -b series2 appropriate-base
 git add -p
 git commit
 ...

Having 'git reset --keep' available would add some flexibility:

 * As you mentioned, reset --keep would let me recover from 'git
   checkout -b' to the wrong commit.
 * As in example 1, if some part of the patch turns out to be a
   bad idea after all, I can try to discard it.

A 'git stash' might be worth avoiding in some cases because it touches
unrelated files, which means wasted time rebuilding everything.

3. Keeping unrelated extra changes around.

Suppose I am Linus, and I keep on forgetting to update the version
number in a file named version.h or something.  So I update it in
advance as soon as I remember, but I do not commit the change or
register it in the index because it is not time yet.

Then in almost every instance when I would have normally used
'reset --hard', I should use 'reset --keep' instead.  The only
exception is when I am mean “screw it all, reset to a completely
known state”; in that case, I will have to update version.h by hand
again.