Documentation/git-cherry.txt

   1 git-cherry(1)
   2 =============
   3
   4 NAME
   5 ----
   6 git-cherry - Find commits yet to be applied to upstream
   7
   8 SYNOPSIS
   9 --------
  10 [verse]
  11 'git cherry' [-v] [<upstream> [<head> [<limit>]]]
  12
  13 DESCRIPTION
  14 -----------
  15 Determine whether there are commits in `<head>..<upstream>` that are
  16 equivalent to those in the range `<limit>..<head>`.
  17
  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::
  30         Show the commit subjects next to the SHA1s.
  31
  32 <upstream>::
  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.
  38
  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]
 142
 143 GIT
 144 ---
 145 Part of the linkgit:git[1] suite