[PATCH] cherry-pick: when pick fails, explain how to cancel

[Jonathan Nieder <jrnieder@gmail.com>]

If you tried a cherry-pick or revert resulting in complex conflicts
and want to start over, "git reset --merge HEAD" might help.

Requested-by: Piotr Krukowiecki <piotr.krukowiecki@gmail.com>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
(+cc some relevant people. Johan wrote merge --abort, Jay is adding
a status hint during cherry-pick, Christian wrote reset --merge and
much related cherry-pick functionality)

Piotr Krukowiecki wrote:

> Example of cherry-pick conflict:
>
>    $ git cherry-pick  c64e8caa56fd76577bbaea37592f4a9df10ab1b8
>    error: could not apply c64e8ca... <<commit message>>
>    hint: after resolving the conflicts, mark the corrected paths
>    hint: with 'git add <paths>' or 'git rm <paths>'
>
>    $ git status
>    # On branch master
>    # Unmerged paths:
[...]
> I see following possibilities:
>
> 1. add hint to cherry-pick how to abort merge, for example:
>    hint: use 'git reset --merge ORIG_HEAD' to abort merge

Good idea.  "git cherry-pick" does not set ORIG_HEAD, so I
put "git reset --merge HEAD" instead.

> 2. add hint to status how to abort merge, for example:
>    #   (use 'git reset --merge ORIG_HEAD' to abort merge)

"git reset --merge" will remove local changes marked with "git add",
under the assumption that they were part of the conflict resolution
and thus should be cleared away.

This leaves me afraid of the following scenario:

	git pull
	# conflict?  agh!

	# ... two days later ...
	... hack hack hack ...
	... add add add ...
	git commit;	# fails because of unmerged files

	# whoops, forgot about that merge.
	# Let's do what it says to do:
	git reset --merge ORIG_HEAD

It seems safest to only recommend "reset --merge" immediately
after a mergy operation.

> The ORIG_HEAD is specified in man page example.

I assume you mean on the git-reset page?  It might be nice to add
more examples and to update the current ones with current best
practice (e.g., using reset --keep more often).

The use of ORIG_HEAD there also allows the following:

	git pull
	# success?  But I didn't want that
	git reset --merge ORIG_HEAD

and protects against situations in which ORIG_HEAD is not present
(though merge --abort does that better, I think).

> git-cherry-pick uses word "cancel" in man page (in example) and
> git-merge uses word "abort" for (as I understand) the same action.

Hmm, where is this example in the cherry-pick manpage?

Thanks for the suggestions.  Generally speaking, I like them.

 builtin/revert.c |    4 +++-
 1 files changed, 3 insertions(+), 1 deletions(-)

diff --git a/builtin/revert.c b/builtin/revert.c
index dc1b702..78baae7 100644
--- a/builtin/revert.c
+++ b/builtin/revert.c
@@ -267,11 +267,13 @@ static void print_advice(void)
 	}
 
 	advise("after resolving the conflicts, mark the corrected paths");
-	advise("with 'git add <paths>' or 'git rm <paths>'");
+	advise("with 'git add <paths>' and 'git rm <paths>'");
 
 	if (action == CHERRY_PICK)
 		advise("and commit the result with 'git commit -c %s'",
 		       find_unique_abbrev(commit->object.sha1, DEFAULT_ABBREV));
+
+	advise("or use 'git reset --merge HEAD' to abort");
 }
 
 static void write_message(struct strbuf *msgbuf, const char *filename)
-- 
1.7.4.1