<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sect2 SYSTEM "../../../dtd/dblite.dtd">

<sect2 lang="en" id="git-cherry(1)">
    <title>git-cherry(1)</title>
    <date>2024-07-02</date>
<revhistory><revision><date>2024-07-02</date></revision></revhistory>
<indexterm>
<primary>git-cherry(1)</primary>
</indexterm>
<simplesect id="git-cherry(1)__name">
<title>NAME</title>
<simpara>git-cherry - Find commits yet to be applied to upstream</simpara>
</simplesect>
<simplesect id="git-cherry(1)__synopsis">
<title>SYNOPSIS</title>
<blockquote>
<literallayout><emphasis>git cherry</emphasis> [-v] [&lt;upstream&gt; [&lt;head&gt; [&lt;limit&gt;]]]</literallayout>
</blockquote>
</simplesect>
<simplesect id="git-cherry(1)__description">
<title>DESCRIPTION</title>
<simpara>Determine whether there are commits in <emphasis>&lt;head&gt;..&lt;upstream&gt;</emphasis> that are
equivalent to those in the range <emphasis>&lt;limit&gt;..&lt;head&gt;</emphasis>.</simpara>
<simpara>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 <xref linkend="git-cherry-pick(1)" />, <xref linkend="git-am(1)" /> or
<xref linkend="git-rebase(1)" />.</simpara>
<simpara>Outputs the SHA1 of every commit in <emphasis>&lt;limit&gt;..&lt;head&gt;</emphasis>, prefixed with
<emphasis>-</emphasis> for commits that have an equivalent in &lt;upstream&gt;, and <emphasis>+</emphasis> for
commits that do not.</simpara>
</simplesect>
<simplesect id="git-cherry(1)__options">
<title>OPTIONS</title>
<variablelist>
<varlistentry>
<term>
-v
</term>
<listitem>
<simpara>
        Show the commit subjects next to the SHA1s.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
&lt;upstream&gt;
</term>
<listitem>
<simpara>
        Upstream branch to search for equivalent commits.
        Defaults to the upstream branch of HEAD.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
&lt;head&gt;
</term>
<listitem>
<simpara>
        Working branch; defaults to HEAD.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
&lt;limit&gt;
</term>
<listitem>
<simpara>
        Do not report commits up to (and including) limit.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</simplesect>
<simplesect id="git-cherry(1)__examples">
<title>EXAMPLES</title>
<section id="git-cherry(1)__patch_workflows">
<title>Patch workflows</title>
<simpara>git-cherry is frequently used in patch-based workflows (see
<xref linkend="gitworkflows(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:</simpara>
<screen>$ git checkout -b topic origin/master
# work and create some commits
$ git format-patch origin/master
$ git send-email ... 00*</screen>
<simpara>Later, you can see whether your changes have been applied by saying
(still on <emphasis>topic</emphasis>):</simpara>
<screen>$ git fetch  # update your notion of origin/master
$ git cherry -v</screen>
</section>
<section id="git-cherry(1)__concrete_example">
<title>Concrete example</title>
<simpara>In a situation where topic consisted of three commits, and the
maintainer applied two of them, the situation might look like:</simpara>
<screen>$ git log --graph --oneline --decorate --boundary origin/master...topic
* 7654321 (origin/master) upstream tip commit
[... snip some other commits ...]
* cccc111 cherry-pick of C
* aaaa111 cherry-pick of A
[... snip a lot more that has happened ...]
| * cccc000 (topic) commit C
| * bbbb000 commit B
| * aaaa000 commit A
|/
o 1234567 branch point</screen>
<simpara>In such cases, git-cherry shows a concise summary of what has yet to
be applied:</simpara>
<screen>$ git cherry origin/master topic
- cccc000... commit C
+ bbbb000... commit B
- aaaa000... commit A</screen>
<simpara>Here, we see that the commits A and C (marked with <emphasis>-</emphasis>) can be
dropped from your <emphasis>topic</emphasis> branch when you rebase it on top of
<emphasis>origin/master</emphasis>, while the commit B (marked with <emphasis>+</emphasis>) still needs to
be kept so that it will be sent to be applied to <emphasis>origin/master</emphasis>.</simpara>
</section>
<section id="git-cherry(1)__using_a_limit">
<title>Using a limit</title>
<simpara>The optional &lt;limit&gt; 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:</simpara>
<screen>$ git log --graph --oneline --decorate --boundary origin/master...topic
* 7654321 (origin/master) upstream tip commit
[... snip some other commits ...]
* cccc111 cherry-pick of C
* aaaa111 cherry-pick of A
[... snip a lot more that has happened ...]
| * cccc000 (topic) commit C
| * bbbb000 commit B
| * aaaa000 commit A
| * 0000fff (base) unpublished stuff F
[... snip ...]
| * 0000aaa unpublished stuff A
|/
o 1234567 merge-base between upstream and topic</screen>
<simpara>By specifying <emphasis>base</emphasis> as the limit, you can avoid listing commits
between <emphasis>base</emphasis> and <emphasis>topic</emphasis>:</simpara>
<screen>$ git cherry origin/master topic base
- cccc000... commit C
+ bbbb000... commit B
- aaaa000... commit A</screen>
</section>
</simplesect>
<simplesect id="git-cherry(1)__see_also">
<title>SEE ALSO</title>
<simpara><xref linkend="git-patch-id(1)" /></simpara>
</simplesect>
<simplesect id="git-cherry(1)__git">
<title>GIT</title>
<simpara>Part of the <xref linkend="git(1)" /> suite</simpara>
</simplesect>
</sect2>
