Autogenerated HTML docs for v1.8.5.1-163-gd7ace

1 files changed, 104 insertions, 34 deletions

diff --git a/git-cherry.html b/git-cherry.html
index e1d2cc49b..049d8ea8c 100644
--- a/git-cherry.html
+++ b/git-cherry.html
@@ -737,7 +737,7 @@ git-cherry(1) Manual Page
 <h2>NAME</h2>

 <div class="sectionbody">

 <p>git-cherry -

-   Find commits not merged upstream

+   Find commits yet to be applied to upstream

 </p>

 </div>

 </div>

@@ -754,35 +754,15 @@ git-cherry(1) Manual Page
 <div class="sect1">

 <h2 id="_description">DESCRIPTION</h2>

 <div class="sectionbody">

-<div class="paragraph"><p>The changeset (or "diff") of each commit between the fork-point and &lt;head&gt;

-is compared against each commit between the fork-point and &lt;upstream&gt;.

-The diffs are compared after removing any whitespace and line numbers.</p></div>

-<div class="paragraph"><p>Every commit that doesn&#8217;t exist in the &lt;upstream&gt; branch

-has its id (sha1) reported, prefixed by a symbol.  The ones that have

-equivalent change already

-in the &lt;upstream&gt; branch are prefixed with a minus (-) sign, and those

-that only exist in the &lt;head&gt; branch are prefixed with a plus (+) symbol:</p></div>

-<div class="literalblock">

-<div class="content">

-<pre><code>           __*__*__*__*__&gt; &lt;upstream&gt;

-          /

-fork-point

-          \__+__+__-__+__+__-__+__&gt; &lt;head&gt;</code></pre>

-</div></div>

-<div class="paragraph"><p>If a &lt;limit&gt; has been given then the commits along the &lt;head&gt; branch up

-to and including &lt;limit&gt; are not reported:</p></div>

-<div class="literalblock">

-<div class="content">

-<pre><code>           __*__*__*__*__&gt; &lt;upstream&gt;

-          /

-fork-point

-          \__*__*__&lt;limit&gt;__-__+__&gt; &lt;head&gt;</code></pre>

-</div></div>

-<div class="paragraph"><p>Because <em>git cherry</em> compares the changeset rather than the commit id

-(sha1), you can use <em>git cherry</em> to find out if a commit you made locally

-has been applied &lt;upstream&gt; under a different commit id.  For example,

-this will happen if you&#8217;re feeding patches &lt;upstream&gt; via email rather

-than pushing or pulling commits directly.</p></div>

+<div class="paragraph"><p>Determine whether there are commits in <code>&lt;head&gt;..&lt;upstream&gt;</code> that are

+equivalent to those in the range <code>&lt;limit&gt;..&lt;head&gt;</code>.</p></div>

+<div class="paragraph"><p>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 <a href="git-cherry-pick.html">git-cherry-pick(1)</a>, <a href="git-am.html">git-am(1)</a> or

+<a href="git-rebase.html">git-rebase(1)</a>.</p></div>

+<div class="paragraph"><p>Outputs the SHA1 of every commit in <code>&lt;limit&gt;..&lt;head&gt;</code>, prefixed with

+<code>-</code> for commits that have an equivalent in &lt;upstream&gt;, and <code>+</code> for

+commits that do not.</p></div>

 </div>

 </div>

 <div class="sect1">

@@ -794,7 +774,7 @@ than pushing or pulling commits directly.</p></div>
 </dt>

 <dd>

 <p>

-        Verbose.

+        Show the commit subjects next to the SHA1s.

 </p>

 </dd>

 <dt class="hdlist1">

@@ -802,8 +782,8 @@ than pushing or pulling commits directly.</p></div>
 </dt>

 <dd>

 <p>

-        Upstream branch to compare against.

-        Defaults to the first tracked remote branch, if available.

+        Upstream branch to search for equivalent commits.

+        Defaults to the upstream branch of HEAD.

 </p>

 </dd>

 <dt class="hdlist1">

@@ -826,6 +806,96 @@ than pushing or pulling commits directly.</p></div>
 </div>

 </div>

 <div class="sect1">

+<h2 id="_examples">EXAMPLES</h2>

+<div class="sectionbody">

+<div class="sect2">

+<h3 id="_patch_workflows">Patch workflows</h3>

+<div class="paragraph"><p>git-cherry is frequently used in patch-based workflows (see

+<a href="gitworkflows.html">gitworkflows(7)</a>) 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:</p></div>

+<div class="listingblock">

+<div class="content">

+<pre><code>$ git checkout -b topic origin/master

+# work and create some commits

+$ git format-patch origin/master

+$ git send-email ... 00*</code></pre>

+</div></div>

+<div class="paragraph"><p>Later, you can see whether your changes have been applied by saying

+(still on <code>topic</code>):</p></div>

+<div class="listingblock">

+<div class="content">

+<pre><code>$ git fetch  # update your notion of origin/master

+$ git cherry -v</code></pre>

+</div></div>

+</div>

+<div class="sect2">

+<h3 id="_concrete_example">Concrete example</h3>

+<div class="paragraph"><p>In a situation where topic consisted of three commits, and the

+maintainer applied two of them, the situation might look like:</p></div>

+<div class="listingblock">

+<div class="content">

+<pre><code>$ 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</code></pre>

+</div></div>

+<div class="paragraph"><p>In such cases, git-cherry shows a concise summary of what has yet to

+be applied:</p></div>

+<div class="listingblock">

+<div class="content">

+<pre><code>$ git cherry origin/master topic

+- cccc000... commit C

++ bbbb000... commit B

+- aaaa000... commit A</code></pre>

+</div></div>

+<div class="paragraph"><p>Here, we see that the commits A and C (marked with <code>-</code>) can be

+dropped from your <code>topic</code> branch when you rebase it on top of

+<code>origin/master</code>, while the commit B (marked with <code>+</code>) still needs to

+be kept so that it will be sent to be applied to <code>origin/master</code>.</p></div>

+</div>

+<div class="sect2">

+<h3 id="_using_a_limit">Using a limit</h3>

+<div class="paragraph"><p>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:</p></div>

+<div class="listingblock">

+<div class="content">

+<pre><code>$ 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</code></pre>

+</div></div>

+<div class="paragraph"><p>By specifying <code>base</code> as the limit, you can avoid listing commits

+between <code>base</code> and <code>topic</code>:</p></div>

+<div class="listingblock">

+<div class="content">

+<pre><code>$ git cherry origin/master topic base

+- cccc000... commit C

++ bbbb000... commit B

+- aaaa000... commit A</code></pre>

+</div></div>

+</div>

+</div>

+</div>

+<div class="sect1">

 <h2 id="_see_also">SEE ALSO</h2>

 <div class="sectionbody">

 <div class="paragraph"><p><a href="git-patch-id.html">git-patch-id(1)</a></p></div>

@@ -841,7 +911,7 @@ than pushing or pulling commits directly.</p></div>
 <div id="footnotes"><hr /></div>

 <div id="footer">

 <div id="footer-text">

-Last updated 2013-10-15 11:39:58 PDT

+Last updated 2013-12-12 16:55:14 PST

 </div>

 </div>

 </body>