hub 1.6.1 → 1.7.0

data/README.md

@@ -114,7 +114,7 @@ The alias command can also be eval'd directly using the `-s` flag:
 Commands
 --------
 
-Assuming you've aliased `hub` to `git` the following commands now have
+Assuming you've aliased `hub` to `git`, the following commands now have
 superpowers:
 
 ### git clone
@@ -126,10 +126,7 @@ superpowers:
     > git clone git@github.com:schacon/ticgit.git
 
     $ git clone resque
-    > git clone git://github.com/YOUR_USER/resque.git
-
-    $ git clone -p resque
-    > git clone git@github.com:YOUR_USER/resque.git
+    > git clone git@github.com/YOUR_USER/resque.git
 
 ### git remote add
 
@@ -167,24 +164,63 @@ superpowers:
     > git fetch mislav
     > git cherry-pick SHA
 
+### git am, git apply
+
+    $ git am https://github.com/defunkt/hub/pull/55
+    > curl https://github.com/defunkt/hub/pull/55.patch -o /tmp/55.patch
+    > git am /tmp/55.patch
+
+    $ git am --ignore-whitespace https://github.com/davidbalbert/hub/commit/fdb9921
+    > curl https://github.com/davidbalbert/hub/commit/fdb9921.patch -o /tmp/fdb9921.patch
+    > git am --ignore-whitespace /tmp/fdb9921.patch
+
+    $ git apply https://gist.github.com/8da7fb575debd88c54cf
+    > curl https://gist.github.com/8da7fb575debd88c54cf.txt -o /tmp/gist-8da7fb575debd88c54cf.txt
+    > git apply /tmp/gist-8da7fb575debd88c54cf.txt
+
 ### git fork
 
     $ git fork
-    ... hardcore forking action ...
+    [ repo forked on GitHub ]
     > git remote add -f YOUR_USER git@github.com:YOUR_USER/CURRENT_REPO.git
 
-Forks the original repo on GitHub and adds the new remote under your
-username. It requires your GitHub token to be present; see "GitHub
-login" below for details.
+### git pull-request
+
+    # while on a topic branch called "feature":
+    $ git pull-request
+    [ opens text editor to edit title & body for the request ]
+    [ opened pull request on GitHub for "YOUR_USER:feature" ]
+
+    # explicit title, pull base & head:
+    $ git pull-request "I've implemented feature X" -b defunkt:master -h mislav:feature
+
+    $ git pull-request -i 123
+    [ attached pull request to issue #123 ]
+
+### git checkout
+
+    # $ git checkout https://github.com/defunkt/hub/pull/73
+    # > git remote add -f -t feature git://github:com/mislav/hub.git
+    # > git checkout -b mislav-feature mislav/feature
+
+    # $ git checkout https://github.com/defunkt/hub/pull/73 custom-branch-name
 
 ### git create
 
     $ git create
-    ... hardcore creating action ...
+    [ repo created on GitHub ]
     > git remote add origin git@github.com:YOUR_USER/CURRENT_REPO.git
 
-Creates a new public github repository and adds the remote `origin` at
-"git@github.com:<USER>/<REPOSITORY>.git"
+    # with description:
+    $ git create -d 'It shall be mine, all mine!'
+
+    $ git create recipes
+    [ repo created on GitHub ]
+    > git remote add origin git@github.com:YOUR_USER/recipes.git
+
+    $ git create sinatra/recipes
+    [ repo created in GitHub organization ]
+    > git remote add origin git@github.com:sinatra/recipes.git
 
 ### git init
 
@@ -204,12 +240,18 @@ Creates a new public github repository and adds the remote `origin` at
     $ git browse
     > open https://github.com/YOUR_USER/CURRENT_REPO
 
+    $ git browse -- commit/SHA
+    > open https://github.com/YOUR_USER/CURRENT_REPO/commit/SHA
+
     $ git browse -- issues
     > open https://github.com/YOUR_USER/CURRENT_REPO/issues
 
     $ git browse schacon/ticgit
     > open https://github.com/schacon/ticgit
 
+    $ git browse schacon/ticgit commit/SHA
+    > open https://github.com/schacon/ticgit/commit/SHA
+
     $ git browse resque
     > open https://github.com/YOUR_USER/resque
 
@@ -221,7 +263,7 @@ Creates a new public github repository and adds the remote `origin` at
     $ git compare refactor
     > open https://github.com/CURRENT_REPO/compare/refactor
 
-    $ git compare 1.0...1.1
+    $ git compare 1.0..1.1
     > open https://github.com/CURRENT_REPO/compare/1.0...1.1
 
     $ git compare -u fix
@@ -265,35 +307,25 @@ If you see nothing, you need to set the config setting:
     $ git config --global github.user YOUR_USER
 
 For commands that require write access to GitHub (such as `fork`), you'll want to
-setup "github.token" as well. See [local GitHub config guide][2] for more information.
-
-Want to use environment variables instead of a local gitconfig?
+setup "github.token" as well. See [GitHub config guide][2] for more information.
 
-* `GITHUB_USER`  - If set, this will be used instead of the `github.user` config
-                   value to determine your GitHub username.
-* `GITHUB_TOKEN` - If set, this will be used instead of the `github.token` config
-                   value to determine your GitHub API token.
+If present, environment variables `GITHUB_USER` and `GITHUB_TOKEN` override the
+values of "github.user" and "github.token".
 
 Configuration
 -------------
 
-If you prefer `http://` clones to `git://` clones, you can set the
-`hub.http-clone` option to true using `git-config`.
+If you prefer using the HTTPS protocol for GitHub repositories instead of the git
+protocol for read and ssh for write, you can set "hub.protocol" to "https".
 
 For example:
 
     $ git clone defunkt/repl
     < git clone >
-    $ git config --global --bool hub.http-clone true
+    
+    $ git config --global hub.protocol https
     $ git clone defunkt/repl
-    < http clone >
-
-Or you can enter this manually into your `~/.gitconfig` file:
-
-    $ cat ~/.gitconfig
-    [hub]
-      http-clone = yes
-
+    < https clone >
 
 Prior Art
 ---------
@@ -302,41 +334,45 @@ These projects also aim to either improve git or make interacting with
 GitHub simpler:
 
 * [eg](http://www.gnome.org/~newren/eg/)
-* [github-gem](http://github.com/defunkt/github-gem)
-* [gh](http://github.com/visionmedia/gh)
+* [github-gem](https://github.com/defunkt/github-gem)
 
 
 Contributing
 ------------
 
-Once you've made your great commits:
-
-1. [Fork][0] hub
-2. Create a topic branch - `git checkout -b my_branch`
-3. Push to your branch - `git push origin my_branch`
-4. Create an [Issue][1] with a link to your branch
-5. That's it!
-
-### Development Gems
-You will need the following gems (and their dependencies) to
-contribute to `hub`:
-
-* `rake` (`gem install rake`)
-* `kicker` (`gem install kicker`)
-* `turn` (`gem install turn`)
-* `mg` (`gem install mg`)
-* `ronn` (`gem install ronn`)
-* `webmock` (`gem install webmock`)
+These instructions assume that you already have `hub` installed and that
+you've set it up so it wraps `git` (see "Aliasing").
+
+1. Clone hub:  
+    `git clone defunkt/hub`
+2. Verify that existing tests pass (see "Development dependencies"):  
+    `rake test`
+3. Create a topic branch:  
+    `git checkout -b my_branch`
+4. Make your changes – it helps a lot if you write tests first
+5. Verify that tests still pass:  
+    `rake test`
+6. Fork hub on GitHub (adds a remote named "YOUR_USER"):  
+    `git fork`
+7. Push to your fork:  
+    `git push -u YOUR_USER my_branch`
+8. Open a pull request describing your changes:  
+    `git pull-request`
+
+### Development dependencies
+
+You will need the following libraries for development:
+
+* [ronn](https://github.com/rtomayko/ronn) (building man pages)
+* [webmock](https://github.com/bblimke/webmock)
+* [json](http://flori.github.com/json/) (ruby 1.8 only)
 
 Meta
 ----
 
-* Code: `git clone git://github.com/defunkt/hub.git`
-* Home: <http://github.com/defunkt/hub>
-* Bugs: <http://github.com/defunkt/hub/issues>
-* List: <http://groups.google.com/group/github>
-* Test: <http://runcoderun.com/defunkt/hub>
-* Gems: <http://gemcutter.org/gems/hub>
+* Home: <https://github.com/defunkt/hub>
+* Bugs: <https://github.com/defunkt/hub/issues>
+* Gem: <https://rubygems.org/gems/hub>
 
 
 Authors
@@ -344,8 +380,6 @@ Authors
 
 <https://github.com/defunkt/hub/contributors>
 
-[0]: http://help.github.com/forking/
-[1]: http://github.com/defunkt/hub/issues
 [speed]: http://gist.github.com/284823
-[2]: http://github.com/guides/local-github-config
+[2]: http://help.github.com/set-your-user-name-email-and-github-token/
 [gc]: https://twitter.com/brynary/status/49560668994674688

data/Rakefile

@@ -4,19 +4,21 @@ require 'rake/testtask'
 # Helpers
 #
 
-def command?(command)
-  `which #{command} 2>/dev/null`
-  $?.success?
+def command?(util)
+  Rake::Task[:load_path].invoke
+  context = Object.new
+  require 'hub/context'
+  context.extend Hub::Context
+  context.send(:command?, util)
 end
 
-task :load_hub do
-  $LOAD_PATH.unshift 'lib'
-  require 'hub'
+task :load_path do
+  $LOAD_PATH.unshift File.expand_path('../lib', __FILE__)
 end
 
 task :check_dirty do
-  if !`git status`.include?('nothing to commit')
-    abort "dirty index - not publishing!"
+  unless system 'git', 'diff', '--quiet', 'HEAD'
+    abort "Aborted: you have uncommitted changes"
   end
 end
 
@@ -27,19 +29,11 @@ end
 
 task :default => :test
 
-if command? :turn
-  desc "Run tests"
-  task :test do
-    suffix = "-n #{ENV['TEST']}" if ENV['TEST']
-    sh "turn test/*.rb #{suffix}"
-  end
-else
-  Rake::TestTask.new do |t|
-    t.libs << 'lib'
-    t.ruby_opts << '-rubygems'
-    t.pattern = 'test/**/*_test.rb'
-    t.verbose = false
-  end
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.ruby_opts << '-rubygems'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
 end
 
 if command? :kicker
@@ -52,34 +46,71 @@ end
 
 
 #
-# Ron
+# Manual
 #
 
 if command? :ronn
-  desc "Show the manual"
+  desc "Show man page"
   task :man => "man:build" do
     exec "man man/hub.1"
   end
 
-  desc "Build the manual"
-  task "man:build" do
-    sh "ronn -br5 --organization=DEFUNKT --manual='Git Manual' man/*.ronn"
+  desc "Build man pages"
+  task "man:build" => ["man/hub.1", "man/hub.1.html"]
+
+  extract_examples = lambda { |readme_file|
+    # split readme in sections
+    examples = File.read(readme_file).split(/^-{4,}$/)[3].strip
+    examples.sub!(/^.+?(###)/m, '\1')  # strip intro paragraph
+    examples.sub!(/\n+.+\Z/, '')       # remove last line
+    examples
+  }
+
+  # inject examples from README file to .ronn source
+  source_with_examples = lambda { |source, readme|
+    examples = extract_examples.call(readme)
+    compiled = File.read(source)
+    compiled.sub!('{{README}}', examples)
+    compiled
+  }
+
+  # generate man page with ronn
+  compile_ronn = lambda { |destination, type, contents|
+    File.popen("ronn --pipe --#{type} --organization=DEFUNKT --manual='Git Manual'", 'w+') { |io|
+      io.write contents
+      io.close_write
+      File.open(destination, 'w') { |f| f << io.read }
+    }
+    abort "ronn --#{type} conversion failed" unless $?.success?
+  }
+
+  file "man/hub.1" => ["man/hub.1.ronn", "README.md"] do |task|
+    contents = source_with_examples.call(*task.prerequisites)
+    compile_ronn.call(task.name, 'roff', contents)
+    compile_ronn.call("#{task.name}.html", 'html', contents)
+  end
+
+  file "man/hub.1.html" => ["man/hub.1.ronn", "README.md"] do |task|
+    Rake::Task["man/hub.1"].invoke
   end
 end
 
 
 #
-# Gems
+# Build
 #
 
-desc "Build standalone script"
-task :standalone => :load_hub do
+file "hub" => FileList.new("lib/hub/*.rb", "man/hub.1") do |task|
+  Rake::Task[:load_path].invoke
   require 'hub/standalone'
-  Hub::Standalone.save('hub')
+  Hub::Standalone.save(task.name)
 end
 
+desc "Build standalone script"
+task :standalone => "hub"
+
 desc "Install standalone script and man pages"
-task :install => :standalone do
+task :install => "hub" do
   prefix = ENV['PREFIX'] || ENV['prefix'] || '/usr/local'
 
   FileUtils.mkdir_p "#{prefix}/bin"
@@ -89,16 +120,21 @@ task :install => :standalone do
   FileUtils.cp "man/hub.1", "#{prefix}/share/man/man1"
 end
 
-desc "Publish to GitHub Pages"
-task :pages => [ "man:build", :check_dirty, :standalone ] do
+desc "Copy files to gh-pages branch, but don't publish"
+task :gh_pages => [:check_dirty, "hub", "man/hub.1.html"] do
   cp "man/hub.1.html", "html"
   sh "git checkout gh-pages"
-  sh "mv hub standalone"
-  sh "git add standalone*"
-  sh "mv html hub.1.html"
-  sh "git add hub.1.html"
+  # replace the specific shebang with a generic ruby one
+  sh "echo '#!/usr/bin/env' ruby > standalone"
+  sh "sed 1d hub >> standalone"
+  mv "html", "hub.1.html"
+  sh "git add standalone hub.1.html"
   sh "git commit -m 'update standalone'"
+end
+
+desc "Publish to GitHub Pages"
+task :pages => :gh_pages do
   sh "git push origin gh-pages"
   sh "git checkout master"
-  puts :done
+  puts "Done."
 end

data/lib/hub/args.rb

@@ -12,7 +12,7 @@ module Hub
       super
       @executable = ENV["GIT"] || "git"
       @after = nil
-      @skip = false
+      @skip = @noop = false
       @original_args = args.first
       @chain = [nil]
     end
@@ -43,20 +43,33 @@ module Hub
 
     # Skip running this command.
     def skip!
-      @skip ||= true
+      @skip = true
     end
-    
+
     # Boolean indicating whether this command will run.
     def skip?
       @skip
     end
 
+    # Mark that this command shouldn't really run.
+    def noop!
+      @noop = true
+    end
+
+    def noop?
+      @noop
+    end
+
     # Array of `executable` followed by all args suitable as arguments
     # for `exec` or `system` calls.
     def to_exec(args = self)
       Array(executable) + args
     end
 
+    def add_exec_flags(flags)
+      self.executable = Array(executable).concat(flags)
+    end
+
     # All the words (as opposed to flags) contained in this argument
     # list.
     #