twig 1.4 → 1.5

data/HISTORY.md

@@ -1,6 +1,21 @@
 Twig
 ====
 
+1.5 (2013-11-21)
+----------------
+* ENHANCEMENT: Add `--format=json` option for printing branch data as JSON
+  instead of a list. Useful for integrating Twig data into other tools.
+* ENHANCEMENT: Add tab completion for all subcommands, built-in (e.g., `twig
+  diff`, `twig gh-update`) and custom.
+* ENHANCEMENT: Paginate help content where possible.
+* ENHANCEMENT: Improve error messages `~/.twigconfig` isn't readable or contains
+  invalid lines.
+* ENHANCEMENT: Include default option values for branch listing and GitHub
+  integration in `twig --help`. (GH-30, GH-31)
+* FIX: Fix warnings when listing branches when a branch has UTF-8 characters in
+  its name. (GH-20)
+* FIX: Fix showing relative time for very old branches (e.g., "2y ago"). (GH-29)
+
 1.4 (2013-08-07)
 ----------------
 * ENHANCEMENT: Speed up listing branches by 3–4x.

data/README.md

@@ -1,6 +1,9 @@
 Twig: Your personal Git branch assistant.
 =========================================
 
+[![Gem Version](https://badge.fury.io/rb/twig.png)](http://badge.fury.io/rb/twig)
+[![Build Status](https://travis-ci.org/rondevera/twig.png?branch=development)](https://travis-ci.org/rondevera/twig)
+
 It's hard enough trying to remember the names of all of your Git branches. You
 also need those branches' issue tracker ids, issue statuses, and reminders of
 what to do next with each branch. `git branch` only lists them in alphabetical
@@ -76,10 +79,10 @@ them by age, name, and custom properties:
 * `twig --all`:
   List all branches regardless of other filtering options
 
-You can put your most frequently used options into `~/.twigrc`, and they'll be
-automatically included when you run `twig`. Example:
+You can put your most frequently used options into `~/.twigconfig`, and they'll
+be automatically included when you run `twig`. Example:
 
-    # ~/.twigrc:
+    # ~/.twigconfig:
     except-branch: staging
     header-style:  green bold
     max-days-old:  30
@@ -221,6 +224,9 @@ open a browser window if possible:
     $ twig gh-open
     GitHub URL: https://github.com/myname/myproject
 
+For GitHub Enterprise or other installations, you can change
+`https://github.com` by setting `github-uri-prefix` in `~/.twigrc`.
+
 
 twig gh-open-issue
 ------------------
@@ -236,6 +242,9 @@ subcommand to view that issue on GitHub:
     $ twig gh-open-issue -b <branch name>
     GitHub issue URL: https://github.com/myname/myproject/issues/222
 
+For GitHub Enterprise or other installations, you can change
+`https://github.com` by setting `github-uri-prefix` in `~/.twigrc`.
+
 
 twig gh-update
 --------------
@@ -272,6 +281,10 @@ subcommand syncs issue statuses with GitHub:
 
 Run `twig gh-update` periodically to keep up with GitHub issues locally.
 
+For GitHub Enterprise or other installations, you can change the default
+`https://api.github.com` endpoint prefix by setting `github-api-uri-prefix` in
+`~/.twigrc`.
+
 
 Writing a subcommand
 --------------------
@@ -309,7 +322,7 @@ add it to the [Twig wiki][wiki]!
 More info
 =========
 
-* **Requirements:** Tested with Git 1.6.5 and Ruby 1.8.7/1.9.2/1.9.3. Probably
+* **Requirements:** Tested with Git 1.6.5+ and Ruby 1.8.7/1.9.2/1.9.3. Probably
   works with older software, but it's not guaranteed.
 * **Contributing:** Found a bug or have a suggestion? [Please open an
   issue][issues] or ping [@ronalddevera on Twitter][twitter]. If you want to

data/bin/twig-gh-open

@@ -14,7 +14,7 @@ Twig::GithubRepo.new do |gh_repo|
   twig.read_config_file!
   twig.read_cli_options!(ARGV)
 
-  gh_uri_prefix = twig.options[:github_uri_prefix] || 'https://github.com'
+  gh_uri_prefix = twig.options[:github_uri_prefix]
   url = "#{gh_uri_prefix}/#{gh_repo.username}/#{gh_repo.repository}"
 
   puts "GitHub URL: #{url}"

data/bin/twig-gh-open-issue

@@ -27,7 +27,7 @@ Twig::GithubRepo.new do |gh_repo|
     abort %{The branch "#{branch_name}" doesn't have an "issue" property.}
   end
 
-  gh_uri_prefix = twig.options[:github_uri_prefix] || 'https://github.com'
+  gh_uri_prefix = twig.options[:github_uri_prefix]
   url = "#{gh_uri_prefix}/#{gh_repo.username}/#{gh_repo.repository}"
   url << "/issues/#{issue_id}"
 

data/bin/twig-gh-update

@@ -20,7 +20,7 @@ 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_prefix = twig.options[:github_api_uri_prefix]
   issues_uri_base =
     "#{issues_uri_prefix}/repos/#{gh_repo.username}/#{gh_repo.repository}/issues"
   issues_uris = [

data/bin/twig-help

@@ -5,4 +5,4 @@
 # Subcommand for Twig: <http://rondevera.github.io/twig/>
 # Author: Ron DeVera <http://rondevera.com>
 
-puts `twig --help`
+exec('twig --help')

data/bin/twig-init-completion-bash

@@ -7,19 +7,20 @@
 # Author: Ron DeVera <http://rondevera.com>
 
 require 'fileutils'
+require 'rubygems'
+require 'twig'
 
-version = `twig --version`.strip
 script = <<-SCRIPT
 
 #!/usr/bin/env bash
 
-# AUTO-GENERATED with Twig v#{version}. Regenerate with
+# AUTO-GENERATED with Twig v#{Twig::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/>
+# Twig: <#{Twig::HOMEPAGE}>
 # Author: Ron DeVera <http://rondevera.com>
 
 __twig_branches() {
@@ -30,6 +31,22 @@ __twig_branches() {
   return 0
 }
 
+__twig_formats() {
+  local current words
+  current="${COMP_WORDS[COMP_CWORD]}"
+  words="json"
+  COMPREPLY=($(compgen -W "$words" -- "$current"))
+  return 0
+}
+
+__twig_subcommands() {
+  local current words
+  current="${COMP_WORDS[COMP_CWORD]}"
+  words="#{Twig::Subcommands.all_names.join(' ')}"
+  COMPREPLY=($(compgen -W "$words" -- "$current"))
+  return 0
+}
+
 __twig() {
   if [ -z "$(git rev-parse HEAD 2>/dev/null)" ]; then
     return 0;
@@ -39,9 +56,11 @@ __twig() {
 
   case "${previous}" in
   -b|--branch)  __twig_branches ;;
+  --format)     __twig_formats ;;
   diff)         __twig_branches ;;
   diff-branch)  __twig_branches ;;
   rebase)       __twig_branches ;;
+  twig)         __twig_subcommands ;;
   esac
 
   return 0

data/bin/twig-rebase

@@ -35,7 +35,7 @@ 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
+input = $stdin.gets.strip.downcase
 if input == 'y' || input == 'yes'
   exec %{git rebase #{rebase_options} "#{base_branch}" "#{topic_branch}"}
 else

data/lib/twig.rb

@@ -1,6 +1,7 @@
 Dir[File.join(File.dirname(__FILE__), 'twig', '*.rb')].each { |file| require file }
 require 'time'
 
+# The main class.
 class Twig
   include Cli
   include Display
@@ -8,11 +9,13 @@ class Twig
 
   attr_accessor :options
 
-  REF_FORMAT_SEPARATOR = ','
+  DEFAULT_GITHUB_API_URI_PREFIX = 'https://api.github.com'
+  DEFAULT_GITHUB_URI_PREFIX = 'https://github.com'
+  DEFAULT_HEADER_COLOR = :blue
+  REF_FORMAT_SEPARATOR = '|'
   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
@@ -27,6 +30,8 @@ class Twig
     self.options = {}
 
     # Set defaults
+    set_option(:github_api_uri_prefix, DEFAULT_GITHUB_API_URI_PREFIX)
+    set_option(:github_uri_prefix, DEFAULT_GITHUB_URI_PREFIX)
     set_option(:header_style, DEFAULT_HEADER_COLOR.to_s)
   end
 
@@ -53,18 +58,21 @@ class Twig
   def branches
     branches = all_branches
     now = Time.now
-    max_seconds_old = options[:max_days_old] * 86400 if options[:max_days_old]
+    max_days_old = options[:max_days_old]
+    max_seconds_old = max_days_old * 86400 if max_days_old
 
-    branches.select do |branch|
+    branches = branches.select do |branch|
       catch :skip_branch do
         if max_seconds_old
           seconds_old = now.to_i - branch.last_commit_time.to_i
           next if seconds_old > max_seconds_old
         end
 
+        branch_name = branch.name
+
         (options[:property_except] || {}).each do |property_name, property_value|
           if property_name == :branch
-            throw :skip_branch if branch.name =~ property_value
+            throw :skip_branch if branch_name =~ property_value
           elsif branch.get_property(property_name.to_s) =~ property_value
             throw :skip_branch
           end
@@ -72,7 +80,7 @@ class Twig
 
         (options[:property_only] || {}).each do |property_name, property_value|
           if property_name == :branch
-            throw :skip_branch if branch.name !~ property_value
+            throw :skip_branch if branch_name !~ property_value
           elsif branch.get_property(property_name.to_s) !~ property_value
             throw :skip_branch
           end
@@ -81,6 +89,14 @@ class Twig
         true
       end
     end
+
+    # List least recently modified branches first
+    branches = branches.sort_by { |branch| branch.last_commit_time }
+    if options[:reverse] != true
+      branches.reverse! # List most recently modified branches first
+    end
+
+    branches
   end
 
   def all_branch_names
@@ -102,13 +118,7 @@ class Twig
 
     out = "\n" << branch_list_headers(options)
 
-    # List least recently modified branches first
-    listable_branches = branches.sort_by { |branch| branch.last_commit_time }
-    if options[:reverse] != true
-      listable_branches.reverse! # List most recently modified branches first
-    end
-
-    branch_lines = listable_branches.inject([]) do |result, branch|
+    branch_lines = branches.inject([]) do |result, branch|
       result << branch_list_line(branch)
     end
 

data/lib/twig/branch.rb

@@ -1,4 +1,6 @@
 class Twig
+
+  # Represents a Git branch.
   class Branch
 
     EMPTY_PROPERTY_NAME_ERROR      = 'Branch property names cannot be empty strings.'
@@ -22,8 +24,8 @@ class Twig
         properties = config_lines.map do |line|
           # Split by rightmost `=`, allowing branch names to contain `=`:
           key = value = nil
-          line.match(/(.+)=(.+)/).tap { |m| key, value = m[1..2] if m }
-          next if key.nil?
+          line.match(/(.+)=(.+)/).tap { |md| key, value = md[1..2] if md }
+          next unless key
 
           key_parts = key.split('.')
           key_parts.last if key_parts[0] == 'branch' && key_parts.size > 2
@@ -42,27 +44,40 @@ class Twig
 
     def to_s ; name ; end
 
+    def to_hash
+      all_property_names = Twig::Branch.all_property_names
+
+      {
+        'name' => name,
+        'last-commit-time' => last_commit_time.iso8601,
+        'properties' => get_properties(all_property_names)
+      }
+    end
+
     def sanitize_property(property_name)
       property_name.gsub(/[ _]+/, '')
     end
 
-    def get_properties(property_names)
-      return {} if property_names.empty?
-
-      property_name_regexps = property_names.map do |property_name|
+    def escaped_property_names(property_names)
+      property_names.map do |property_name|
         property_name = sanitize_property(property_name)
         raise EmptyPropertyNameError if property_name.empty?
         Regexp.escape(property_name)
-      end.join('|')
+      end
+    end
+
+    def get_properties(property_names)
+      return {} if property_names.empty?
 
-      git_config_regexp = "branch\.#{name}\.(#{ property_name_regexps })$"
+      property_names_regexp = escaped_property_names(property_names).join('|')
+      git_config_regexp     = "branch\.#{name}\.(#{ property_names_regexp })$"
       cmd = %{git config --get-regexp "#{git_config_regexp}"}
 
       git_result = Twig.run(cmd) || ''
       git_result_lines = git_result.split("\n")
 
       git_result_lines.inject({}) do |properties, line|
-        match_data = line.match(/^branch\.#{name}\.([^\s]+)\s+(.*)$/)
+        match_data = line.match(/^branch\.#{Regexp.escape(name)}\.([^\s]+)\s+(.*)$/)
 
         if match_data
           property_name = match_data[1]

data/lib/twig/cli.rb

@@ -1,4 +1,5 @@
 require 'optparse'
+require 'rbconfig'
 
 class Twig
   module Cli
@@ -25,24 +26,25 @@ class Twig
       intro + ' ' # Force extra blank line
     end
 
-    def help_separator(option_parser, text, options={})
+    def help_separator(option_parser, text, options = {})
       options[:trailing] ||= "\n\n"
       option_parser.separator "\n#{text}#{options[:trailing]}"
     end
 
-    def help_description(text, options={})
+    def help_description(text, options = {})
       width = options[:width] || 40
       words = text.gsub(/\n?\s+/, ' ').strip.split(' ')
       lines = []
 
       # Split words into lines
       while words.any?
-        current_word = words.shift
+        current_word      = words.shift
         current_word_size = unformat_string(current_word).size
-        last_line_size = lines.last && unformat_string(lines.last).size
+        last_line         = lines.last
+        last_line_size    = last_line && unformat_string(last_line).size
 
         if last_line_size && (last_line_size + current_word_size + 1 <= width)
-          lines.last << ' ' << current_word
+          last_line << ' ' << current_word
         elsif current_word_size >= width
           lines << current_word[0...width]
           words.unshift(current_word[width..-1])
@@ -55,7 +57,8 @@ class Twig
       lines
     end
 
-    def help_description_for_custom_property(option_parser, desc_lines)
+    def help_description_for_custom_property(option_parser, desc_lines, options = {})
+      options[:trailing] ||= "\n"
       indent = '      '
       left_column_width = 29
 
@@ -64,7 +67,7 @@ class Twig
         sprintf("%-#{left_column_width}s", left_column) + right_column + "\n"
       end
 
-      help_separator(option_parser, help_desc, :trailing => "\n")
+      help_separator(option_parser, help_desc, :trailing => options[:trailing])
     end
 
     def help_paragraph(text)
@@ -93,6 +96,36 @@ class Twig
       is_custom_property_width
     end
 
+    def run_pager
+      # Starts a pager so that all following STDOUT output is paginated.
+      # Based on: http://nex-3.com/posts/73-git-style-automatic-paging-in-ruby
+
+      return if Twig::System.windows? || !$stdout.tty?
+
+      read_io, write_io = IO.pipe
+
+      # Create child process
+      unless Kernel.fork
+        # The following runs only in the child process:
+        $stdout.reopen(write_io)
+        $stderr.reopen(write_io) if $stderr.tty?
+        read_io.close
+        write_io.close
+        return
+      end
+
+      $stdin.reopen(read_io)
+      read_io.close
+      write_io.close
+
+      ENV['LESS'] = 'FSRX'      # Don't page if the input fits on screen
+      Kernel.select([$stdin])   # Wait for input before starting pager
+
+      # Turn parent process into pager
+      pager = ENV['PAGER'] || 'less'
+      exec pager rescue exec '/bin/sh', '-c', pager
+    end
+
     def read_cli_options!(args)
       custom_properties = Twig::Branch.all_property_names
 
@@ -120,6 +153,7 @@ class Twig
         desc = 'Show this help content.'
         opts.on('--help', *help_description(desc)) do
           summary_lines = opts.to_s.split("\n")
+          run_pager
 
           # Filter out custom property lines
           prev_line = nil
@@ -166,23 +200,34 @@ class Twig
         end
 
         custom_properties.each do |property_name|
+          property_name_sym = property_name.to_sym
+
           opts.on("--only-#{property_name} PATTERN") do |pattern|
-            set_option(:property_only, property_name.to_sym => pattern)
+            set_option(:property_only, property_name_sym => pattern)
           end
 
           opts.on("--except-#{property_name} PATTERN") do |pattern|
-            set_option(:property_except, property_name.to_sym => pattern)
+            set_option(:property_except, property_name_sym => pattern)
           end
         end
         help_description_for_custom_property(opts, [
           ['--only-PROPERTY PATTERN',   'Only list branches with a given property'],
           ['',                          'that matches a given pattern.'],
-        ])
+        ], :trailing => '')
         help_description_for_custom_property(opts, [
           ['--except-PROPERTY PATTERN', 'Do not list branches with a given property'],
           ['',                          'that matches a given pattern.']
         ])
 
+        desc =
+          'Print branch properties in a format that can be used by other ' +
+          'tools. Currently, the only supported value is `json`.'
+        opts.on(
+          '--format FORMAT', *help_description(desc, :add_separator => true)
+        ) do |format|
+          set_option(:format, format)
+        end
+
         desc =
           'Lists all branches regardless of other filtering options. ' +
           'Useful for overriding options in ' +
@@ -197,7 +242,10 @@ class Twig
 
         help_separator(opts, 'Listing branches:')
 
-        desc = 'Set the width for the `branch` column.'
+        desc = <<-DESC
+          Set the width for the `branch` column.
+          (Default: #{Twig::DEFAULT_BRANCH_COLUMN_WIDTH})
+        DESC
         opts.on('--branch-width NUMBER', *help_description(desc)) do |width|
           set_option(:property_width, :branch => width)
         end
@@ -208,7 +256,8 @@ class Twig
           end
         end
         help_description_for_custom_property(opts, [
-          ['--PROPERTY-width NUMBER', "Set the width for a given property's column."]
+          ['--PROPERTY-width NUMBER', "Set the width for a given property's column."],
+          ['',                        "(Default: #{Twig::DEFAULT_PROPERTY_COLUMN_WIDTH})"]
         ])
 
         colors = Twig::Display::COLORS.keys.map do |value|
@@ -217,14 +266,14 @@ class Twig
         weights = Twig::Display::WEIGHTS.keys.map do |value|
           format_string(value, :weight => value)
         end.join(' and ')
-        default_color = format_string(
+        default_header_style = 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}".
+          (Default: "#{default_header_style}")
         DESC
         opts.on(
           '--header-style "STYLE"',
@@ -233,7 +282,7 @@ class Twig
           set_option(:header_style, style)
         end
 
-        desc = 'Show oldest branches first.'
+        desc = 'Show oldest branches first. (Default: false)'
         opts.on('--reverse', *help_description(desc)) do
           set_option(:reverse, true)
         end
@@ -245,6 +294,7 @@ class Twig
         desc = <<-DESC
           Set a custom GitHub API URI prefix, e.g.,
           https://github-enterprise.example.com/api/v3.
+          (Default: "#{Twig::DEFAULT_GITHUB_API_URI_PREFIX}")
         DESC
         opts.on(
           '--github-api-uri-prefix PREFIX',
@@ -256,6 +306,7 @@ class Twig
         desc = <<-DESC
           Set a custom GitHub URI prefix, e.g.,
           https://github-enterprise.example.com.
+          (Default: "#{Twig::DEFAULT_GITHUB_URI_PREFIX}")
         DESC
         opts.on(
           '--github-uri-prefix PREFIX',
@@ -287,6 +338,8 @@ class Twig
       option_parser.parse!(args)
     rescue OptionParser::InvalidOption, OptionParser::MissingArgument => exception
       abort_for_option_exception(exception)
+    ensure
+      args
     end
 
     def abort_for_option_exception(exception)
@@ -295,19 +348,22 @@ class Twig
       exit
     end
 
-    def read_cli_args!(args)
-      if args.any?
-        # Run subcommand binary, if any, and exit here
-        possible_subcommand_name = args[0]
-        command_path = Twig.run("which twig-#{possible_subcommand_name} 2>/dev/null")
-        unless command_path.empty?
-          command = ([command_path] + args[1..-1]).join(' ')
-          exec(command)
-        end
+    def exec_subcommand_if_any(args)
+      # Run subcommand binary, if any, and exit here
+      possible_subcommand_name = Twig::Subcommands::BIN_PREFIX + args[0]
+      command_path = Twig.run("which #{possible_subcommand_name} 2>/dev/null")
+      unless command_path.empty?
+        command = ([command_path] + args[1..-1]).join(' ')
+        exec(command)
       end
+    end
+
+    def read_cli_args!(args)
+      exec_subcommand_if_any(args) if args.any?
 
-      read_cli_options!(args)
+      args = read_cli_options!(args)
       branch_name = options[:branch] || current_branch_name
+      format = options.delete(:format)
       property_to_unset = options.delete(:unset_property)
 
       # Handle remaining arguments, if any
@@ -327,6 +383,9 @@ class Twig
       elsif property_to_unset
         # `$ twig --unset <key>`
         unset_branch_property_for_cli(branch_name, property_to_unset)
+      elsif format == :json
+        # `$ twig --format json`
+        puts branches_json
       else
         # `$ twig`
         puts list_branches