Skip to content

Commit 5169f5a

Browse files
gitstergitster
committed
Merge branch 'tr/doc-git-cherry' into maint
* tr/doc-git-cherry: Documentation: revamp git-cherry(1)
2 parents 2126074 + 7c801fb commit 5169f5a

File tree

1 file changed

+110
-33
lines changed

1 file changed

+110
-33
lines changed

‎Documentation/git-cherry.txt

Lines changed: 110 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ git-cherry(1)
33

44
NAME
55
----
6-
git-cherry - Find commits not merged upstream
6+
git-cherry - Find commits yet to be applied to upstream
77

88
SYNOPSIS
99
--------
@@ -12,53 +12,130 @@ SYNOPSIS
1212

1313
DESCRIPTION
1414
-----------
15-
The changeset (or "diff") of each commit between the fork-point and <head>
16-
is compared against each commit between the fork-point and <upstream>.
17-
The diffs are compared after removing any whitespace and line numbers.
15+
Determine whether there are commits in `<head>..<upstream>` that are
16+
equivalent to those in the range `<limit>..<head>`.
1817

19-
Every commit that doesn't exist in the <upstream> branch
20-
has its id (sha1) reported, prefixed by a symbol. The ones that have
21-
equivalent change already
22-
in the <upstream> branch are prefixed with a minus (-) sign, and those
23-
that only exist in the <head> branch are prefixed with a plus (+) symbol:
24-
25-
__*__*__*__*__> <upstream>
26-
/
27-
fork-point
28-
\__+__+__-__+__+__-__+__> <head>
29-
30-
31-
If a <limit> has been given then the commits along the <head> branch up
32-
to and including <limit> are not reported:
33-
34-
__*__*__*__*__> <upstream>
35-
/
36-
fork-point
37-
\__*__*__<limit>__-__+__> <head>
38-
39-
40-
Because 'git cherry' compares the changeset rather than the commit id
41-
(sha1), you can use 'git cherry' to find out if a commit you made locally
42-
has been applied <upstream> under a different commit id. For example,
43-
this will happen if you're feeding patches <upstream> via email rather
44-
than pushing or pulling commits directly.
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].
4522

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.
4626

4727
OPTIONS
4828
-------
4929
-v::
50-
Verbose.
30+
Show the commit subjects next to the SHA1s.
5131

5232
<upstream>::
53-
Upstream branch to compare against.
54-
Defaults to the first tracked remote branch, if available.
33+
Upstream branch to search for equivalent commits.
34+
Defaults to the upstream branch of HEAD.
5535

5636
<head>::
5737
Working branch; defaults to HEAD.
5838

5939
<limit>::
6040
Do not report commits up to (and including) limit.
6141

42+
EXAMPLES
43+
--------
44+
45+
Patch workflows
46+
~~~~~~~~~~~~~~~
47+
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:
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+
60+
Later, 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+
68+
Concrete example
69+
~~~~~~~~~~~~~~~~
70+
71+
In a situation where topic consisted of three commits, and the
72+
maintainer 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+
|/
85+
o 1234567 branch point
86+
------------
87+
88+
In such cases, git-cherry shows a concise summary of what has yet to
89+
be applied:
90+
91+
------------
92+
$ git cherry origin/master topic
93+
- cccc000... commit C
94+
+ bbbb000... commit B
95+
- aaaa000... commit A
96+
------------
97+
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`.
102+
103+
104+
Using a limit
105+
~~~~~~~~~~~~~
106+
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:
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+
|/
125+
o 1234567 merge-base between upstream and topic
126+
------------
127+
128+
By specifying `base` as the limit, you can avoid listing commits
129+
between `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+
62139
SEE ALSO
63140
--------
64141
linkgit:git-patch-id[1]

0 commit comments

Comments
 (0)