From: Junio C Hamano Date: Wed, 11 Jul 2012 19:45:34 +0000 (-0700) Subject: Merge branch 'cn/cherry-pick-range-docs' into maint X-Git-Tag: v1.7.11.2~9 X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/a0ceb72f38bf841322fc8ce28ea39328e8a5aa19?ds=inline;hp=-c Merge branch 'cn/cherry-pick-range-docs' into maint The documentation for "git cherry-pick A B..C" was misleading. * cn/cherry-pick-range-docs: git-cherry-pick.txt: clarify the use of revision range notation Documentation: --no-walk is no-op if range is specified --- a0ceb72f38bf841322fc8ce28ea39328e8a5aa19 diff --combined Documentation/git-cherry-pick.txt index 9f3dae631e,49ac61c3d0..0e170a51ca --- a/Documentation/git-cherry-pick.txt +++ b/Documentation/git-cherry-pick.txt @@@ -47,7 -47,9 +47,9 @@@ OPTION linkgit:gitrevisions[7]. Sets of commits can be passed but no traversal is done by default, as if the '--no-walk' option was specified, see - linkgit:git-rev-list[1]. + linkgit:git-rev-list[1]. Note that specifying a range will + feed all ... arguments to a single revision walk + (see a later example that uses 'maint master..next'). -e:: --edit:: @@@ -103,25 -105,6 +105,25 @@@ effect to your index in a row cherry-pick'ed commit, then a fast forward to this commit will be performed. +--allow-empty:: + By default, cherry-picking an empty commit will fail, + indicating that an explicit invocation of `git commit + --allow-empty` is required. This option overrides that + behavior, allowing empty commits to be preserved automatically + in a cherry-pick. Note that when "--ff" is in effect, empty + commits that meet the "fast-forward" requirement will be kept + even without this option. Note also, that use of this option only + keeps commits that were initially empty (i.e. the commit recorded the + same tree as its parent). Commits which are made empty due to a + previous commit are dropped. To force the inclusion of those commits + use `--keep-redundant-commits`. + +--keep-redundant-commits:: + If a commit being cherry picked duplicates a commit already in the + current history, it will become empty. By default these + redundant commits are ignored. This option overrides that behavior and + creates an empty commit object. Implies `--allow-empty`. + --strategy=:: Use the given merge strategy. Should only be used once. See the MERGE STRATEGIES section in linkgit:git-merge[1] @@@ -149,7 -132,16 +151,16 @@@ EXAMPLE Apply the changes introduced by all commits that are ancestors of master but not of HEAD to produce new commits. + `git cherry-pick maint next ^master`:: + `git cherry-pick maint master..next`:: + + Apply the changes introduced by all commits that are + ancestors of maint or next, but not master or any of its + ancestors. Note that the latter does not mean `maint` and + everything between `master` and `next`; specifically, + `maint` will not be used if it is included in `master`. + -`git cherry-pick master{tilde}4 master{tilde}2`:: +`git cherry-pick master~4 master~2`:: Apply the changes introduced by the fifth and third last commits pointed to by master and create 2 new commits with @@@ -170,7 -162,7 +181,7 @@@ are in next but not HEAD to the current branch, creating a new commit for each new change. -`git rev-list --reverse master \-- README | git cherry-pick -n --stdin`:: +`git rev-list --reverse master -- README | git cherry-pick -n --stdin`:: Apply the changes introduced by all commits on the master branch that touched README to the working tree and index, diff --combined Documentation/rev-list-options.txt index 1ae3c899ef,5b440294c5..84e34b1aba --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@@ -198,7 -198,7 +198,7 @@@ excluded from the output + For example, `--cherry-pick --right-only A...B` omits those commits from `B` which are in `A` or are patch-equivalent to a commit in -`A`. In other words, this lists the `{plus}` commits from `git cherry A B`. +`A`. In other words, this lists the `+` commits from `git cherry A B`. More precisely, `--cherry-pick --right-only --no-merges` gives the exact list. @@@ -455,7 -455,7 +455,7 @@@ The effect of this is best shown by wa `---------' ----------------------------------------------------------------------- + -Note the major differences in `N` and `P` over '\--full-history': +Note the major differences in `N` and `P` over '--full-history': + -- * `N`'s parent list had `I` removed, because it is an ancestor of the @@@ -494,7 -494,7 +494,7 @@@ of course) When we want to find out what commits in `M` are contaminated with the bug introduced by `D` and need fixing, however, we might want to view only the subset of 'D..M' that are actually descendants of `D`, i.e. -excluding `C` and `K`. This is exactly what the '\--ancestry-path' +excluding `C` and `K`. This is exactly what the '--ancestry-path' option does. Applied to the 'D..M' range, it results in: + ----------------------------------------------------------------------- @@@ -622,6 -622,7 +622,7 @@@ These options are mostly targeted for p --no-walk:: Only show the given revs, but do not traverse their ancestors. + This has no effect if a range is specified. --do-walk::