Re: [PATCH] reset: update help text

From: Jonathan Nieder <jrnieder@gmail.com>
Date: Mar 31, 2011, 18:42 UTC
Message-ID: <20110331184246.GA19264@elie>
In-Reply-To: <AANLkTiknvWE9Fe3u88Jbis4Cgxd5ubqaR6MzYOJZ-AtM@mail.gmail.com>

Nguyen Thai Ngoc Duy wrote:

> To be honest, I have no idea what the above describes. I read 9bc454d
> (reset: add option "--keep" to "git reset" - 2010-01-19) and figured
> that --keep is like --merge except that "git diff" before and after
> the reset is exactly the same, is it? I have never used --keep before.

I use "git reset --keep" to

 - discard a bad commit: git reset --keep HEAD^
 - start working against a different commit:

	git checkout -b topic &&
	... hack hack hack without committing ... &&
	: "oops, I thought I was on master but I was somewhere else" &&
	git reset --keep master

The spirit of the thing[1] is:

 * if the diff "HEAD -> <commit>" touch paths in which we have local
   changes, error out;
 * otherwise, checkout the relevant paths from <commit> but leave the
   paths in which we have local changes alone.

which indeed means "git diff --cached" and "git diff" before and after would be exactly the same. But there are some edge cases, in which the diff "HEAD -> <commit>" makes the same change we did and the reset --keep is still allowed.

This is totally different from --merge. The only legitimate use of --merge is to cancel a merge you just performed, imho --- the effect otherwise is too scary ("git add <path>; git reset --merge elsewhere" --- bye, bye, changes made at <path>).

Hope that helps, Jonathan

[1] Detailed semantics: for each path listed by "git diff --name-only HEAD <commit>":

 * if the worktree, index, and HEAD match, make the index and worktree
   match <commit>.

 * otherwise, if it is "not easy" to keep local changes, error out.
   We are not going to do a three-way merge.  That is,

   - if the index matches neither HEAD nor <commit>, error out;
   - if the index matches HEAD but not the worktree, error out.

 * otherwise, it is "easy", so keep local changes.

   - if the index already matches <commit>, leave the index and
     worktree alone.
   - if the index and worktree match HEAD, make them match the
     <commit> instead.

These are the same rules used by fast-forward merges and plain "git checkout".