twig 1.0.1 → 1.1

data/CONTRIBUTING.md

@@ -8,18 +8,24 @@ Found a bug or have a suggestion? [Please open an issue][issues] or ping
 
 If you want to hack on some code, even better! Here are the basics:
 
-1.  Fork the Twig repo.
-2.  Check out the [**`development`** branch][dev branch]; the `master` branch is
+1.  If you plan to work on a large feature or bug fix, first
+    [open an issue][issues] first to discuss whether you're on the right track.
+    If you're working on something small, go right ahead.
+2.  Fork the Twig repo.
+3.  Check out the [**`development`** branch][dev branch]; the `master` branch is
     for stable builds only.
-3.  Run the tests to make sure that they pass on your machine: `bundle && rake`
-4.  Add one or more failing tests for your feature or bug fix.
-5.  Write your feature or bug fix to make the test(s) pass. Tests should pass in
-    the latest **Ruby 1.8.7** and **Ruby 1.9.3**, which you can do with
-    [rvm][rvm] or [rbenv][rbenv].
-6.  Test the change manually:
+4.  Run the tests to make sure that they pass on your machine: `bundle && rake`
+5.  Add one or more failing tests for your feature or bug fix.
+6.  Write your feature or bug fix to make the test(s) pass.
+    * Tests should pass in the latest **Ruby 1.8.7** and **Ruby 1.9.3**, which
+      you can do with [rvm][rvm] or [rbenv][rbenv].
+    * Keep the branch focused on a single topic, rather than covering multiple
+      features or bug fixes in a single branch. This makes branches quicker to
+      review and merge.
+7.  Test the change manually:
     1.  `gem build twig.gemspec`
     2.  `gem install twig-x.y.z.gem` (fill in the current version number)
-7.  Push to your fork and submit a pull request.
+8.  Push to your fork and submit a pull request.
 
 Thanks for contributing!
 

data/HISTORY.md

@@ -1,6 +1,22 @@
 Twig
 ====
 
+1.1 (2013-03-06)
+----------------
+* ENHANCEMENT: Add branch name tab completion for `-b` and `--branch` options.
+  (GH-12)
+* ENHANCEMENT: Add `--header-style` option for changing the column headers'
+  colors and weights. (GH-11. Thanks [tsujigiri](https://github.com/tsujigiri)!)
+* ENHANCEMENT: Add `twig gh-open-issue` for opening a branch's GitHub issue, if
+  any, in a browser.
+* FIX: Make `branch` a reserved property name, along with `merge`, `rebase`, and
+  `remote`.
+* 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
+  empty string.
+
 1.0.1 (2013-02-13)
 ------------------
 * ENHANCEMENT: Add Travis CI integration for running tests in multiple versions

data/README.md

@@ -43,6 +43,8 @@ chronologically with their properties.
 * `twig <property> -b <branch>`:         Get property for any branch
 * `twig <property> <value> -b <branch>`: Set property for any branch
 * `twig --unset <property> -b <branch>`: Unset property for any branch
+* `twig --header-style <format>`:        Change the header style, e.g., "red", "green bold"
+* `twig init-completion`:                Set up tab completion for `-b` and `--branch`
 * `twig --help`:                         More info
 
 
@@ -66,6 +68,7 @@ automatically included when you run `twig`. Example:
 
     # ~/.twigrc:
     except-branch: staging
+    header-style:  green bold
     max-days-old:  30
 
 
@@ -137,8 +140,8 @@ You can set just about any custom property you need to remember for each branch.
 Subcommands
 ===========
 
-Twig comes with two subcommands, `gh-open` and `gh-update`, which are handy for
-use with GitHub repositories.
+Twig comes with a few subcommands that are handy for use with GitHub
+repositories: `gh-open`, `gh-open-issue`, and `gh-update`.
 
 While inside a Git repo, run `twig gh-open` to see the repo's GitHub URL, and open
 a browser window if possible:
@@ -149,8 +152,8 @@ a browser window if possible:
     GitHub URL: https://github.com/myname/myproject
     # Also opens a browser window (OS X only).
 
-If you're working on an issue for a GitHub repository, you can also use the
-`gh-update` subcommand:
+If you're working on an issue for a GitHub repository, the `gh-update`
+subcommand syncs issue statuses with GitHub:
 
     $ git checkout add-feature
     Switched to branch 'add-feature'.
@@ -180,6 +183,18 @@ If you're working on an issue for a GitHub repository, you can also use the
 
 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
+    # Also opens a browser window (OS X only).
+
+    # Any branch:
+    $ twig gh-open-issue -b <branch name>
+    GitHub issue URL: https://github.com/myname/myproject/issues/222
+
 You can write any Twig subcommand that fits your own Git workflow. To write a
 Twig subcommand:
 
@@ -204,6 +219,7 @@ Some ideas for subcommands:
   they've shipped.
 * Generate a formatted list of your branches from the past week. Useful for
   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]!

data/bin/twig

@@ -1,6 +1,6 @@
 #!/usr/bin/env ruby
 
-require File.join(File.dirname(__FILE__), '..', 'lib', 'twig')
+require File.expand_path(File.join(File.dirname(__FILE__), '..', 'lib', 'twig'))
 
 twig = Twig.new
 abort unless twig.repo?

data/bin/twig-gh-open-issue

@@ -0,0 +1,59 @@
+#!/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.
+#
+# Author: Ron DeVera <http://rondevera.com>
+
+require 'rubygems'
+require 'twig'
+
+class TwigGithubRepo
+  def initialize
+    if origin_url.empty? || username.empty? || repository.empty?
+      abort_for_non_github_repo
+    end
+
+    yield(self)
+  end
+
+  def origin_url
+    @origin_url ||= `git config remote.origin.url`.strip
+  end
+
+  def origin_url_parts
+    @origin_url_parts ||= origin_url.split(/[\/:]/)
+  end
+
+  def username
+    @username ||= origin_url_parts[-2] || ''
+  end
+
+  def repository
+    @repo ||= origin_url_parts[-1].sub(/\.git$/, '') || ''
+  end
+
+  def abort_for_non_github_repo
+    abort 'This does not appear to be a GitHub repository.'
+  end
+end
+
+TwigGithubRepo.new do |gh_repo|
+  twig = Twig.new
+  twig.read_cli_options!(ARGV)
+  branch_name = twig.options[:branch] || twig.current_branch_name
+  issue_id = twig.get_branch_property(branch_name, 'issue')
+
+  unless issue_id
+    abort %{The branch "#{branch_name}" doesn't have an "issue" property.}
+  end
+
+  url = "https://github.com/#{gh_repo.username}/#{gh_repo.repository}"
+  url << "/issues/#{issue_id}"
+
+  puts "GitHub issue URL: #{url}"
+  `which open && open #{url}`
+end

data/bin/twig-help

@@ -1,4 +1,7 @@
 #!/usr/bin/env ruby
 
 # Your friendly neighborhood `twig --help` alias.
+#
+# Author: Ron DeVera <http://rondevera.com>
+
 puts `twig --help`

data/bin/twig-init-completion

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+
+# Initializes tab completion for Twig. To use this, run
+# `twig init-completion` and follow the instructions.
+#
+# Author: Ron DeVera <http://rondevera.com>
+
+debug = ARGV.include?('--debug')
+bash_version = `bash -c 'echo $BASH_VERSION'`.strip
+
+if debug
+  puts "- Ruby version: #{`ruby --version`.strip}"
+  puts "- bash_version: #{bash_version.inspect}"
+end
+
+exec('twig-init-completion-bash') if bash_version != ''
+abort 'Could not initialize Twig tab completion for this shell.'

data/bin/twig-init-completion-bash

@@ -0,0 +1,69 @@
+#!/usr/bin/env ruby
+
+# Initializes bash tab completion for Twig. To use this, run
+# `twig init-completion` and follow the instructions.
+#
+# Author: Ron DeVera <http://rondevera.com>
+
+require 'fileutils'
+
+version = `twig --version`.strip
+script = <<-SCRIPT
+
+#!/usr/bin/env bash
+
+# AUTO-GENERATED with Twig v#{version}. Regenerate with `twig init-completion`.
+#
+# Initializes bash tab completion for Twig. To use this, run
+# `twig init-completion` and follow the instructions.
+#
+# 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' ' ')"
+  COMPREPLY=($(compgen -W "$words" -- "$current"))
+  return 0
+}
+
+__twig() {
+  if [ -z "$(git rev-parse HEAD 2>/dev/null)" ]; then
+    return 0;
+  fi
+
+  local previous=${COMP_WORDS[COMP_CWORD-1]}
+
+  case "${previous}" in
+  -b|--branch)  __twig_branches ;;
+  esac
+
+  return 0
+}
+
+complete -F __twig twig
+
+SCRIPT
+script = script.strip + "\n"
+
+
+
+twig_dir = '~/.twig'
+FileUtils.mkdir_p(File.expand_path(twig_dir))
+
+script_path = File.join(twig_dir, '/twig-completion.bash')
+full_script_path = File.expand_path(script_path)
+unless File.exists?(full_script_path)
+  File.open(full_script_path, 'w') do |file|
+    file.write script
+  end
+  puts "Created #{script_path}."
+end
+
+puts
+puts 'To enable tab completion for Twig, add the following to your `~/.bashrc`'
+puts 'or equivalent:'
+puts
+puts "  [[ -s #{script_path} ]] && source #{script_path}"
+puts
+puts 'To finish setup, open a new command-line window or run `source ~/.bashrc`.'

data/lib/twig.rb

@@ -1,4 +1,4 @@
-Dir[File.join(File.dirname(__FILE__), 'twig', '*')].each { |file| require file }
+Dir[File.join(File.dirname(__FILE__), 'twig', '*.rb')].each { |file| require file }
 require 'time'
 
 class Twig
@@ -9,21 +9,20 @@ class Twig
   attr_accessor :options
 
   REF_FORMAT_SEPARATOR = ','
-  REF_FORMAT = %w[refname committerdate committerdate:relative].
+  REF_FORMAT = %w[refname:short committerdate committerdate:relative].
                 map { |field| '%(' + field + ')' }.join(REF_FORMAT_SEPARATOR)
   REF_PREFIX = 'refs/heads/'
+  DEFAULT_HEADER_COLOR = :blue
 
   def self.run(command)
     `#{command}`.strip
   end
 
-  def initialize(options = {})
-    # Options:
-    # - :branch_except (Regexp)
-    # - :branch_only (Regexp)
-    # - :max_days_old (integer)
+  def initialize
+    self.options = {}
 
-    self.options = options
+    # Set defaults
+    set_option(:header_style, DEFAULT_HEADER_COLOR.to_s)
   end
 
   def repo?
@@ -44,10 +43,9 @@ class Twig
 
       branch_tuples.inject([]) do |result, branch_tuple|
         ref, time_string, time_ago = branch_tuple.split(REF_FORMAT_SEPARATOR)
-        name        = ref.sub(%r{^#{ REF_PREFIX }}, '')
         time        = Time.parse(time_string)
         commit_time = Twig::CommitTime.new(time, time_ago)
-        branch      = Branch.new(name, :last_commit_time => commit_time)
+        branch      = Branch.new(ref, :last_commit_time => commit_time)
         result << branch
       end
     end
@@ -88,7 +86,7 @@ class Twig
       end
     end
 
-    out = "\n" << branch_list_headers
+    out = "\n" << branch_list_headers(options)
 
     # List most recently modified branches first
     listable_branches =

data/lib/twig/branch.rb

@@ -1,8 +1,17 @@
 class Twig
   class Branch
 
-    RESERVED_BRANCH_PROPERTIES    = %w[merge rebase remote]
+    EMPTY_PROPERTY_NAME_ERROR     = 'Branch property names cannot be empty strings.'
     PROPERTY_NAME_FROM_GIT_CONFIG = /^branch\.[^.]+\.([^=]+)=.*$/
+    RESERVED_BRANCH_PROPERTIES    = %w[branch merge rebase remote]
+
+    class EmptyPropertyNameError < ArgumentError
+      def initialize(message = nil)
+        message ||= EMPTY_PROPERTY_NAME_ERROR
+        super
+      end
+    end
+    class MissingPropertyError < StandardError; end
 
     attr_accessor :name, :last_commit_time
 
@@ -38,35 +47,48 @@ class Twig
     end
 
     def get_property(property_name)
-      Twig.run("git config branch.#{name}.#{property_name}")
+      property_name = sanitize_property(property_name)
+      raise EmptyPropertyNameError if property_name.empty?
+
+      value = Twig.run("git config branch.#{name}.#{property_name}")
+      value == '' ? nil : value
     end
 
     def set_property(property_name, value)
       property_name = sanitize_property(property_name)
       value = value.to_s.strip
 
-      if RESERVED_BRANCH_PROPERTIES.include?(property_name)
-        %{Can't modify the reserved property "#{property_name}".}
+      if property_name.empty?
+        raise EmptyPropertyNameError
+      elsif RESERVED_BRANCH_PROPERTIES.include?(property_name)
+        raise ArgumentError,
+          %{Can't modify the reserved property "#{property_name}".}
       elsif value.empty?
-        %{Can't set a branch property to an empty string.}
+        raise ArgumentError,
+          %{Can't set a branch property to an empty string.}
       else
         Twig.run(%{git config branch.#{name}.#{property_name} "#{value}"})
         result_body = %{property "#{property_name}" as "#{value}" for branch "#{name}".}
         if $?.success?
           "Saved #{result_body}"
         else
-          "Could not save #{result_body}"
+          raise RuntimeError, "Could not save #{result_body}"
         end
       end
     end
 
     def unset_property(property_name)
+      property_name = sanitize_property(property_name)
+      raise EmptyPropertyNameError if property_name.empty?
+
       value = get_property(property_name)
-      if value && !value.empty?
+
+      if value
         Twig.run(%{git config --unset branch.#{name}.#{property_name}})
         %{Removed property "#{property_name}" for branch "#{name}".}
       else
-        %{The branch "#{name}" does not have the property "#{property_name}".}
+        raise MissingPropertyError,
+          %{The branch "#{name}" does not have the property "#{property_name}".}
       end
     end
 

data/lib/twig/cli.rb

@@ -6,45 +6,58 @@ class Twig
     def help_intro
       version_string = "Twig v#{Twig::VERSION}"
 
+      intro = help_paragraph(%{
+        Twig is your personal Git branch assistant. It shows you your most
+        recent branches, and tracks issue tracker ids, tasks, and other metadata
+        for your Git branches.
+      })
+
       <<-BANNER.gsub(/^[ ]+/, '')
 
         #{version_string}
         #{'-' * version_string.size}
 
-        Twig is your personal Git branch assistant. It shows you your most
-        recent branches, and tracks issue tracker ids, tasks, and other metadata
-        for your Git branches.
+        #{intro}
 
         https://rondevera.github.com/twig
 
       BANNER
     end
 
-    def help_separator(option_parser, text)
-      option_parser.separator "\n#{text}\n\n"
+    def help_separator(option_parser, text, options={})
+      options[:trailing] ||= "\n\n"
+      option_parser.separator "\n#{text}#{options[:trailing]}"
     end
 
     def help_description(text, options={})
       width = options[:width] || 40
-      text  = text.dup
-
-      # Split into lines
+      words = text.gsub(/\n?\s+/, ' ').strip.split(' ')
       lines = []
-      until text.empty?
-        if text.size > width
-          split_index = text[0..width].rindex(' ') || width
-          lines << text.slice!(0, split_index)
-          text.strip!
+
+      # Split words into lines
+      while words.any?
+        current_word = words.shift
+        current_word_size = formatted_string_display_size(current_word)
+        last_line_size = lines.last && formatted_string_display_size(lines.last)
+
+        if last_line_size && (last_line_size + current_word_size + 1 <= width)
+          lines.last << ' ' << current_word
+        elsif current_word_size >= width
+          lines << current_word[0...width]
+          words.unshift(current_word[width..-1])
         else
-          lines << text.slice!(0..-1)
+          lines << current_word
         end
       end
 
       lines << ' ' if options[:add_separator]
-
       lines
     end
 
+    def help_paragraph(text)
+      help_description(text, :width => 80).join("\n")
+    end
+
     def read_cli_options!(args)
       option_parser = OptionParser.new do |opts|
         opts.banner         = help_intro
@@ -114,13 +127,46 @@ class Twig
           unset_option(:branch_only)
         end
 
+
+
+        help_separator(opts, 'Listing branches:')
+
+        colors = Twig::Display::COLORS.keys.map do |value|
+          format_string(value, { :color => value })
+        end.join(', ')
+        weights = Twig::Display::WEIGHTS.keys.map do |value|
+          format_string(value, { :weight => value })
+        end.join(' and ')
+        default_color = format_string(
+          Twig::DEFAULT_HEADER_COLOR.to_s,
+          :color => Twig::DEFAULT_HEADER_COLOR
+        )
+        desc = <<-DESC
+          STYLE is a color, weight, or a space-separated pair of one of each.
+          Valid colors are #{colors}. Valid weights are #{weights}.
+          The default is "#{default_color}".
+        DESC
+        opts.on('--header-style "STYLE"', *help_description(desc)) do |style|
+          set_option(:header_style, style)
+        end
+
+
+
+        help_separator(opts, help_paragraph(%{
+          You can put your most frequently used options for filtering and
+          listing branches into #{Twig::Options::CONFIG_FILE}. For example:
+        }), :trailing => '')
+
         help_separator(opts, [
-          'You can put your most frequently used branch filtering options in',
-          "#{Twig::Options::CONFIG_FILE}. For example:",
-          '',
           '      except-branch: staging',
+          '      header-style:  green bold',
           '      max-days-old:  30'
-        ].join("\n"))
+        ].join("\n"), :trailing => '')
+
+        help_separator(opts, help_paragraph(%{
+          To enable tab completion for Twig, run `twig init-completion` and
+          follow the instructions.
+        }))
       end
 
       option_parser.parse!(args)
@@ -154,19 +200,31 @@ class Twig
         # Get/set branch property
         if property_value
           # `$ twig <key> <value>`
-          puts set_branch_property(branch_name, property_name, property_value)
+          begin
+            puts set_branch_property(branch_name, property_name, property_value)
+          rescue ArgumentError, RuntimeError => exception
+            abort exception.message
+          end
         else
           # `$ twig <key>`
-          value = get_branch_property(branch_name, property_name)
-          if value && !value.empty?
-            puts value
-          else
-            abort %{The branch "#{branch_name}" does not have the property "#{property_name}".}
+          begin
+            value = get_branch_property(branch_name, property_name)
+            if value
+              puts value
+            else
+              abort %{The branch "#{branch_name}" does not have the property "#{property_name}".}
+            end
+          rescue ArgumentError => exception
+            abort exception.message
           end
         end
       elsif property_to_unset
         # `$ twig --unset <key>`
-        puts unset_branch_property(branch_name, property_to_unset)
+        begin
+          puts unset_branch_property(branch_name, property_to_unset)
+        rescue ArgumentError, Twig::Branch::MissingPropertyError => exception
+          abort exception.message
+        end
       else
         # `$ twig`
         puts list_branches