Documentation: revamp git-cherry(1)
git-cherry(1)'s "description" section has never really managed to explain to me what the command does. It contains too much explanation of the algorithm instead of simply saying what goals it achieves, and too much terminology that we otherwise do not use (fork-point instead of merge-base). Try a much more concise approach: state what it finds out, why this is neat, and how the output is formatted, in a few short paragraphs. In return, provide much longer examples of how it fits into a "format-patch | am" based workflow, and how it compares to reading the same from git-log. Also carefully avoid using "merge" in a context where it does not mean something that comes from git-merge(1). Instead, say "apply" in an attempt to further link to patch workflow concepts. While there, also omit the language about _which_ upstream branch we treat as the default. I literally just learned that we support having several, so let's not confuse new users here, especially considering that git-config(1) does not document this. Prompted-by: a.huemer@commend.com on #git Signed-off-by: Thomas Rast <tr@thomasrast.ch> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Thomas Rast committed
Nov 22, 2013 at 17:29 UTC
7c801fbc74d4c4687ea6db60e24a67f896767824
1 file changed
+110
-33
Documentation/git-cherry.txt
+110
-33
@@ -3,7 +3,7 @@ git-cherry(1)
3
4
NAME
5
----
6
-git-cherry - Find commits not merged upstream
6
+git-cherry - Find commits yet to be applied to upstream
7
8
SYNOPSIS
9
--------
@@ -12,46 +12,26 @@ SYNOPSIS
12
13
DESCRIPTION
14
-----------
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>`.
17
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].
22
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.
26
27
OPTIONS
28
-------
29
-v::
50
- Verbose.
30
+ Show the commit subjects next to the SHA1s.
31
32
<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.
35
36
<head>::
37
Working branch; defaults to HEAD.
@@ -59,6 +39,103 @@ OPTIONS
39
<limit>::
40
Do not report commits up to (and including) limit.
41
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
+
139
SEE ALSO
140
--------
141
linkgit:git-patch-id[1]