RubyGems - git-smart - Versions diffs - 0.1.3 → 0.1.4 - Mend

git-smart 0.1.3 → 0.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (17) hide show

data/Gemfile +1 -0
data/Gemfile.lock +6 -0
data/README.md +10 -20
data/Rakefile +7 -0
data/VERSION +1 -1
data/docs/images/git-smart.png +0 -0
data/docs/smart-merge.html +211 -0
data/docs/smart-pull.html +274 -0
data/git-smart.gemspec +13 -2
data/lib/commands/smart-merge.rb +63 -0
data/lib/commands/smart-pull.rb +38 -10
data/lib/git-smart/git_repo.rb +27 -10
data/spec/smart-merge_failures_spec.rb +46 -0
data/spec/smart-merge_spec.rb +101 -0
data/spec/smart-pull_spec.rb +2 -5
data/spec/spec_helper.rb +2 -1
metadata +52 -23

data/Gemfile CHANGED Viewed

@@ -7,4 +7,5 @@ group :development do
   gem "rcov", ">= 0"
   gem "bundler", "~> 1.0.0"
   gem "jeweler", "~> 1.5.2"
+  gem "rocco"
 end

data/Gemfile.lock CHANGED Viewed

@@ -8,8 +8,13 @@ GEM
       bundler (~> 1.0.0)
       git (>= 1.2.5)
       rake
+    mustache (0.12.0)
     rake (0.8.7)
     rcov (0.9.8)
+    rdiscount (1.6.5)
+    rocco (0.5)
+      mustache
+      rdiscount
     rspec (2.3.0)
       rspec-core (~> 2.3.0)
       rspec-expectations (~> 2.3.0)
@@ -27,4 +32,5 @@ DEPENDENCIES
   colorize
   jeweler (~> 1.5.2)
   rcov
+  rocco
   rspec (~> 2.3.0)

data/README.md CHANGED Viewed

@@ -1,11 +1,13 @@
 # git-smart
+![git-smart logo](https://github.com/geelen/git-smart/raw/master/docs/images/git-smart.png)
 Adds some additional git commands to add some smarts to your workflow. These commands follow a few guidelines:
 0. It should do the 'right thing' in all situations - an inexperienced git user should be guided away from making simple mistakes.
 0. It should make every attempt to explain to the user what decisions it has made, and why.
 0. All git commands that modify the repository should be shown to the user - hopefully this helps the user eventually learn the underlying git commands, and when they're relevant.
-0. All git commands, destructive or not, and their output should be shown to the user with the -v/--verbose flag.
+0. All git commands, destructive or not, and their output should be shown to the user with the -v/--verbose flag. (not implemented yet)
 # Installing
@@ -20,7 +22,7 @@ List the commands you can install (currently only the one):
 Install away!
     git-smart install smart-pull
 OR
     git-smart install --all
@@ -29,29 +31,17 @@ That'll put an executable file for each command in your ~/bin directory if that
 # Using
-Git allows custom commands with a simple convention - `git xyz` tries to find an executable `git-xyz` on the path. So, to run the smart-pull command, simply run:
+Git allows custom commands with a simple convention - `git xyz` tries to find an executable `git-xyz` on the path. So, to run the commands, simply type
     git smart-pull
+    git smart-merge <branchname>
-## git-smart-pull
-Calling 'git smart-pull' will fetch remote tracked changes and reapply your work on top of it. It's like a much, much smarter version of 'git pull --rebase'.
-For some background as to why this is needed, see [my blog post about the perils of rebasing merge commits](https://gist.github.com/591209)
+# Documentation
-This is how it works:
+The code for each of these commands has been annotated with comments and rendered with [Rocco](https://github.com/rtomayko/rocco):
-0. First, determine which remote branch to update from. Use branch tracking config if present, otherwise default to a remote of 'origin' and the same branch name. E.g. 'branchX', by default, tracks 'origin/branchX'.
-0. Fetch the remote.
-0. Determine what needs to be done:
-  - If the remote is a parent of HEAD, there's nothing to do.
-  - If HEAD is a parent of the remote, you simply need to reapply any working changes to the new HEAD. Stash, fast-forward, stash pop.
-  - If HEAD and the remote have diverged:
-    0. stash
-    0. rebase -p onto the remote
-    0. stash pop
-    0. update ORIG\_HEAD to be the previous local HEAD, as expected (rebase -p doesn't set ORIG\_HEAD correctly)
-0. Output a big green or red message so, at a glance, you know if things worked or not.
+- [smart-pull](http://github-displayer.heroku.com/geelen/git-smart/raw/master/docs/smart-pull.html)
+- [smart-merge](http://github-displayer.heroku.com/geelen/git-smart/raw/master/docs/smart-merge.html)
 # Contributing to git-smart

data/Rakefile CHANGED Viewed

@@ -44,3 +44,10 @@ Rake::RDocTask.new do |rdoc|
   rdoc.rdoc_files.include('README*')
   rdoc.rdoc_files.include('lib/**/*.rb')
 end
+desc "Generate the rocco docs"
+task :rocco do
+  %x[cd lib/commands && rocco *.rb -o ../../docs]
+end
+task :release => :rocco

data/VERSION CHANGED Viewed

	@@ -1 +1 @@
1	- 0.1.3
1	+ 0.1.4

data/docs/images/git-smart.png ADDED Viewed

Binary file

data/docs/smart-merge.html ADDED Viewed

@@ -0,0 +1,211 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta http-equiv="content-type" content="text/html;charset=utf-8">
+  <title>smart-merge.rb</title>
+  <link rel="stylesheet" href="http://jashkenas.github.com/docco/resources/docco.css">
+</head>
+<body>
+<div id='container'>
+  <div id="background"></div>
+  <div id="jump_to">
+    Jump To &hellip;
+    <div id="jump_wrapper">
+      <div id="jump_page">
+          <a class="source" href="smart-merge.html">smart-merge.rb</a>
+          <a class="source" href="smart-pull.html">smart-pull.rb</a>
+      </div>
+    </div>
+  </div>
+  <table cellspacing=0 cellpadding=0>
+  <thead>
+    <tr>
+      <th class=docs><h1>smart-merge.rb</h1></th>
+      <th class=code></th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr id='section-1'>
+      <td class=docs>
+        <div class="octowrap">
+          <a class="octothorpe" href="#section-1">#</a>
+        </div>
+        <p>Calling <code>git smart-merge branchname</code> will, quite simply, perform a
+non-fast-forward merge wrapped in a stash push/pop, if that&rsquo;s required.
+With some helpful extra output.</p>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre><span class="no">GitSmart</span><span class="o">.</span><span class="n">register</span> <span class="s1">&#39;smart-merge&#39;</span> <span class="k">do</span> <span class="o">|</span><span class="n">repo</span><span class="p">,</span> <span class="n">args</span><span class="o">|</span></pre></div>
+      </td>
+    </tr>
+    <tr id='section-2'>
+      <td class=docs>
+        <div class="octowrap">
+          <a class="octothorpe" href="#section-2">#</a>
+        </div>
+        <p>Let&rsquo;s begin!</p>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre>  <span class="n">current_branch</span> <span class="o">=</span> <span class="n">repo</span><span class="o">.</span><span class="n">current_branch</span>
+  <span class="n">start</span> <span class="s2">&quot;Starting: smart-merge on branch &#39;</span><span class="si">#{</span><span class="n">current_branch</span><span class="si">}</span><span class="s2">&#39;&quot;</span></pre></div>
+      </td>
+    </tr>
+    <tr id='section-3'>
+      <td class=docs>
+        <div class="octowrap">
+          <a class="octothorpe" href="#section-3">#</a>
+        </div>
+        <p>Grab the merge_target the user specified</p>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre>  <span class="n">merge_target</span> <span class="o">=</span> <span class="n">args</span><span class="o">.</span><span class="n">shift</span>
+  <span class="n">failure</span> <span class="s2">&quot;Usage: git smart-merge ref&quot;</span> <span class="k">if</span> <span class="o">!</span><span class="n">merge_target</span></pre></div>
+      </td>
+    </tr>
+    <tr id='section-4'>
+      <td class=docs>
+        <div class="octowrap">
+          <a class="octothorpe" href="#section-4">#</a>
+        </div>
+        <p>Make sure git can resolve the reference to the merge_target</p>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre>  <span class="n">merge_sha</span> <span class="o">=</span> <span class="n">repo</span><span class="o">.</span><span class="n">sha</span><span class="p">(</span><span class="n">merge_target</span><span class="p">)</span>
+  <span class="n">failure</span> <span class="s2">&quot;Branch to merge &#39;</span><span class="si">#{</span><span class="n">merge_target</span><span class="si">}</span><span class="s2">&#39; not recognised by git!&quot;</span> <span class="k">if</span> <span class="o">!</span><span class="n">merge_sha</span></pre></div>
+      </td>
+    </tr>
+    <tr id='section-5'>
+      <td class=docs>
+        <div class="octowrap">
+          <a class="octothorpe" href="#section-5">#</a>
+        </div>
+        <p>If the SHA of HEAD and the merge_target are the same, we&rsquo;re trying to merge
+the same commit with itself. Which is madness!</p>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre>  <span class="n">head</span> <span class="o">=</span> <span class="n">repo</span><span class="o">.</span><span class="n">sha</span><span class="p">(</span><span class="s1">&#39;HEAD&#39;</span><span class="p">)</span>
+  <span class="k">if</span> <span class="n">merge_sha</span> <span class="o">==</span> <span class="n">head</span>
+    <span class="n">note</span> <span class="s2">&quot;Branch &#39;</span><span class="si">#{</span><span class="n">merge_target</span><span class="si">}</span><span class="s2">&#39; has no new commits. Nothing to merge in.&quot;</span>
+    <span class="n">success</span> <span class="s1">&#39;Already up-to-date.&#39;</span>
+  <span class="k">else</span></pre></div>
+      </td>
+    </tr>
+    <tr id='section-6'>
+      <td class=docs>
+        <div class="octowrap">
+          <a class="octothorpe" href="#section-6">#</a>
+        </div>
+        <p>Determine the merge-base of the two commits, so we can report some useful output
+about how many new commits have been added.</p>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre>    <span class="n">merge_base</span> <span class="o">=</span> <span class="n">repo</span><span class="o">.</span><span class="n">merge_base</span><span class="p">(</span><span class="n">head</span><span class="p">,</span> <span class="n">merge_sha</span><span class="p">)</span></pre></div>
+      </td>
+    </tr>
+    <tr id='section-7'>
+      <td class=docs>
+        <div class="octowrap">
+          <a class="octothorpe" href="#section-7">#</a>
+        </div>
+        <p>Report the number of commits on merge_target we&rsquo;re about to merge in.</p>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre>    <span class="n">new_commits_on_merge_target</span> <span class="o">=</span> <span class="n">repo</span><span class="o">.</span><span class="n">rev_list</span><span class="p">(</span><span class="n">merge_base</span><span class="p">,</span> <span class="n">merge_target</span><span class="p">)</span>
+    <span class="nb">puts</span> <span class="s2">&quot;Branch &#39;</span><span class="si">#{</span><span class="n">merge_target</span><span class="si">}</span><span class="s2">&#39; has diverged by </span><span class="si">#{</span><span class="n">new_commits_on_merge_target</span><span class="o">.</span><span class="n">length</span><span class="si">}</span><span class="s2"> commit</span><span class="si">#{</span><span class="s1">&#39;s&#39;</span> <span class="k">if</span> <span class="n">new_commits_on_merge_target</span><span class="o">.</span><span class="n">length</span> <span class="o">!=</span> <span class="mi">1</span><span class="si">}</span><span class="s2">. Merging in.&quot;</span></pre></div>
+      </td>
+    </tr>
+    <tr id='section-8'>
+      <td class=docs>
+        <div class="octowrap">
+          <a class="octothorpe" href="#section-8">#</a>
+        </div>
+        <p>Determine if our branch has moved on.</p>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre>    <span class="k">if</span> <span class="n">head</span> <span class="o">==</span> <span class="n">merge_base</span></pre></div>
+      </td>
+    </tr>
+    <tr id='section-9'>
+      <td class=docs>
+        <div class="octowrap">
+          <a class="octothorpe" href="#section-9">#</a>
+        </div>
+        <p>Note: Even though we <em>can</em> fast-forward here, it&rsquo;s a really bad idea since
+it results in the disappearance of the branch in history. For a good discussion
+on this topic, see this <a href="http://stackoverflow.com/questions/2850369/why-uses-git-fast-forward-merging-per-default">StackOverflow question</a>.</p>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre>      <span class="n">note</span> <span class="s2">&quot;Branch &#39;</span><span class="si">#{</span><span class="n">current_branch</span><span class="si">}</span><span class="s2">&#39; has not moved on since &#39;</span><span class="si">#{</span><span class="n">merge_target</span><span class="si">}</span><span class="s2">&#39; diverged. Running with --no-ff anyway, since a fast-forward is unexpected behaviour.&quot;</span>
+    <span class="k">else</span></pre></div>
+      </td>
+    </tr>
+    <tr id='section-10'>
+      <td class=docs>
+        <div class="octowrap">
+          <a class="octothorpe" href="#section-10">#</a>
+        </div>
+        <p>Report how many commits on our branch since merge_target diverged.</p>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre>      <span class="n">new_commits_on_branch</span> <span class="o">=</span> <span class="n">repo</span><span class="o">.</span><span class="n">rev_list</span><span class="p">(</span><span class="n">merge_base</span><span class="p">,</span> <span class="n">head</span><span class="p">)</span>
+      <span class="nb">puts</span> <span class="s2">&quot;Branch &#39;</span><span class="si">#{</span><span class="n">current_branch</span><span class="si">}</span><span class="s2">&#39; has </span><span class="si">#{</span><span class="n">new_commits_on_branch</span><span class="o">.</span><span class="n">length</span><span class="si">}</span><span class="s2"> new commit</span><span class="si">#{</span><span class="s1">&#39;s&#39;</span> <span class="k">if</span> <span class="n">new_commits_on_merge_target</span><span class="o">.</span><span class="n">length</span> <span class="o">!=</span> <span class="mi">1</span><span class="si">}</span><span class="s2"> since &#39;</span><span class="si">#{</span><span class="n">merge_target</span><span class="si">}</span><span class="s2">&#39; diverged.&quot;</span>
+    <span class="k">end</span></pre></div>
+      </td>
+    </tr>
+    <tr id='section-11'>
+      <td class=docs>
+        <div class="octowrap">
+          <a class="octothorpe" href="#section-11">#</a>
+        </div>
+        <p>Before we merge, detect if there are local changes and stash them.</p>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre>    <span class="n">stash_required</span> <span class="o">=</span> <span class="n">repo</span><span class="o">.</span><span class="n">dirty?</span>
+    <span class="k">if</span> <span class="n">stash_required</span>
+      <span class="n">note</span> <span class="s2">&quot;Working directory dirty. Stashing...&quot;</span>
+      <span class="n">repo</span><span class="o">.</span><span class="n">stash!</span>
+    <span class="k">end</span></pre></div>
+      </td>
+    </tr>
+    <tr id='section-12'>
+      <td class=docs>
+        <div class="octowrap">
+          <a class="octothorpe" href="#section-12">#</a>
+        </div>
+        <p>Perform the merge, using &mdash;no-ff.</p>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre>    <span class="n">repo</span><span class="o">.</span><span class="n">merge_no_ff!</span><span class="p">(</span><span class="n">merge_target</span><span class="p">)</span></pre></div>
+      </td>
+    </tr>
+    <tr id='section-13'>
+      <td class=docs>
+        <div class="octowrap">
+          <a class="octothorpe" href="#section-13">#</a>
+        </div>
+        <p>If we stashed before, pop now.</p>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre>    <span class="k">if</span> <span class="n">stash_required</span>
+      <span class="n">note</span> <span class="s2">&quot;Reapplying local changes...&quot;</span>
+      <span class="n">repo</span><span class="o">.</span><span class="n">stash_pop!</span>
+    <span class="k">end</span></pre></div>
+      </td>
+    </tr>
+    <tr id='section-14'>
+      <td class=docs>
+        <div class="octowrap">
+          <a class="octothorpe" href="#section-14">#</a>
+        </div>
+        <p>Display a nice completion message in large, friendly letters.</p>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre>    <span class="n">success</span> <span class="s2">&quot;All good. Created merge commit </span><span class="si">#{</span><span class="n">repo</span><span class="o">.</span><span class="n">sha</span><span class="p">(</span><span class="s1">&#39;HEAD&#39;</span><span class="p">)</span><span class="o">[</span><span class="mi">0</span><span class="p">,</span><span class="mi">7</span><span class="o">]</span><span class="si">}</span><span class="s2">.&quot;</span>
+  <span class="k">end</span>
+<span class="k">end</span></pre></div>
+      </td>
+    </tr>
+  </table>
+</div>
+</body>

data/docs/smart-pull.html ADDED Viewed

@@ -0,0 +1,274 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta http-equiv="content-type" content="text/html;charset=utf-8">
+  <title>smart-pull.rb</title>
+  <link rel="stylesheet" href="http://jashkenas.github.com/docco/resources/docco.css">
+</head>
+<body>
+<div id='container'>
+  <div id="background"></div>
+  <div id="jump_to">
+    Jump To &hellip;
+    <div id="jump_wrapper">
+      <div id="jump_page">
+          <a class="source" href="smart-merge.html">smart-merge.rb</a>
+          <a class="source" href="smart-pull.html">smart-pull.rb</a>
+      </div>
+    </div>
+  </div>
+  <table cellspacing=0 cellpadding=0>
+  <thead>
+    <tr>
+      <th class=docs><h1>smart-pull.rb</h1></th>
+      <th class=code></th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr id='section-1'>
+      <td class=docs>
+        <div class="octowrap">
+          <a class="octothorpe" href="#section-1">#</a>
+        </div>
+        <p>Calling <code>git smart-pull</code> will fetch remote tracked changes
+and reapply your work on top of it. It&rsquo;s like a much, much
+smarter version of <code>git pull --rebase</code>.</p>
+<p>For some background as to why this is needed, see <a href="https://gist.github.com/591209">my blog
+post about the perils of rebasing merge commits</a></p>
+<p>This is how it works:</p>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre><span class="no">GitSmart</span><span class="o">.</span><span class="n">register</span> <span class="s1">&#39;smart-pull&#39;</span> <span class="k">do</span> <span class="o">|</span><span class="n">repo</span><span class="p">,</span> <span class="n">args</span><span class="o">|</span></pre></div>
+      </td>
+    </tr>
+    <tr id='section-2'>
+      <td class=docs>
+        <div class="octowrap">
+          <a class="octothorpe" href="#section-2">#</a>
+        </div>
+        <p>Let&rsquo;s begin!</p>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre>  <span class="n">branch</span> <span class="o">=</span> <span class="n">repo</span><span class="o">.</span><span class="n">current_branch</span>
+  <span class="n">start</span> <span class="s2">&quot;Starting: smart-pull on branch &#39;</span><span class="si">#{</span><span class="n">branch</span><span class="si">}</span><span class="s2">&#39;&quot;</span></pre></div>
+      </td>
+    </tr>
+    <tr id='section-3'>
+      <td class=docs>
+        <div class="octowrap">
+          <a class="octothorpe" href="#section-3">#</a>
+        </div>
+        <p>Let&rsquo;s not have any arguments, fellas.</p>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre>  <span class="nb">warn</span> <span class="s2">&quot;Ignoring arguments: </span><span class="si">#{</span><span class="n">args</span><span class="o">.</span><span class="n">inspect</span><span class="si">}</span><span class="s2">&quot;</span> <span class="k">if</span> <span class="o">!</span><span class="n">args</span><span class="o">.</span><span class="n">empty?</span></pre></div>
+      </td>
+    </tr>
+    <tr id='section-4'>
+      <td class=docs>
+        <div class="octowrap">
+          <a class="octothorpe" href="#section-4">#</a>
+        </div>
+        <p>Try grabbing the tracking remote from the config. If it doesn&rsquo;t exist,
+notify the user and default to &lsquo;origin&rsquo;</p>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre>  <span class="n">tracking_remote</span> <span class="o">=</span> <span class="n">repo</span><span class="o">.</span><span class="n">tracking_remote</span> <span class="o">||</span>
+    <span class="n">note</span><span class="p">(</span><span class="s2">&quot;No tracking remote configured, assuming &#39;origin&#39;&quot;</span><span class="p">)</span> <span class="o">||</span>
+    <span class="s1">&#39;origin&#39;</span></pre></div>
+      </td>
+    </tr>
+    <tr id='section-5'>
+      <td class=docs>
+        <div class="octowrap">
+          <a class="octothorpe" href="#section-5">#</a>
+        </div>
+        <p> Fetch the remote. This pulls down all new commits from the server, not just our branch,
+ but generally that&rsquo;s a good thing. This is the only communication we need to do with the server.</p>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre>  <span class="n">repo</span><span class="o">.</span><span class="n">fetch!</span><span class="p">(</span><span class="n">tracking_remote</span><span class="p">)</span></pre></div>
+      </td>
+    </tr>
+    <tr id='section-6'>
+      <td class=docs>
+        <div class="octowrap">
+          <a class="octothorpe" href="#section-6">#</a>
+        </div>
+        <p>Try grabbing the tracking branch from the config. If it doesn&rsquo;t exist,
+notify the user and choose the branch of the same name</p>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre>  <span class="n">tracking_branch</span> <span class="o">=</span> <span class="n">repo</span><span class="o">.</span><span class="n">tracking_branch</span> <span class="o">||</span>
+    <span class="n">note</span><span class="p">(</span><span class="s2">&quot;No tracking branch configured, assuming &#39;</span><span class="si">#{</span><span class="n">branch</span><span class="si">}</span><span class="s2">&#39;&quot;</span><span class="p">)</span> <span class="o">||</span>
+    <span class="n">branch</span></pre></div>
+      </td>
+    </tr>
+    <tr id='section-7'>
+      <td class=docs>
+        <div class="octowrap">
+          <a class="octothorpe" href="#section-7">#</a>
+        </div>
+        <p>Check the specified upstream branch exists. Fail if it doesn&rsquo;t.</p>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre>  <span class="n">upstream_branch</span> <span class="o">=</span> <span class="s2">&quot;</span><span class="si">#{</span><span class="n">tracking_remote</span><span class="si">}</span><span class="s2">/</span><span class="si">#{</span><span class="n">tracking_branch</span><span class="si">}</span><span class="s2">&quot;</span>
+  <span class="n">failure</span><span class="p">(</span><span class="s2">&quot;Upstream branch &#39;</span><span class="si">#{</span><span class="n">upstream_branch</span><span class="si">}</span><span class="s2">&#39; doesn&#39;t exist!&quot;</span><span class="p">)</span> <span class="k">if</span> <span class="o">!</span><span class="n">repo</span><span class="o">.</span><span class="n">exists?</span><span class="p">(</span><span class="n">upstream_branch</span><span class="p">)</span></pre></div>
+      </td>
+    </tr>
+    <tr id='section-8'>
+      <td class=docs>
+        <div class="octowrap">
+          <a class="octothorpe" href="#section-8">#</a>
+        </div>
+        <p>Grab the SHAs of the commits we&rsquo;ll be working with.</p>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre>  <span class="n">head</span> <span class="o">=</span> <span class="n">repo</span><span class="o">.</span><span class="n">sha</span><span class="p">(</span><span class="s1">&#39;HEAD&#39;</span><span class="p">)</span>
+  <span class="n">remote</span> <span class="o">=</span> <span class="n">repo</span><span class="o">.</span><span class="n">sha</span><span class="p">(</span><span class="n">upstream_branch</span><span class="p">)</span></pre></div>
+      </td>
+    </tr>
+    <tr id='section-9'>
+      <td class=docs>
+        <div class="octowrap">
+          <a class="octothorpe" href="#section-9">#</a>
+        </div>
+        <p>If both HEAD and our upstream_branch resolve to the same SHA, there&rsquo;s nothing to do!</p>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre>  <span class="k">if</span> <span class="n">head</span> <span class="o">==</span> <span class="n">remote</span>
+    <span class="nb">puts</span> <span class="s2">&quot;Neither your local branch &#39;</span><span class="si">#{</span><span class="n">branch</span><span class="si">}</span><span class="s2">&#39;, nor the remote branch &#39;</span><span class="si">#{</span><span class="n">upstream_branch</span><span class="si">}</span><span class="s2">&#39; have moved on.&quot;</span>
+    <span class="n">success</span> <span class="s2">&quot;Already up-to-date&quot;</span>
+  <span class="k">else</span></pre></div>
+      </td>
+    </tr>
+    <tr id='section-10'>
+      <td class=docs>
+        <div class="octowrap">
+          <a class="octothorpe" href="#section-10">#</a>
+        </div>
+        <p>Find out where the two branches diverged using merge-base. It&rsquo;s what git
+uses internally.</p>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre>    <span class="n">merge_base</span> <span class="o">=</span> <span class="n">repo</span><span class="o">.</span><span class="n">merge_base</span><span class="p">(</span><span class="n">head</span><span class="p">,</span> <span class="n">remote</span><span class="p">)</span></pre></div>
+      </td>
+    </tr>
+    <tr id='section-11'>
+      <td class=docs>
+        <div class="octowrap">
+          <a class="octothorpe" href="#section-11">#</a>
+        </div>
+        <p>By comparing the merge_base to both HEAD and the remote, we can
+determine whether both or only one have moved on.
+If the remote hasn&rsquo;t changed, we&rsquo;re already up to date, so there&rsquo;s nothing
+to pull.</p>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre>    <span class="k">if</span> <span class="n">merge_base</span> <span class="o">==</span> <span class="n">remote</span>
+      <span class="nb">puts</span> <span class="s2">&quot;Remote branch &#39;</span><span class="si">#{</span><span class="n">upstream_branch</span><span class="si">}</span><span class="s2">&#39; has not moved on.&quot;</span>
+      <span class="n">success</span> <span class="s2">&quot;Already up-to-date&quot;</span>
+    <span class="k">else</span></pre></div>
+      </td>
+    </tr>
+    <tr id='section-12'>
+      <td class=docs>
+        <div class="octowrap">
+          <a class="octothorpe" href="#section-12">#</a>
+        </div>
+        <p>If the remote <em>has</em> moved on, we actually have some work to do:</p>
+<p>First, report how many commits are new on remote. Because that&rsquo;s useful information.</p>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre>      <span class="n">new_commits_on_remote</span> <span class="o">=</span> <span class="n">repo</span><span class="o">.</span><span class="n">rev_list</span><span class="p">(</span><span class="n">merge_base</span><span class="p">,</span> <span class="n">remote</span><span class="p">)</span>
+      <span class="n">is_are</span><span class="p">,</span> <span class="n">s_or_not</span> <span class="o">=</span> <span class="p">(</span><span class="n">new_commits_on_remote</span><span class="o">.</span><span class="n">length</span> <span class="o">==</span> <span class="mi">1</span><span class="p">)</span> <span class="p">?</span> <span class="o">[</span><span class="s1">&#39;is&#39;</span><span class="p">,</span> <span class="s1">&#39;&#39;</span><span class="o">]</span> <span class="p">:</span> <span class="o">[</span><span class="s1">&#39;are&#39;</span><span class="p">,</span> <span class="s1">&#39;s&#39;</span><span class="o">]</span>
+      <span class="n">note</span> <span class="s2">&quot;There </span><span class="si">#{</span><span class="n">is_are</span><span class="si">}</span><span class="s2"> </span><span class="si">#{</span><span class="n">new_commits_on_remote</span><span class="o">.</span><span class="n">length</span><span class="si">}</span><span class="s2"> new commit</span><span class="si">#{</span><span class="n">s_or_not</span><span class="si">}</span><span class="s2"> on &#39;</span><span class="si">#{</span><span class="n">upstream_branch</span><span class="si">}</span><span class="s2">&#39;.&quot;</span></pre></div>
+      </td>
+    </tr>
+    <tr id='section-13'>
+      <td class=docs>
+        <div class="octowrap">
+          <a class="octothorpe" href="#section-13">#</a>
+        </div>
+        <p>Next, detect if there are local changes and stash them.</p>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre>      <span class="n">stash_required</span> <span class="o">=</span> <span class="n">repo</span><span class="o">.</span><span class="n">dirty?</span>
+      <span class="k">if</span> <span class="n">stash_required</span>
+        <span class="n">note</span> <span class="s2">&quot;Working directory dirty. Stashing...&quot;</span>
+        <span class="n">repo</span><span class="o">.</span><span class="n">stash!</span>
+      <span class="k">end</span>
+      <span class="n">success_messages</span> <span class="o">=</span> <span class="o">[]</span></pre></div>
+      </td>
+    </tr>
+    <tr id='section-14'>
+      <td class=docs>
+        <div class="octowrap">
+          <a class="octothorpe" href="#section-14">#</a>
+        </div>
+        <p>Then, bring the local branch up to date.</p>
+<p>If our local branch hasn&rsquo;t moved on, that&rsquo;s easy &ndash; we just need to fast-forward.</p>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre>      <span class="k">if</span> <span class="n">merge_base</span> <span class="o">==</span> <span class="n">head</span>
+        <span class="nb">puts</span> <span class="s2">&quot;Local branch &#39;</span><span class="si">#{</span><span class="n">branch</span><span class="si">}</span><span class="s2">&#39; has not moved on. Fast-forwarding...&quot;</span>
+        <span class="n">repo</span><span class="o">.</span><span class="n">fast_forward!</span><span class="p">(</span><span class="n">upstream_branch</span><span class="p">)</span>
+        <span class="n">success_messages</span> <span class="o">&lt;&lt;</span> <span class="s2">&quot;Fast forwarded from </span><span class="si">#{</span><span class="n">head</span><span class="o">[</span><span class="mi">0</span><span class="p">,</span><span class="mi">7</span><span class="o">]</span><span class="si">}</span><span class="s2"> to </span><span class="si">#{</span><span class="n">remote</span><span class="o">[</span><span class="mi">0</span><span class="p">,</span><span class="mi">7</span><span class="o">]</span><span class="si">}</span><span class="s2">&quot;</span>
+      <span class="k">else</span></pre></div>
+      </td>
+    </tr>
+    <tr id='section-15'>
+      <td class=docs>
+        <div class="octowrap">
+          <a class="octothorpe" href="#section-15">#</a>
+        </div>
+        <p>If our local branch has new commits, we need to rebase them on top of master.</p>
+<p>When we rebase, we use <code>git rebase -p</code>, which attempts to recreate merges
+instead of ignoring them. For a description as to why, see my <a href="(https://gist.github.com/591209">blog post</a>.</p>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre>        <span class="n">note</span> <span class="s2">&quot;Both local and remote branches have moved on. Branch &#39;master&#39; needs to be rebased onto &#39;origin/master&#39;&quot;</span>
+        <span class="n">repo</span><span class="o">.</span><span class="n">rebase_preserving_merges!</span><span class="p">(</span><span class="n">upstream_branch</span><span class="p">)</span>
+        <span class="n">success_messages</span> <span class="o">&lt;&lt;</span> <span class="s2">&quot;HEAD moved from </span><span class="si">#{</span><span class="n">head</span><span class="o">[</span><span class="mi">0</span><span class="p">,</span><span class="mi">7</span><span class="o">]</span><span class="si">}</span><span class="s2"> to </span><span class="si">#{</span><span class="n">repo</span><span class="o">.</span><span class="n">sha</span><span class="p">(</span><span class="s1">&#39;HEAD&#39;</span><span class="p">)</span><span class="o">[</span><span class="mi">0</span><span class="p">,</span><span class="mi">7</span><span class="o">]</span><span class="si">}</span><span class="s2">.&quot;</span>
+      <span class="k">end</span></pre></div>
+      </td>
+    </tr>
+    <tr id='section-16'>
+      <td class=docs>
+        <div class="octowrap">
+          <a class="octothorpe" href="#section-16">#</a>
+        </div>
+        <p>If we stashed before, pop now.</p>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre>      <span class="k">if</span> <span class="n">stash_required</span>
+        <span class="n">note</span> <span class="s2">&quot;Reapplying local changes...&quot;</span>
+        <span class="n">repo</span><span class="o">.</span><span class="n">stash_pop!</span>
+      <span class="k">end</span></pre></div>
+      </td>
+    </tr>
+    <tr id='section-17'>
+      <td class=docs>
+        <div class="octowrap">
+          <a class="octothorpe" href="#section-17">#</a>
+        </div>
+        <p>Display a nice completion message in large, friendly letters.</p>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre>      <span class="n">success</span> <span class="o">[</span><span class="s2">&quot;All good.&quot;</span><span class="p">,</span> <span class="o">*</span><span class="n">success_messages</span><span class="o">].</span><span class="n">join</span><span class="p">(</span><span class="s2">&quot; &quot;</span><span class="p">)</span>
+    <span class="k">end</span>
+  <span class="k">end</span>
+<span class="k">end</span></pre></div>
+      </td>
+    </tr>
+  </table>
+</div>
+</body>