man1/git-cherry.1

   1 '\" t
   2 .\"     Title: git-cherry
   3 .\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
   4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 01/17/2023
   6 .\"    Manual: Git Manual
   7 .\"    Source: Git 2.39.1.231.ga7caae2729
   8 .\"  Language: English
   9 .\"
  10 .TH "GIT\-CHERRY" "1" "01/17/2023" "Git 2\&.39\&.1\&.231\&.ga7caae" "Git Manual"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 git-cherry \- Find commits yet to be applied to upstream
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 \fIgit cherry\fR [\-v] [<upstream> [<head> [<limit>]]]
  36 .fi
  37 .sp
  38 .SH "DESCRIPTION"
  39 .sp
  40 Determine whether there are commits in \fB<head>\&.\&.<upstream>\fR that are equivalent to those in the range \fB<limit>\&.\&.<head>\fR\&.
  41 .sp
  42 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 \fBgit-cherry-pick\fR(1), \fBgit-am\fR(1) or \fBgit-rebase\fR(1)\&.
  43 .sp
  44 Outputs the SHA1 of every commit in \fB<limit>\&.\&.<head>\fR, prefixed with \fB\-\fR for commits that have an equivalent in <upstream>, and \fB+\fR for commits that do not\&.
  45 .SH "OPTIONS"
  46 .PP
  47 \-v
  48 .RS 4
  49 Show the commit subjects next to the SHA1s\&.
  50 .RE
  51 .PP
  52 <upstream>
  53 .RS 4
  54 Upstream branch to search for equivalent commits\&. Defaults to the upstream branch of HEAD\&.
  55 .RE
  56 .PP
  57 <head>
  58 .RS 4
  59 Working branch; defaults to HEAD\&.
  60 .RE
  61 .PP
  62 <limit>
  63 .RS 4
  64 Do not report commits up to (and including) limit\&.
  65 .RE
  66 .SH "EXAMPLES"
  67 .SS "Patch workflows"
  68 .sp
  69 git\-cherry is frequently used in patch\-based workflows (see \fBgitworkflows\fR(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:
  70 .sp
  71 .if n \{\
  72 .RS 4
  73 .\}
  74 .nf
  75 $ git checkout \-b topic origin/master
  76 # work and create some commits
  77 $ git format\-patch origin/master
  78 $ git send\-email \&.\&.\&. 00*
  79 .fi
  80 .if n \{\
  81 .RE
  82 .\}
  83 .sp
  84 .sp
  85 Later, you can see whether your changes have been applied by saying (still on \fBtopic\fR):
  86 .sp
  87 .if n \{\
  88 .RS 4
  89 .\}
  90 .nf
  91 $ git fetch  # update your notion of origin/master
  92 $ git cherry \-v
  93 .fi
  94 .if n \{\
  95 .RE
  96 .\}
  97 .sp
  98 .SS "Concrete example"
  99 .sp
 100 In a situation where topic consisted of three commits, and the maintainer applied two of them, the situation might look like:
 101 .sp
 102 .if n \{\
 103 .RS 4
 104 .\}
 105 .nf
 106 $ git log \-\-graph \-\-oneline \-\-decorate \-\-boundary origin/master\&.\&.\&.topic
 107 * 7654321 (origin/master) upstream tip commit
 108 [\&.\&.\&. snip some other commits \&.\&.\&.]
 109 * cccc111 cherry\-pick of C
 110 * aaaa111 cherry\-pick of A
 111 [\&.\&.\&. snip a lot more that has happened \&.\&.\&.]
 112 | * cccc000 (topic) commit C
 113 | * bbbb000 commit B
 114 | * aaaa000 commit A
 115 |/
 116 o 1234567 branch point
 117 .fi
 118 .if n \{\
 119 .RE
 120 .\}
 121 .sp
 122 .sp
 123 In such cases, git\-cherry shows a concise summary of what has yet to be applied:
 124 .sp
 125 .if n \{\
 126 .RS 4
 127 .\}
 128 .nf
 129 $ git cherry origin/master topic
 130 \- cccc000\&.\&.\&. commit C
 131 + bbbb000\&.\&.\&. commit B
 132 \- aaaa000\&.\&.\&. commit A
 133 .fi
 134 .if n \{\
 135 .RE
 136 .\}
 137 .sp
 138 .sp
 139 Here, we see that the commits A and C (marked with \fB\-\fR) can be dropped from your \fBtopic\fR branch when you rebase it on top of \fBorigin/master\fR, while the commit B (marked with \fB+\fR) still needs to be kept so that it will be sent to be applied to \fBorigin/master\fR\&.
 140 .SS "Using a limit"
 141 .sp
 142 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:
 143 .sp
 144 .if n \{\
 145 .RS 4
 146 .\}
 147 .nf
 148 $ git log \-\-graph \-\-oneline \-\-decorate \-\-boundary origin/master\&.\&.\&.topic
 149 * 7654321 (origin/master) upstream tip commit
 150 [\&.\&.\&. snip some other commits \&.\&.\&.]
 151 * cccc111 cherry\-pick of C
 152 * aaaa111 cherry\-pick of A
 153 [\&.\&.\&. snip a lot more that has happened \&.\&.\&.]
 154 | * cccc000 (topic) commit C
 155 | * bbbb000 commit B
 156 | * aaaa000 commit A
 157 | * 0000fff (base) unpublished stuff F
 158 [\&.\&.\&. snip \&.\&.\&.]
 159 | * 0000aaa unpublished stuff A
 160 |/
 161 o 1234567 merge\-base between upstream and topic
 162 .fi
 163 .if n \{\
 164 .RE
 165 .\}
 166 .sp
 167 .sp
 168 By specifying \fBbase\fR as the limit, you can avoid listing commits between \fBbase\fR and \fBtopic\fR:
 169 .sp
 170 .if n \{\
 171 .RS 4
 172 .\}
 173 .nf
 174 $ git cherry origin/master topic base
 175 \- cccc000\&.\&.\&. commit C
 176 + bbbb000\&.\&.\&. commit B
 177 \- aaaa000\&.\&.\&. commit A
 178 .fi
 179 .if n \{\
 180 .RE
 181 .\}
 182 .sp
 183 .SH "SEE ALSO"
 184 .sp
 185 \fBgit-patch-id\fR(1)
 186 .SH "GIT"
 187 .sp
 188 Part of the \fBgit\fR(1) suite