.gitignore: "git-verify-commit" is a generated file
[git.git] / Documentation / git-cherry.txt
blob0ea921a5931647f21f74a44a80622c3d3c16827c
1 git-cherry(1)
2 =============
4 NAME
5 ----
6 git-cherry - Find commits yet to be applied to upstream
8 SYNOPSIS
9 --------
10 [verse]
11 'git cherry' [-v] [<upstream> [<head> [<limit>]]]
13 DESCRIPTION
14 -----------
15 Determine whether there are commits in `<head>..<upstream>` that are
16 equivalent to those in the range `<limit>..<head>`.
18 The equivalence test is based on the diff, after removing whitespace
19 and line numbers.  git-cherry therefore detects when commits have been
20 "copied" by means of linkgit:git-cherry-pick[1], linkgit:git-am[1] or
21 linkgit:git-rebase[1].
23 Outputs the SHA1 of every commit in `<limit>..<head>`, prefixed with
24 `-` for commits that have an equivalent in <upstream>, and `+` for
25 commits that do not.
27 OPTIONS
28 -------
29 -v::
30         Show the commit subjects next to the SHA1s.
32 <upstream>::
33         Upstream branch to search for equivalent commits.
34         Defaults to the upstream branch of HEAD.
36 <head>::
37         Working branch; defaults to HEAD.
39 <limit>::
40         Do not report commits up to (and including) limit.
42 EXAMPLES
43 --------
45 Patch workflows
46 ~~~~~~~~~~~~~~~
48 git-cherry is frequently used in patch-based workflows (see
49 linkgit:gitworkflows[7]) to determine if a series of patches has been
50 applied by the upstream maintainer.  In such a workflow you might
51 create and send a topic branch like this:
53 ------------
54 $ git checkout -b topic origin/master
55 # work and create some commits
56 $ git format-patch origin/master
57 $ git send-email ... 00*
58 ------------
60 Later, you can see whether your changes have been applied by saying
61 (still on `topic`):
63 ------------
64 $ git fetch  # update your notion of origin/master
65 $ git cherry -v
66 ------------
68 Concrete example
69 ~~~~~~~~~~~~~~~~
71 In a situation where topic consisted of three commits, and the
72 maintainer applied two of them, the situation might look like:
74 ------------
75 $ git log --graph --oneline --decorate --boundary origin/master...topic
76 * 7654321 (origin/master) upstream tip commit
77 [... snip some other commits ...]
78 * cccc111 cherry-pick of C
79 * aaaa111 cherry-pick of A
80 [... snip a lot more that has happened ...]
81 | * cccc000 (topic) commit C
82 | * bbbb000 commit B
83 | * aaaa000 commit A
85 o 1234567 branch point
86 ------------
88 In such cases, git-cherry shows a concise summary of what has yet to
89 be applied:
91 ------------
92 $ git cherry origin/master topic
93 - cccc000... commit C
94 + bbbb000... commit B
95 - aaaa000... commit A
96 ------------
98 Here, we see that the commits A and C (marked with `-`) can be
99 dropped from your `topic` branch when you rebase it on top of
100 `origin/master`, while the commit B (marked with `+`) still needs to
101 be kept so that it will be sent to be applied to `origin/master`.
104 Using a limit
105 ~~~~~~~~~~~~~
107 The optional <limit> is useful in cases where your topic is based on
108 other work that is not in upstream.  Expanding on the previous
109 example, this might look like:
111 ------------
112 $ git log --graph --oneline --decorate --boundary origin/master...topic
113 * 7654321 (origin/master) upstream tip commit
114 [... snip some other commits ...]
115 * cccc111 cherry-pick of C
116 * aaaa111 cherry-pick of A
117 [... snip a lot more that has happened ...]
118 | * cccc000 (topic) commit C
119 | * bbbb000 commit B
120 | * aaaa000 commit A
121 | * 0000fff (base) unpublished stuff F
122 [... snip ...]
123 | * 0000aaa unpublished stuff A
125 o 1234567 merge-base between upstream and topic
126 ------------
128 By specifying `base` as the limit, you can avoid listing commits
129 between `base` and `topic`:
131 ------------
132 $ git cherry origin/master topic base
133 - cccc000... commit C
134 + bbbb000... commit B
135 - aaaa000... commit A
136 ------------
139 SEE ALSO
140 --------
141 linkgit:git-patch-id[1]
145 Part of the linkgit:git[1] suite