blob: 0ea921a5931647f21f74a44a80622c3d3c16827c [file] [log] [blame]
Junio C Hamano7fc9d692005-08-23 01:49:47 -07001git-cherry(1)
2=============
3
4NAME
5----
Thomas Rast7c801fb2013-11-22 17:29:16 +01006git-cherry - Find commits yet to be applied to upstream
Junio C Hamano7fc9d692005-08-23 01:49:47 -07007
8SYNOPSIS
9--------
Martin von Zweigbergk7791a1d2011-07-01 22:38:26 -040010[verse]
Markus Heidelberg3bc52d72009-01-01 22:56:29 +010011'git cherry' [-v] [<upstream> [<head> [<limit>]]]
Junio C Hamano7fc9d692005-08-23 01:49:47 -070012
13DESCRIPTION
14-----------
Thomas Rast7c801fb2013-11-22 17:29:16 +010015Determine whether there are commits in `<head>..<upstream>` that are
16equivalent to those in the range `<limit>..<head>`.
sean81ae43c2006-05-05 15:06:07 -040017
Thomas Rast7c801fb2013-11-22 17:29:16 +010018The equivalence test is based on the diff, after removing whitespace
19and 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
21linkgit:git-rebase[1].
Rene Scharfea8ebdb92006-10-26 23:32:41 +020022
Thomas Rast7c801fb2013-11-22 17:29:16 +010023Outputs the SHA1 of every commit in `<limit>..<head>`, prefixed with
24`-` for commits that have an equivalent in <upstream>, and `+` for
25commits that do not.
Junio C Hamano7fc9d692005-08-23 01:49:47 -070026
27OPTIONS
28-------
A Large Angry SCM52a22d12005-08-26 18:18:48 -070029-v::
Thomas Rast7c801fb2013-11-22 17:29:16 +010030 Show the commit subjects next to the SHA1s.
Junio C Hamano7fc9d692005-08-23 01:49:47 -070031
A Large Angry SCM52a22d12005-08-26 18:18:48 -070032<upstream>::
Thomas Rast7c801fb2013-11-22 17:29:16 +010033 Upstream branch to search for equivalent commits.
34 Defaults to the upstream branch of HEAD.
Junio C Hamano7fc9d692005-08-23 01:49:47 -070035
A Large Angry SCM52a22d12005-08-26 18:18:48 -070036<head>::
37 Working branch; defaults to HEAD.
Junio C Hamano7fc9d692005-08-23 01:49:47 -070038
Luiz Fernando N. Capitulino6894f492007-06-11 09:56:56 -030039<limit>::
40 Do not report commits up to (and including) limit.
41
Thomas Rast7c801fb2013-11-22 17:29:16 +010042EXAMPLES
43--------
44
45Patch workflows
46~~~~~~~~~~~~~~~
47
48git-cherry is frequently used in patch-based workflows (see
49linkgit:gitworkflows[7]) to determine if a series of patches has been
50applied by the upstream maintainer. In such a workflow you might
51create and send a topic branch like this:
52
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------------
59
60Later, you can see whether your changes have been applied by saying
61(still on `topic`):
62
63------------
64$ git fetch # update your notion of origin/master
65$ git cherry -v
66------------
67
68Concrete example
69~~~~~~~~~~~~~~~~
70
71In a situation where topic consisted of three commits, and the
72maintainer applied two of them, the situation might look like:
73
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
84|/
85o 1234567 branch point
86------------
87
88In such cases, git-cherry shows a concise summary of what has yet to
89be applied:
90
91------------
92$ git cherry origin/master topic
93- cccc000... commit C
94+ bbbb000... commit B
95- aaaa000... commit A
96------------
97
98Here, we see that the commits A and C (marked with `-`) can be
99dropped from your `topic` branch when you rebase it on top of
100`origin/master`, while the commit B (marked with `+`) still needs to
101be kept so that it will be sent to be applied to `origin/master`.
102
103
104Using a limit
105~~~~~~~~~~~~~
106
107The optional <limit> is useful in cases where your topic is based on
108other work that is not in upstream. Expanding on the previous
109example, this might look like:
110
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
124|/
125o 1234567 merge-base between upstream and topic
126------------
127
128By specifying `base` as the limit, you can avoid listing commits
129between `base` and `topic`:
130
131------------
132$ git cherry origin/master topic base
133- cccc000... commit C
134+ bbbb000... commit B
135- aaaa000... commit A
136------------
137
138
Junio C Hamanoa7052d32008-05-28 17:03:46 -0700139SEE ALSO
140--------
141linkgit:git-patch-id[1]
142
Junio C Hamano7fc9d692005-08-23 01:49:47 -0700143GIT
144---
Christian Couder9e1f0a82008-06-06 09:07:32 +0200145Part of the linkgit:git[1] suite