diff options
| author | Vincent Ambo <Vincent Ambo> | 2020-01-11T23·36+0000 |
|---|---|---|
| committer | Vincent Ambo <Vincent Ambo> | 2020-01-11T23·40+0000 |
| commit | 7ef0d62730840ded097b524104cc0a0904591a63 (patch) | |
| tree | a670f96103667aeca4789a95d94ca0dff550c4ce /third_party/git/Documentation/git-cherry.txt | |
| parent | 6a2a3007077818e24a3d56fc492ada9206a10cf0 (diff) | |
| parent | 1b593e1ea4d2af0f6444d9a7788d5d99abd6fde5 (diff) | |
merge(third_party/git): Merge squashed git subtree at v2.23.0 r/373
Merge commit '1b593e1ea4d2af0f6444d9a7788d5d99abd6fde5' as 'third_party/git'
Diffstat (limited to 'third_party/git/Documentation/git-cherry.txt')
| -rw-r--r-- | third_party/git/Documentation/git-cherry.txt | 145 |
1 files changed, 145 insertions, 0 deletions
diff --git a/third_party/git/Documentation/git-cherry.txt b/third_party/git/Documentation/git-cherry.txt new file mode 100644 index 000000000000..0ea921a59316 --- /dev/null +++ b/third_party/git/Documentation/git-cherry.txt @@ -0,0 +1,145 @@ +git-cherry(1) +============= + +NAME +---- +git-cherry - Find commits yet to be applied to upstream + +SYNOPSIS +-------- +[verse] +'git cherry' [-v] [<upstream> [<head> [<limit>]]] + +DESCRIPTION +----------- +Determine whether there are commits in `<head>..<upstream>` that are +equivalent to those in the range `<limit>..<head>`. + +The equivalence test is based on the diff, after removing whitespace +and line numbers. git-cherry therefore detects when commits have been +"copied" by means of linkgit:git-cherry-pick[1], linkgit:git-am[1] or +linkgit:git-rebase[1]. + +Outputs the SHA1 of every commit in `<limit>..<head>`, prefixed with +`-` for commits that have an equivalent in <upstream>, and `+` for +commits that do not. + +OPTIONS +------- +-v:: + Show the commit subjects next to the SHA1s. + +<upstream>:: + Upstream branch to search for equivalent commits. + Defaults to the upstream branch of HEAD. + +<head>:: + Working branch; defaults to HEAD. + +<limit>:: + Do not report commits up to (and including) limit. + +EXAMPLES +-------- + +Patch workflows +~~~~~~~~~~~~~~~ + +git-cherry is frequently used in patch-based workflows (see +linkgit:gitworkflows[7]) to determine if a series of patches has been +applied by the upstream maintainer. In such a workflow you might +create and send a topic branch like this: + +------------ +$ git checkout -b topic origin/master +# work and create some commits +$ git format-patch origin/master +$ git send-email ... 00* +------------ + +Later, you can see whether your changes have been applied by saying +(still on `topic`): + +------------ +$ git fetch # update your notion of origin/master +$ git cherry -v +------------ + +Concrete example +~~~~~~~~~~~~~~~~ + +In a situation where topic consisted of three commits, and the +maintainer applied two of them, the situation might look like: + +------------ +$ git log --graph --oneline --decorate --boundary origin/master...topic +* 7654321 (origin/master) upstream tip commit +[... snip some other commits ...] +* cccc111 cherry-pick of C +* aaaa111 cherry-pick of A +[... snip a lot more that has happened ...] +| * cccc000 (topic) commit C +| * bbbb000 commit B +| * aaaa000 commit A +|/ +o 1234567 branch point +------------ + +In such cases, git-cherry shows a concise summary of what has yet to +be applied: + +------------ +$ git cherry origin/master topic +- cccc000... commit C ++ bbbb000... commit B +- aaaa000... commit A +------------ + +Here, we see that the commits A and C (marked with `-`) can be +dropped from your `topic` branch when you rebase it on top of +`origin/master`, while the commit B (marked with `+`) still needs to +be kept so that it will be sent to be applied to `origin/master`. + + +Using a limit +~~~~~~~~~~~~~ + +The optional <limit> is useful in cases where your topic is based on +other work that is not in upstream. Expanding on the previous +example, this might look like: + +------------ +$ git log --graph --oneline --decorate --boundary origin/master...topic +* 7654321 (origin/master) upstream tip commit +[... snip some other commits ...] +* cccc111 cherry-pick of C +* aaaa111 cherry-pick of A +[... snip a lot more that has happened ...] +| * cccc000 (topic) commit C +| * bbbb000 commit B +| * aaaa000 commit A +| * 0000fff (base) unpublished stuff F +[... snip ...] +| * 0000aaa unpublished stuff A +|/ +o 1234567 merge-base between upstream and topic +------------ + +By specifying `base` as the limit, you can avoid listing commits +between `base` and `topic`: + +------------ +$ git cherry origin/master topic base +- cccc000... commit C ++ bbbb000... commit B +- aaaa000... commit A +------------ + + +SEE ALSO +-------- +linkgit:git-patch-id[1] + +GIT +--- +Part of the linkgit:git[1] suite |