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 v1.79.2 <http://docbook.sf.net/>
   5 .\"      Date: 2024-08-14
   6 .\"    Manual: Git Manual
   7 .\"    Source: Git 2.46.0.164.g477ce5ccd6
   8 .\"  Language: English
   9 .\"
  10 .TH "GIT\-CHERRY" "1" "2024-08-14" "Git 2\&.46\&.0\&.164\&.g477ce5" "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 .SH "DESCRIPTION"
  38 .sp
  39 Determine whether there are commits in \fB<head>\&.\&.<upstream>\fR that are equivalent to those in the range \fB<limit>\&.\&.<head>\fR\&.
  40 .sp
  41 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)\&.
  42 .sp
  43 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\&.
  44 .SH "OPTIONS"
  45 .PP
  46 \-v
  47 .RS 4
  48 Show the commit subjects next to the SHA1s\&.
  49 .RE
  50 .PP
  51 <upstream>
  52 .RS 4
  53 Upstream branch to search for equivalent commits\&. Defaults to the upstream branch of HEAD\&.
  54 .RE
  55 .PP
  56 <head>
  57 .RS 4
  58 Working branch; defaults to HEAD\&.
  59 .RE
  60 .PP
  61 <limit>
  62 .RS 4
  63 Do not report commits up to (and including) limit\&.
  64 .RE
  65 .SH "EXAMPLES"
  66 .SS "Patch workflows"
  67 .sp
  68 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:
  69 .sp
  70 .if n \{\
  71 .RS 4
  72 .\}
  73 .nf
  74 $ git checkout \-b topic origin/master
  75 # work and create some commits
  76 $ git format\-patch origin/master
  77 $ git send\-email \&.\&.\&. 00*
  78 .fi
  79 .if n \{\
  80 .RE
  81 .\}
  82 .sp
  83 Later, you can see whether your changes have been applied by saying (still on \fBtopic\fR):
  84 .sp
  85 .if n \{\
  86 .RS 4
  87 .\}
  88 .nf
  89 $ git fetch  # update your notion of origin/master
  90 $ git cherry \-v
  91 .fi
  92 .if n \{\
  93 .RE
  94 .\}
  95 .SS "Concrete example"
  96 .sp
  97 In a situation where topic consisted of three commits, and the maintainer applied two of them, the situation might look like:
  98 .sp
  99 .if n \{\
 100 .RS 4
 101 .\}
 102 .nf
 103 $ git log \-\-graph \-\-oneline \-\-decorate \-\-boundary origin/master\&.\&.\&.topic
 104 * 7654321 (origin/master) upstream tip commit
 105 [\&.\&.\&. snip some other commits \&.\&.\&.]
 106 * cccc111 cherry\-pick of C
 107 * aaaa111 cherry\-pick of A
 108 [\&.\&.\&. snip a lot more that has happened \&.\&.\&.]
 109 | * cccc000 (topic) commit C
 110 | * bbbb000 commit B
 111 | * aaaa000 commit A
 112 |/
 113 o 1234567 branch point
 114 .fi
 115 .if n \{\
 116 .RE
 117 .\}
 118 .sp
 119 In such cases, git\-cherry shows a concise summary of what has yet to be applied:
 120 .sp
 121 .if n \{\
 122 .RS 4
 123 .\}
 124 .nf
 125 $ git cherry origin/master topic
 126 \- cccc000\&.\&.\&. commit C
 127 + bbbb000\&.\&.\&. commit B
 128 \- aaaa000\&.\&.\&. commit A
 129 .fi
 130 .if n \{\
 131 .RE
 132 .\}
 133 .sp
 134 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\&.
 135 .SS "Using a limit"
 136 .sp
 137 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:
 138 .sp
 139 .if n \{\
 140 .RS 4
 141 .\}
 142 .nf
 143 $ git log \-\-graph \-\-oneline \-\-decorate \-\-boundary origin/master\&.\&.\&.topic
 144 * 7654321 (origin/master) upstream tip commit
 145 [\&.\&.\&. snip some other commits \&.\&.\&.]
 146 * cccc111 cherry\-pick of C
 147 * aaaa111 cherry\-pick of A
 148 [\&.\&.\&. snip a lot more that has happened \&.\&.\&.]
 149 | * cccc000 (topic) commit C
 150 | * bbbb000 commit B
 151 | * aaaa000 commit A
 152 | * 0000fff (base) unpublished stuff F
 153 [\&.\&.\&. snip \&.\&.\&.]
 154 | * 0000aaa unpublished stuff A
 155 |/
 156 o 1234567 merge\-base between upstream and topic
 157 .fi
 158 .if n \{\
 159 .RE
 160 .\}
 161 .sp
 162 By specifying \fBbase\fR as the limit, you can avoid listing commits between \fBbase\fR and \fBtopic\fR:
 163 .sp
 164 .if n \{\
 165 .RS 4
 166 .\}
 167 .nf
 168 $ git cherry origin/master topic base
 169 \- cccc000\&.\&.\&. commit C
 170 + bbbb000\&.\&.\&. commit B
 171 \- aaaa000\&.\&.\&. commit A
 172 .fi
 173 .if n \{\
 174 .RE
 175 .\}
 176 .SH "SEE ALSO"
 177 .sp
 178 \fBgit-patch-id\fR(1)
 179 .SH "GIT"
 180 .sp
 181 Part of the \fBgit\fR(1) suite