twig 1.3 → 1.4

data/HISTORY.md

@@ -1,6 +1,22 @@
 Twig
 ====
 
+1.4 (2013-08-07)
+----------------
+* ENHANCEMENT: Speed up listing branches by 3–4x.
+* ENHANCEMENT: Add `twig diff`, which diffs the current branch against its
+  `diff-branch` property, and `twig diff <branch>`, which diffs the given branch
+  against its `diff-branch` property.
+* ENHANCEMENT: Add `twig rebase`, which rebases the current branch onto the
+  branch in its `diff-branch` property, and `twig rebase <branch>`, which
+  rebases the given branch onto its `diff-branch`.
+* ENHANCEMENT: Add `twig init-completion --force` for overwriting existing
+  completion scripts. Useful for upgrading to the latest Twig completion
+  scripts.
+* ENHANCEMENT: Improve `twig gh-update` error reporting by listing the affected
+  API endpoints upon failure.
+* FIX: Deprecate `~/.twigrc` in favor of `~/.twigconfig`.
+
 1.3 (2013-05-22)
 ----------------
 * ENHANCEMENT: Add `--branch-width` and `--<property>-width` options for setting
@@ -43,7 +59,7 @@ Twig
 * FIX: Handle line breaks gracefully in `~/.twigrc` config file.
 * FIX: Exit with a non-zero status when trying to get or unset a branch property
   that isn't set, or trying to set a branch property to an invalid value.
-* FIX : Don't allow getting/setting/unsetting a branch property whose name is an
+* FIX: Don't allow getting/setting/unsetting a branch property whose name is an
   empty string.
 
 1.0.1 (2013-02-13)

data/README.md

@@ -44,6 +44,7 @@ chronologically with their properties.
 * `twig <property> <value> -b <branch>`: Set property for any branch
 * `twig --unset <property> -b <branch>`: Unset property for any branch
 * `twig init-completion`:                Set up tab completion for `-b` and `--branch`
+* `twig init-completion --force`:        Update to the latest tab completion script
 * `twig --help`:                         More info
 
 
@@ -131,15 +132,15 @@ Remember the order in which you were rebasing your stack of branches:
     $ git checkout master
     Switched to branch 'master'.
 
-    $ twig rebase-onto branch2 -b branch3
-    Saved property "rebase-onto" as "branch2" for branch "branch3".
+    $ twig diff-branch branch2 -b branch3
+    Saved property "diff-branch" as "branch2" for branch "branch3".
 
-    $ twig rebase-onto branch1 -b branch2
-    Saved property "rebase-onto" as "branch1" for branch "branch2".
+    $ twig diff-branch branch1 -b branch2
+    Saved property "diff-branch" as "branch1" for branch "branch2".
 
     $ twig
 
-                                  rebase-onto    branch
+                                  diff-branch    branch
                                   -----------    ------
     2013-01-26 18:00:25 (7m ago)  branch2        branch3
     2013-01-26 16:49:47 (2h ago)  branch1        branch2
@@ -152,17 +153,93 @@ You can set just about any custom property you need to remember for each branch.
 Subcommands
 ===========
 
-Twig comes with a few subcommands that are handy for use with GitHub
-repositories: `gh-open`, `gh-open-issue`, and `gh-update`.
+A Twig subcommand is a little script that makes use of a branch's Twig
+properties. You can [write your own](#writing-a-subcommand), but here are some
+subcommands that Twig comes with.
 
-While inside a Git repo, run `twig gh-open` to see the repo's GitHub URL, and open
-a browser window if possible:
+
+twig diff
+---------
+
+If you have a stack of branches with different parent branches, it gets tricky
+to remember which branch to diff against. `twig diff` makes it easy:
+
+    $ git checkout branch2
+
+    # Remember your branch's diff branch:
+    $ twig diff-branch branch1
+    Saved property "diff-branch" as "branch1" for branch "branch2".
+
+    # Generate a diff between branch1 (the current branch) and branch2:
+    $ twig diff
+
+More usage:
+
+    # Generate a diff between any given branch and its `diff-branch`:
+    $ twig diff my-other-branch
+
+    # Pass options through to `git diff`:
+    $ twig diff --stat
+
+    # Pipe results to a diff viewer:
+    $ twig diff | gitx
+
+
+twig rebase
+-----------
+
+If you have a stack of branches that you need to rebase in the same order,
+`twig rebase` simplifies the process:
+
+    $ git checkout branch2
+
+    # Remember your branches' diff (parent) branches:
+    $ twig diff-branch branch1
+    Saved property "diff-branch" as "branch1" for branch "branch2".
+
+    # Rebase branch2 (the current branch) onto branch1:
+    $ twig rebase
+    Rebase "branch2" onto "development"? (y/n)
+
+More usage:
+
+    # Rebase any given branch onto its `diff-branch`:
+    $ twig rebase my-other-branch
+
+    # Pass options through to `git rebase`:
+    $ twig rebase -i
+
+
+twig gh-open
+------------
+
+While inside a GitHub repo, run `twig gh-open` to see the repo's GitHub URL, and
+open a browser window if possible:
 
     $ cd myproject
 
     $ twig gh-open
     GitHub URL: https://github.com/myname/myproject
 
+
+twig gh-open-issue
+------------------
+
+For any branch that has an `issue` property, you can use the `gh-open-issue`
+subcommand to view that issue on GitHub:
+
+    # Current branch:
+    $ twig gh-open-issue
+    GitHub issue URL: https://github.com/myname/myproject/issues/111
+
+    # Any branch:
+    $ twig gh-open-issue -b <branch name>
+    GitHub issue URL: https://github.com/myname/myproject/issues/222
+
+
+twig gh-update
+--------------
+
 If you're working on an issue for a GitHub repository, the `gh-update`
 subcommand syncs issue statuses with GitHub:
 
@@ -181,6 +258,7 @@ subcommand syncs issue statuses with GitHub:
     2013-01-22 17:12:23 (4d ago)  -      -         master
 
     $ twig gh-update
+    Getting latest states for GitHub issues...
     # Automatically looks up the GitHub issue status for each
     # of your local branches, and saves it locally.
 
@@ -194,16 +272,9 @@ subcommand syncs issue statuses with GitHub:
 
 Run `twig gh-update` periodically to keep up with GitHub issues locally.
 
-For any branch that has an `issue` property, you can use the `gh-open-issue`
-subcommand to view that issue on GitHub:
 
-    # Current branch:
-    $ twig gh-open-issue
-    GitHub issue URL: https://github.com/myname/myproject/issues/111
-
-    # Any branch:
-    $ twig gh-open-issue -b <branch name>
-    GitHub issue URL: https://github.com/myname/myproject/issues/222
+Writing a subcommand
+--------------------
 
 You can write any Twig subcommand that fits your own Git workflow. To write a
 Twig subcommand:
@@ -231,8 +302,8 @@ Some ideas for subcommands:
   emailing your team about what you're up to.
 * Create a gem that contains your team's favorite custom Twig subcommands.
 
-If you write a subcommand that others can appreciate, send a pull request or add
-it to the [Twig wiki][wiki]!
+If you write a subcommand that others might appreciate, send a pull request or
+add it to the [Twig wiki][wiki]!
 
 
 More info

data/bin/twig

@@ -1,5 +1,7 @@
 #!/usr/bin/env ruby
 
+# Entry point for Twig: <http://rondevera.github.io/twig/>
+
 require File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib', 'twig'))
 
 repo_required = ARGV != ['--help'] && ARGV != ['help'] && ARGV != ['--version']

data/bin/twig-diff

@@ -0,0 +1,38 @@
+#!/usr/bin/env ruby
+
+# Summary:
+#
+#   `twig diff [<branch>] [<options>]`
+#
+# Usage:
+#
+# - `twig diff`:
+#   Shows the diff between the current branch and its `diff-branch` property.
+#
+# - `twig diff <options>`:
+#   Shows the diff between the current branch and its `diff-branch`, and passes
+#   options through to `git-diff`, e.g., `twig diff --stat`.
+#
+# - `twig diff <branch>`:
+#   Shows the diff between the given branch and its `diff-branch` property.
+#
+# - `twig diff <branch> <options>`:
+#   Shows the diff between the given branch and its `diff-branch`, and passes
+#   options through to `git-diff`, e.g., `twig diff my_branch --stat`.
+#
+# Subcommand for Twig: <http://rondevera.github.io/twig/>
+# Author: Ron DeVera <http://rondevera.com>
+
+args = ARGV.dup
+
+branch_given = args.any? && args.first[0, 1] != '-'
+topic_branch = args.shift.strip if branch_given           # Use given branch
+topic_branch ||= `git rev-parse --abbrev-ref HEAD`.strip  # Use current branch
+
+diff_branch  = `twig diff-branch -b "#{topic_branch}"`.strip
+diff_options = args.join(' ') # Pass remaining options to `git-diff`
+
+abort if diff_branch.empty?
+
+puts %{Getting diff of "#{topic_branch}" against "#{diff_branch}"...}
+exec %{git diff "#{diff_branch}" "#{topic_branch}" #{diff_options}}

data/bin/twig-gh-open

@@ -2,6 +2,7 @@
 
 # Opens a browser window for the current GitHub repo.
 #
+# Subcommand for Twig: <http://rondevera.github.io/twig/>
 # Author: Ron DeVera <http://rondevera.com>
 
 require 'rubygems'
@@ -9,7 +10,13 @@ require 'twig'
 require 'launchy'
 
 Twig::GithubRepo.new do |gh_repo|
-  url = "https://github.com/#{gh_repo.username}/#{gh_repo.repository}"
+  twig = Twig.new
+  twig.read_config_file!
+  twig.read_cli_options!(ARGV)
+
+  gh_uri_prefix = twig.options[:github_uri_prefix] || 'https://github.com'
+  url = "#{gh_uri_prefix}/#{gh_repo.username}/#{gh_repo.repository}"
+
   puts "GitHub URL: #{url}"
   Launchy.open(url) rescue nil
 end

data/bin/twig-gh-open-issue

@@ -1,11 +1,14 @@
 #!/usr/bin/env ruby
 
 # Usage:
+#
 # - `twig gh-open-issue`:
 #   Opens a browser window for the GitHub issue, if any, for the current branch.
+#
 # - `twig gh-open-issue -b <branch>`:
 #   Opens the GitHub issue, if any, for the specified branch.
 #
+# Subcommand for Twig: <http://rondevera.github.io/twig/>
 # Author: Ron DeVera <http://rondevera.com>
 
 require 'rubygems'
@@ -14,7 +17,9 @@ require 'launchy'
 
 Twig::GithubRepo.new do |gh_repo|
   twig = Twig.new
+  twig.read_config_file!
   twig.read_cli_options!(ARGV)
+
   branch_name = twig.options[:branch] || twig.current_branch_name
   issue_id = twig.get_branch_property(branch_name, 'issue')
 
@@ -22,7 +27,8 @@ Twig::GithubRepo.new do |gh_repo|
     abort %{The branch "#{branch_name}" doesn't have an "issue" property.}
   end
 
-  url = "https://github.com/#{gh_repo.username}/#{gh_repo.repository}"
+  gh_uri_prefix = twig.options[:github_uri_prefix] || 'https://github.com'
+  url = "#{gh_uri_prefix}/#{gh_repo.username}/#{gh_repo.repository}"
   url << "/issues/#{issue_id}"
 
   puts "GitHub issue URL: #{url}"

data/bin/twig-gh-update

@@ -2,6 +2,7 @@
 
 # Updates each branch with the latest issue status on GitHub.
 #
+# Subcommand for Twig: <http://rondevera.github.io/twig/>
 # Author: Ron DeVera <http://rondevera.com>
 
 require File.join(File.dirname(__FILE__), '..', 'lib', 'twig')
@@ -19,14 +20,18 @@ Twig::GithubRepo.new do |gh_repo|
   print 'Getting latest states for GitHub issues...'
 
   issues = {}
+  issues_uri_prefix = twig.options[:github_api_uri_prefix] || 'https://api.github.com'
   issues_uri_base =
-    "https://api.github.com/repos/#{gh_repo.username}/#{gh_repo.repository}/issues"
+    "#{issues_uri_prefix}/repos/#{gh_repo.username}/#{gh_repo.repository}/issues"
   issues_uris = [
     URI.parse("#{issues_uri_base}?state=open"),
     URI.parse("#{issues_uri_base}?state=closed")
   ]
   user_agent = "Twig/#{Twig::VERSION} (for Git; <#{Twig::HOMEPAGE}>)"
 
+  error = "\n\nERROR: Couldn't get open issues from GitHub." <<
+    "\n- API endpoints: " << issues_uris.map { |uri| "<#{uri}>" }.join(', ')
+
   begin
     issues_uris.each do |issues_uri|
       http = Net::HTTP.new(issues_uri.host, issues_uri.port)
@@ -44,10 +49,11 @@ Twig::GithubRepo.new do |gh_repo|
           issues[issue_data['number']] = issue_data
         end
       else
-        abort "\nERROR: Couldn't get open issues from GitHub. " <<
-          "(Response: #{response.code})"
+        abort error + "\n- Response: #{response.code}"
       end
     end
+  rescue OpenSSL::SSL::SSLError => exception
+    abort error
   end
 
   twig.branches.each do |branch|

data/bin/twig-help

@@ -2,6 +2,7 @@
 
 # Your friendly neighborhood `twig --help` alias.
 #
+# Subcommand for Twig: <http://rondevera.github.io/twig/>
 # Author: Ron DeVera <http://rondevera.com>
 
 puts `twig --help`

data/bin/twig-init-completion

@@ -3,9 +3,11 @@
 # Initializes tab completion for Twig. To use this, run
 # `twig init-completion` and follow the instructions.
 #
+# Subcommand for Twig: <http://rondevera.github.io/twig/>
 # Author: Ron DeVera <http://rondevera.com>
 
-debug = ARGV.include?('--debug')
+args  = ARGV.dup
+debug = args.delete('--debug')
 bash_version = `bash -c 'echo $BASH_VERSION'`.strip
 
 if debug
@@ -13,5 +15,5 @@ if debug
   puts "- bash_version: #{bash_version.inspect}"
 end
 
-exec('twig-init-completion-bash') if bash_version != ''
+exec('twig-init-completion-bash ' + args.join(' ')) if bash_version != ''
 abort 'Could not initialize Twig tab completion for this shell.'

data/bin/twig-init-completion-bash

@@ -3,6 +3,7 @@
 # Initializes bash tab completion for Twig. To use this, run
 # `twig init-completion` and follow the instructions.
 #
+# Subcommand for Twig: <http://rondevera.github.io/twig/>
 # Author: Ron DeVera <http://rondevera.com>
 
 require 'fileutils'
@@ -12,17 +13,19 @@ script = <<-SCRIPT
 
 #!/usr/bin/env bash
 
-# AUTO-GENERATED with Twig v#{version}. Regenerate with `twig init-completion`.
+# AUTO-GENERATED with Twig v#{version}. Regenerate with
+# `twig init-completion --force`.
 #
 # Initializes bash tab completion for Twig. To use this, run
 # `twig init-completion` and follow the instructions.
 #
+# Twig: <http://rondevera.github.io/twig/>
 # Author: Ron DeVera <http://rondevera.com>
 
 __twig_branches() {
   local current words
   current="${COMP_WORDS[COMP_CWORD]}"
-  words="$(git for-each-ref refs/heads/ --format="%(refname:short)" | tr '\n' ' ')"
+  words="$(git for-each-ref refs/heads/ --format="%(refname:short)" | tr '\\n' ' ')"
   COMPREPLY=($(compgen -W "$words" -- "$current"))
   return 0
 }
@@ -36,6 +39,9 @@ __twig() {
 
   case "${previous}" in
   -b|--branch)  __twig_branches ;;
+  diff)         __twig_branches ;;
+  diff-branch)  __twig_branches ;;
+  rebase)       __twig_branches ;;
   esac
 
   return 0
@@ -48,16 +54,29 @@ script = script.strip + "\n"
 
 
 
+args  = ARGV.dup
+force = args.delete('--force')
+
 twig_dir = '~/.twig'
 FileUtils.mkdir_p(File.expand_path(twig_dir))
 
-script_path = File.join(twig_dir, '/twig-completion.bash')
+script_path      = File.join(twig_dir, '/twig-completion.bash')
 full_script_path = File.expand_path(script_path)
-unless File.exists?(full_script_path)
+script_exists    = File.exists?(full_script_path)
+
+if script_exists && !force
+  puts "The file `#{script_path}` already exists."
+  puts "To overwrite it, run `twig init-completion --force`."
+else
   File.open(full_script_path, 'w') do |file|
     file.write script
   end
-  puts "Created #{script_path}."
+
+  if script_exists
+    puts "Overwrote #{script_path}."
+  else
+    puts "Created #{script_path}."
+  end
 end
 
 puts

data/bin/twig-rebase

@@ -0,0 +1,43 @@
+#!/usr/bin/env ruby
+
+# Summary:
+#
+#   `twig rebase [<branch>] [<options>]`
+#
+# Usage:
+#
+# - `twig rebase`:
+#   Rebases the current branch onto the branch in its `diff-branch` property.
+#
+# - `twig rebase <options>`:
+#   Rebases the current branch onto its `diff-branch`, and passes options
+#   through to `git-rebase`, e.g., `twig rebase -i`.
+#
+# - `twig rebase <branch>`:
+#   Rebases the given branch onto its `diff-branch`.
+#
+# - `twig rebase <branch> <options>`:
+#   Rebases the given branch and its `diff-branch`, and passes options
+#   through to `git-rebase`, e.g., `twig rebase my_branch -i`.
+#
+# Subcommand for Twig: <http://rondevera.github.io/twig/>
+# Author: Ron DeVera <http://rondevera.com>
+
+args = ARGV.dup
+
+branch_given = args.any? && args.first[0, 1] != '-'
+topic_branch = args.shift.strip if branch_given           # Use given branch
+topic_branch ||= `git rev-parse --abbrev-ref HEAD`.strip  # Use current branch
+
+base_branch    = `twig diff-branch -b "#{topic_branch}"`.strip
+rebase_options = args.join(' ') # Pass remaining options to `git-rebase`
+
+abort if base_branch.empty?
+
+print %{Rebase "#{topic_branch}" onto "#{base_branch}"? (y/n) }
+input = STDIN.gets.strip.downcase
+if input == 'y' || input == 'yes'
+  exec %{git rebase #{rebase_options} "#{base_branch}" "#{topic_branch}"}
+else
+  puts 'Cancelled.'
+end