From: Junio C Hamano <gitster@pobox.com>
Date: Mon, 16 May 2011 23:38:56 +0000 (-0700)
Subject: Merge branch 'ss/cherry-pick-x-doc' into maint
X-Git-Tag: v1.7.5.2~4
X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/0f51322a6be0d31f299df7becad438e8edfb608b?ds=inline;hp=-c

Merge branch 'ss/cherry-pick-x-doc' into maint

* ss/cherry-pick-x-doc:
doc: Clarify that "cherry-pick -x" does not use "git notes"
---

0f51322a6be0d31f299df7becad438e8edfb608b
diff --combined Documentation/git-cherry-pick.txt
index 01db83039f,6ba3230401..9d8fe0d261
--- a/Documentation/git-cherry-pick.txt
+++ b/Documentation/git-cherry-pick.txt
@@@ -16,25 -16,6 +16,25 @@@ Given one or more existing commits, app
  introduces, recording a new commit for each.  This requires your
  working tree to be clean (no modifications from the HEAD commit).
  
 +When it is not obvious how to apply a change, the following
 +happens:
 +
 +1. The current branch and `HEAD` pointer stay at the last commit
 +   successfully made.
 +2. The `CHERRY_PICK_HEAD` ref is set to point at the commit that
 +   introduced the change that is difficult to apply.
 +3. Paths in which the change applied cleanly are updated both
 +   in the index file and in your working tree.
 +4. For conflicting paths, the index file records up to three
 +   versions, as described in the "TRUE MERGE" section of
 +   linkgit:git-merge[1].  The working tree files will include
 +   a description of the conflict bracketed by the usual
 +   conflict markers `<<<<<<<` and `>>>>>>>`.
 +5. No other modifications are made.
 +
 +See linkgit:git-merge[1] for some hints on resolving such
 +conflicts.
 +
  OPTIONS
  -------
  <commit>...::
@@@ -51,9 -32,10 +51,10 @@@
  	message prior to committing.
  
  -x::
- 	When recording the commit, append to the original commit
- 	message a note that indicates which commit this change
- 	was cherry-picked from.  Append the note only for cherry
+ 	When recording the commit, append a line that says
+ 	"(cherry picked from commit ...)" to the original commit
+ 	message in order to indicate which commit this change was
+ 	cherry-picked from.  This is done only for cherry
  	picks without conflicts.  Do not use this option if
  	you are cherry-picking from your private branch because
  	the information is useless to the recipient.  If on the
@@@ -98,16 -80,6 +99,16 @@@ effect to your index in a row
  	cherry-pick'ed commit, then a fast forward to this commit will
  	be performed.
  
 +--strategy=<strategy>::
 +	Use the given merge strategy.  Should only be used once.
 +	See the MERGE STRATEGIES section in linkgit:git-merge[1]
 +	for details.
 +
 +-X<option>::
 +--strategy-option=<option>::
 +	Pass the merge strategy-specific option through to the
 +	merge strategy.  See linkgit:git-merge[1] for details.
 +
  EXAMPLES
  --------
  git cherry-pick master::
@@@ -149,27 -121,13 +150,27 @@@ git rev-list --reverse master \-- READM
  	so the result can be inspected and made into a single new
  	commit if suitable.
  
 -Author
 -------
 -Written by Junio C Hamano <gitster@pobox.com>
 -
 -Documentation
 ---------------
 -Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
 +The following sequence attempts to backport a patch, bails out because
 +the code the patch applies to has changed too much, and then tries
 +again, this time exercising more care about matching up context lines.
 +
 +------------
 +$ git cherry-pick topic^             <1>
 +$ git diff                           <2>
 +$ git reset --merge ORIG_HEAD        <3>
 +$ git cherry-pick -Xpatience topic^  <4>
 +------------
 +<1> apply the change that would be shown by `git show topic^`.
 +In this example, the patch does not apply cleanly, so
 +information about the conflict is written to the index and
 +working tree and no new commit results.
 +<2> summarize changes to be reconciled
 +<3> cancel the cherry-pick.  In other words, return to the
 +pre-cherry-pick state, preserving any local modifications you had in
 +the working tree.
 +<4> try to apply the change introduced by `topic^` again,
 +spending extra time to avoid mistakes based on incorrectly matching
 +context lines.
  
  SEE ALSO
  --------