doc/source/en/TortoiseGit/git_doc/git-cherry.xml

   1 <?xml version="1.0" encoding="UTF-8"?>\r
   2 <!DOCTYPE sect2 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">\r
   3 \r
   4 <sect2 lang="en" id="git-cherry(1)">\r
   5     <title>git-cherry(1)</title>\r
   6 <indexterm>\r
   7 <primary>git-cherry(1)</primary>\r
   8 </indexterm>\r
   9 <simplesect id="git-cherry(1)__name">\r
  10 <title>NAME</title>\r
  11 <simpara>git-cherry - Find commits yet to be applied to upstream</simpara>\r
  12 </simplesect>\r
  13 <simplesect id="git-cherry(1)__synopsis">\r
  14 <title>SYNOPSIS</title>\r
  15 <blockquote>\r
  16 <literallayout><emphasis>git cherry</emphasis> [-v] [&lt;upstream&gt; [&lt;head&gt; [&lt;limit&gt;]]]</literallayout>\r
  17 </blockquote>\r
  18 </simplesect>\r
  19 <simplesect id="git-cherry(1)__description">\r
  20 <title>DESCRIPTION</title>\r
  21 <simpara>Determine whether there are commits in <emphasis>&lt;head&gt;..&lt;upstream&gt;</emphasis> that are\r
  22 equivalent to those in the range <emphasis>&lt;limit&gt;..&lt;head&gt;</emphasis>.</simpara>\r
  23 <simpara>The equivalence test is based on the diff, after removing whitespace\r
  24 and line numbers.  git-cherry therefore detects when commits have been\r
  25 "copied" by means of <xref linkend="git-cherry-pick(1)" />, <xref linkend="git-am(1)" /> or\r
  26 <xref linkend="git-rebase(1)" />.</simpara>\r
  27 <simpara>Outputs the SHA1 of every commit in <emphasis>&lt;limit&gt;..&lt;head&gt;</emphasis>, prefixed with\r
  28 <emphasis>-</emphasis> for commits that have an equivalent in &lt;upstream&gt;, and <emphasis>+</emphasis> for\r
  29 commits that do not.</simpara>\r
  30 </simplesect>\r
  31 <simplesect id="git-cherry(1)__options">\r
  32 <title>OPTIONS</title>\r
  33 <variablelist>\r
  34 <varlistentry>\r
  35 <term>\r
  36 -v\r
  37 </term>\r
  38 <listitem>\r
  39 <simpara>\r
  40         Show the commit subjects next to the SHA1s.\r
  41 </simpara>\r
  42 </listitem>\r
  43 </varlistentry>\r
  44 <varlistentry>\r
  45 <term>\r
  46 &lt;upstream&gt;\r
  47 </term>\r
  48 <listitem>\r
  49 <simpara>\r
  50         Upstream branch to search for equivalent commits.\r
  51         Defaults to the upstream branch of HEAD.\r
  52 </simpara>\r
  53 </listitem>\r
  54 </varlistentry>\r
  55 <varlistentry>\r
  56 <term>\r
  57 &lt;head&gt;\r
  58 </term>\r
  59 <listitem>\r
  60 <simpara>\r
  61         Working branch; defaults to HEAD.\r
  62 </simpara>\r
  63 </listitem>\r
  64 </varlistentry>\r
  65 <varlistentry>\r
  66 <term>\r
  67 &lt;limit&gt;\r
  68 </term>\r
  69 <listitem>\r
  70 <simpara>\r
  71         Do not report commits up to (and including) limit.\r
  72 </simpara>\r
  73 </listitem>\r
  74 </varlistentry>\r
  75 </variablelist>\r
  76 </simplesect>\r
  77 <simplesect id="git-cherry(1)__examples">\r
  78 <title>EXAMPLES</title>\r
  79 <section id="git-cherry(1)__patch_workflows">\r
  80 <title>Patch workflows</title>\r
  81 <simpara>git-cherry is frequently used in patch-based workflows (see\r
  82 <xref linkend="gitworkflows(7)" />) to determine if a series of patches has been\r
  83 applied by the upstream maintainer.  In such a workflow you might\r
  84 create and send a topic branch like this:</simpara>\r
  85 <screen>$ git checkout -b topic origin/master\r
  86 # work and create some commits\r
  87 $ git format-patch origin/master\r
  88 $ git send-email ... 00*</screen>\r
  89 <simpara>Later, you can see whether your changes have been applied by saying\r
  90 (still on <emphasis>topic</emphasis>):</simpara>\r
  91 <screen>$ git fetch  # update your notion of origin/master\r
  92 $ git cherry -v</screen>\r
  93 </section>\r
  94 <section id="git-cherry(1)__concrete_example">\r
  95 <title>Concrete example</title>\r
  96 <simpara>In a situation where topic consisted of three commits, and the\r
  97 maintainer applied two of them, the situation might look like:</simpara>\r
  98 <screen>$ git log --graph --oneline --decorate --boundary origin/master...topic\r
  99 * 7654321 (origin/master) upstream tip commit\r
 100 [... snip some other commits ...]\r
 101 * cccc111 cherry-pick of C\r
 102 * aaaa111 cherry-pick of A\r
 103 [... snip a lot more that has happened ...]\r
 104 | * cccc000 (topic) commit C\r
 105 | * bbbb000 commit B\r
 106 | * aaaa000 commit A\r
 107 |/\r
 108 o 1234567 branch point</screen>\r
 109 <simpara>In such cases, git-cherry shows a concise summary of what has yet to\r
 110 be applied:</simpara>\r
 111 <screen>$ git cherry origin/master topic\r
 112 - cccc000... commit C\r
 113 + bbbb000... commit B\r
 114 - aaaa000... commit A</screen>\r
 115 <simpara>Here, we see that the commits A and C (marked with <emphasis>-</emphasis>) can be\r
 116 dropped from your <emphasis>topic</emphasis> branch when you rebase it on top of\r
 117 <emphasis>origin/master</emphasis>, while the commit B (marked with <emphasis>+</emphasis>) still needs to\r
 118 be kept so that it will be sent to be applied to <emphasis>origin/master</emphasis>.</simpara>\r
 119 </section>\r
 120 <section id="git-cherry(1)__using_a_limit">\r
 121 <title>Using a limit</title>\r
 122 <simpara>The optional &lt;limit&gt; is useful in cases where your topic is based on\r
 123 other work that is not in upstream.  Expanding on the previous\r
 124 example, this might look like:</simpara>\r
 125 <screen>$ git log --graph --oneline --decorate --boundary origin/master...topic\r
 126 * 7654321 (origin/master) upstream tip commit\r
 127 [... snip some other commits ...]\r
 128 * cccc111 cherry-pick of C\r
 129 * aaaa111 cherry-pick of A\r
 130 [... snip a lot more that has happened ...]\r
 131 | * cccc000 (topic) commit C\r
 132 | * bbbb000 commit B\r
 133 | * aaaa000 commit A\r
 134 | * 0000fff (base) unpublished stuff F\r
 135 [... snip ...]\r
 136 | * 0000aaa unpublished stuff A\r
 137 |/\r
 138 o 1234567 merge-base between upstream and topic</screen>\r
 139 <simpara>By specifying <emphasis>base</emphasis> as the limit, you can avoid listing commits\r
 140 between <emphasis>base</emphasis> and <emphasis>topic</emphasis>:</simpara>\r
 141 <screen>$ git cherry origin/master topic base\r
 142 - cccc000... commit C\r
 143 + bbbb000... commit B\r
 144 - aaaa000... commit A</screen>\r
 145 </section>\r
 146 </simplesect>\r
 147 <simplesect id="git-cherry(1)__see_also">\r
 148 <title>SEE ALSO</title>\r
 149 <simpara><xref linkend="git-patch-id(1)" /></simpara>\r
 150 </simplesect>\r
 151 <simplesect id="git-cherry(1)__git">\r
 152 <title>GIT</title>\r
 153 <simpara>Part of the <xref linkend="git(1)" /> suite</simpara>\r
 154 </simplesect>\r
 155 </sect2>\r