twig 1.5 → 1.6

data/bin/twig-gh-open-issue

@@ -1,12 +1,22 @@
 #!/usr/bin/env ruby
 
-# Usage:
+# Synopsis:
 #
-# - `twig gh-open-issue`:
-#   Opens a browser window for the GitHub issue, if any, for the current branch.
+#   twig gh-open-issue [-b|--branch <branch>]
 #
-# - `twig gh-open-issue -b <branch>`:
-#   Opens the GitHub issue, if any, for the specified branch.
+# Description:
+#
+#   Opens a browser window the GitHub issue, if any, for the current branch.
+#
+#   To customize the GitHub URI prefix (e.g., for GitHub Enterprise
+#   installations), set GitHub options in `~/.twigconfig`:
+#
+#     github-uri-prefix:     http://example-enterprise.github.com
+#     github-api-uri-prefix: http://example-enterprise.github.com
+#
+# Options:
+#
+#   `-b` or `--branch`: Opens the GitHub issue, if any, for the given branch.
 #
 # Subcommand for Twig: <http://rondevera.github.io/twig/>
 # Author: Ron DeVera <http://rondevera.com>
@@ -16,15 +26,12 @@ require 'twig'
 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')
+  twig = Twig.new(:read_options => true)
+  target_branch_name = twig.target_branch_name
+  issue_id = twig.get_branch_property(target_branch_name, 'issue')
 
   unless issue_id
-    abort %{The branch "#{branch_name}" doesn't have an "issue" property.}
+    abort %{The branch "#{target_branch_name}" doesn't have an "issue" property.}
   end
 
   gh_uri_prefix = twig.options[:github_uri_prefix]

data/bin/twig-gh-update

@@ -1,6 +1,18 @@
 #!/usr/bin/env ruby
 
-# Updates each branch with the latest issue status on GitHub.
+# Synopsis:
+#
+#   twig gh-update
+#
+# Description:
+#
+#   Updates each branch with the latest issue status on GitHub.
+#
+#   To customize the GitHub URI prefix (e.g., for GitHub Enterprise
+#   installations), set GitHub options in `~/.twigconfig`:
+#
+#     github-uri-prefix:     http://example-enterprise.github.com
+#     github-api-uri-prefix: http://example-enterprise.github.com
 #
 # Subcommand for Twig: <http://rondevera.github.io/twig/>
 # Author: Ron DeVera <http://rondevera.com>
@@ -11,9 +23,7 @@ require 'json'
 require 'net/https'
 require 'uri'
 
-twig = Twig.new
-twig.read_config_file!
-twig.read_cli_options!(ARGV)
+twig = Twig.new(:read_options => true)
 
 Twig::GithubRepo.new do |gh_repo|
   $stdout.sync = true

data/bin/twig-init

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+
+# Synopsis:
+#
+#   twig init
+#
+# Description:
+#
+#   Runs all initialization commands. This is only needed once after installing
+#   Twig, and affects all Git repositories.
+#
+# Subcommand for Twig: <http://rondevera.github.io/twig/>
+# Author: Ron DeVera <http://rondevera.com>
+
+exec('twig init-completion')

data/bin/twig-init-completion

@@ -1,7 +1,19 @@
 #!/usr/bin/env ruby
 
-# Initializes tab completion for Twig. To use this, run
-# `twig init-completion` and follow the instructions.
+# Synopsis:
+#
+#   twig init-completion [--force]
+#
+# Description:
+#
+#   Initializes tab completion for Twig. Instead of running this directly,
+#   run `twig init` to run all setup tasks.
+#
+# Options:
+#
+#   `--force`: By default, `twig init-completion` preserves the existing tab
+#   completion script, if any. If this option is used, the command will
+#   overwrite any existing tab completion script.
 #
 # Subcommand for Twig: <http://rondevera.github.io/twig/>
 # Author: Ron DeVera <http://rondevera.com>

data/bin/twig-init-completion-bash

@@ -1,7 +1,14 @@
 #!/usr/bin/env ruby
 
-# Initializes bash tab completion for Twig. To use this, run
-# `twig init-completion` and follow the instructions.
+# Synopsis:
+#
+#   twig init-completion-bash
+#
+# Description:
+#
+#   Initializes bash tab completion for Twig. Instead of running this directly,
+#   run `twig init` to run all setup tasks for the current shell. Uses all
+#   options available for `twig init-completion`.
 #
 # Subcommand for Twig: <http://rondevera.github.io/twig/>
 # Author: Ron DeVera <http://rondevera.com>
@@ -84,7 +91,8 @@ full_script_path = File.expand_path(script_path)
 script_exists    = File.exists?(full_script_path)
 
 if script_exists && !force
-  puts "The file `#{script_path}` already exists."
+  twig = Twig.new
+  puts twig.format_string("The file `#{script_path}` already exists.", :color => :red)
   puts "To overwrite it, run `twig init-completion --force`."
 else
   File.open(full_script_path, 'w') do |file|

data/bin/twig-rebase

@@ -1,24 +1,27 @@
 #!/usr/bin/env ruby
 
-# Summary:
+# Synopsis:
 #
-#   `twig rebase [<branch>] [<options>]`
+#   twig rebase [<branch>] [<options>]
 #
-# Usage:
+# Description:
 #
-# - `twig rebase`:
 #   Rebases the current branch onto the branch in its `diff-branch` property.
+#   All options are passed through to `git-rebase`.
 #
-# - `twig rebase <options>`:
-#   Rebases the current branch onto its `diff-branch`, and passes options
-#   through to `git-rebase`, e.g., `twig rebase -i`.
+# Examples:
 #
-# - `twig rebase <branch>`:
-#   Rebases the given branch onto its `diff-branch`.
+#   Rebase the current branch onto its `diff-branch` interactively:
 #
-# - `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`.
+#     twig rebase -i
+#
+#   Rebase the given branch onto its `diff-branch`:
+#
+#     twig rebase my_branch
+#
+#   Rebase the given branch onto its `diff-branch` interactively:
+#
+#     twig rebase my_branch -i
 #
 # Subcommand for Twig: <http://rondevera.github.io/twig/>
 # Author: Ron DeVera <http://rondevera.com>

data/lib/twig.rb

@@ -1,4 +1,15 @@
-Dir[File.join(File.dirname(__FILE__), 'twig', '*.rb')].each { |file| require file }
+$LOAD_PATH.unshift(File.dirname(__FILE__)) # For gem development
+require 'twig/branch'
+require 'twig/cli'
+require 'twig/commit_time'
+require 'twig/display'
+require 'twig/github'
+require 'twig/homepage'
+require 'twig/options'
+require 'twig/subcommands'
+require 'twig/system'
+require 'twig/util'
+require 'twig/version'
 require 'time'
 
 # The main class.
@@ -26,37 +37,32 @@ class Twig
     $?.success?
   end
 
-  def initialize
+  def initialize(options = {})
     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)
+
+    if options[:read_options]
+      read_config_file!
+      read_cli_options!(ARGV)
+    end
   end
 
   def current_branch_name
+    # Returns the name of the branch that is currently checked out in Git.
     @_current_branch_name ||= Twig.run('git rev-parse --abbrev-ref HEAD')
   end
 
-  def all_branches
-    @_all_branches ||= begin
-      branch_tuples = Twig.
-        run(%{git for-each-ref #{ REF_PREFIX } --format="#{ REF_FORMAT }"}).
-        split("\n")
-
-      branch_tuples.inject([]) do |result, branch_tuple|
-        ref, time_string, time_ago = branch_tuple.split(REF_FORMAT_SEPARATOR)
-        time        = Time.parse(time_string)
-        commit_time = Twig::CommitTime.new(time, time_ago)
-        branch      = Branch.new(ref, :last_commit_time => commit_time)
-        result << branch
-      end
-    end
+  def target_branch_name
+    # Returns the name of the branch to work on, e.g., for setting a property.
+    options[:branch] || current_branch_name
   end
 
   def branches
-    branches = all_branches
+    branches = Twig::Branch.all_branches
     now = Time.now
     max_days_old = options[:max_days_old]
     max_seconds_old = max_days_old * 86400 if max_days_old
@@ -99,8 +105,22 @@ class Twig
     branches
   end
 
-  def all_branch_names
-    all_branches.map { |branch| branch.name }
+  def property_names
+    @_property_names ||= begin
+      property_names = Twig::Branch.all_property_names
+      only_name      = options[:property_only_name]
+      except_name    = options[:property_except_name]
+
+      if only_name
+        property_names = property_names.select { |name| name =~ only_name }
+      end
+
+      if except_name
+        property_names = property_names.select { |name| name !~ except_name }
+      end
+
+      property_names
+    end
   end
 
 
@@ -109,7 +129,7 @@ class Twig
 
   def list_branches
     if branches.empty?
-      if all_branches.any?
+      if Twig::Branch.all_branches.any?
         return 'There are no branches matching your selected options.'
       else
         return 'This repository has no branches.'

data/lib/twig/branch.rb

@@ -5,7 +5,7 @@ class Twig
 
     EMPTY_PROPERTY_NAME_ERROR      = 'Branch property names cannot be empty strings.'
     PROPERTY_NAME_FROM_GIT_CONFIG  = /^branch\.[^.]+\.([^=]+)=.*$/
-    RESERVED_BRANCH_PROPERTY_NAMES = %w[branch merge rebase remote]
+    RESERVED_BRANCH_PROPERTY_NAMES = %w[branch merge property rebase remote]
 
     class EmptyPropertyNameError < ArgumentError
       def initialize(message = nil)
@@ -17,14 +17,34 @@ class Twig
 
     attr_accessor :name, :last_commit_time
 
+    def self.all_branches
+      @_all_branches ||= begin
+        branch_tuples = Twig.
+          run(%{git for-each-ref #{ REF_PREFIX } --format="#{ REF_FORMAT }"}).
+          split("\n")
+
+        branch_tuples.inject([]) do |result, branch_tuple|
+          name, time_string, time_ago = branch_tuple.split(REF_FORMAT_SEPARATOR)
+          time        = Time.parse(time_string)
+          commit_time = Twig::CommitTime.new(time, time_ago)
+          branch      = Branch.new(name, :last_commit_time => commit_time)
+          result << branch
+        end
+      end
+    end
+
+    def self.all_branch_names
+      @_all_branch_names ||= self.all_branches.map { |branch| branch.name }
+    end
+
     def self.all_property_names
       @_all_property_names ||= begin
         config_lines = Twig.run('git config --list').split("\n")
 
         properties = config_lines.map do |line|
-          # Split by rightmost `=`, allowing branch names to contain `=`:
-          key = value = nil
-          line.match(/(.+)=(.+)/).tap { |md| key, value = md[1..2] if md }
+          # Split by rightmost `=`, allowing branch names to contain `=`
+          match_data = line.match(/(.+)=(.+)/)
+          key, value = match_data[1..2] if match_data
           next unless key
 
           key_parts = key.split('.')
@@ -35,6 +55,10 @@ class Twig
       end
     end
 
+    def self.validate_property_name(property_name)
+      raise EmptyPropertyNameError if property_name.empty?
+    end
+
     def initialize(name, attrs = {})
       self.name = name
       raise ArgumentError, '`name` is required' if name.empty?
@@ -44,13 +68,11 @@ class Twig
 
     def to_s ; name ; end
 
-    def to_hash
-      all_property_names = Twig::Branch.all_property_names
-
+    def to_hash(property_names)
       {
         'name' => name,
         'last-commit-time' => last_commit_time.iso8601,
-        'properties' => get_properties(all_property_names)
+        'properties' => get_properties(property_names)
       }
     end
 
@@ -61,7 +83,7 @@ class Twig
     def escaped_property_names(property_names)
       property_names.map do |property_name|
         property_name = sanitize_property(property_name)
-        raise EmptyPropertyNameError if property_name.empty?
+        Branch.validate_property_name(property_name)
         Regexp.escape(property_name)
       end
     end
@@ -103,10 +125,9 @@ class Twig
     def set_property(property_name, value)
       property_name = sanitize_property(property_name)
       value = value.to_s.strip
+      Branch.validate_property_name(property_name)
 
-      if property_name.empty?
-        raise EmptyPropertyNameError
-      elsif RESERVED_BRANCH_PROPERTY_NAMES.include?(property_name)
+      if RESERVED_BRANCH_PROPERTY_NAMES.include?(property_name)
         raise ArgumentError,
           %{Can't modify the reserved property "#{property_name}".}
       elsif value.empty?
@@ -126,7 +147,7 @@ class Twig
 
     def unset_property(property_name)
       property_name = sanitize_property(property_name)
-      raise EmptyPropertyNameError if property_name.empty?
+      Branch.validate_property_name(property_name)
 
       value = get_property(property_name)
 

data/lib/twig/cli.rb

@@ -4,13 +4,33 @@ require 'rbconfig'
 class Twig
   module Cli
 
+    def self.prompt_with_choices(prompt, choices)
+      # Prints the given string `prompt` and the array `choices` numbered, and
+      # prompts the user to enter a number. Returns the matching value, or nil
+      # if the user input is invalid.
+
+      if choices.size < 2
+        raise ArgumentError, 'At least two choices required'
+      end
+
+      puts prompt
+      choices.each_with_index do |choice, index|
+        puts "#{sprintf('%3s', index + 1)}. #{choice}"
+      end
+      print '> '
+
+      input = $stdin.gets.to_i
+      choices[input - 1]
+    end
+
     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.
+        Twig is your personal Git branch assistant. It's a command-line tool for
+        listing your most recent branches, and for remembering branch details
+        for you, like issue tracker ids and todos. It also supports subcommands,
+        like automatically fetching statuses from your issue tracking system.
       })
 
       intro = <<-BANNER.gsub(/^[ ]+/, '')
@@ -78,11 +98,13 @@ class Twig
       is_custom_property_except = (
         line.include?('--except-') &&
         !line.include?('--except-branch') &&
+        !line.include?('--except-property') &&
         !line.include?('--except-PROPERTY')
       )
       is_custom_property_only = (
         line.include?('--only-') &&
         !line.include?('--only-branch') &&
+        !line.include?('--only-property') &&
         !line.include?('--only-PROPERTY')
       )
       is_custom_property_width = (
@@ -212,7 +234,7 @@ class Twig
         end
         help_description_for_custom_property(opts, [
           ['--only-PROPERTY PATTERN',   'Only list branches with a given property'],
-          ['',                          'that matches a given pattern.'],
+          ['',                          'that matches a given pattern.']
         ], :trailing => '')
         help_description_for_custom_property(opts, [
           ['--except-PROPERTY PATTERN', 'Do not list branches with a given property'],
@@ -260,6 +282,28 @@ class Twig
           ['',                        "(Default: #{Twig::DEFAULT_PROPERTY_COLUMN_WIDTH})"]
         ])
 
+        desc = <<-DESC
+          Only include properties where the property name matches the given
+          regular expression.
+        DESC
+        opts.on(
+          '--only-property PATTERN',
+          *help_description(desc, :add_separator => true)
+        ) do |pattern|
+          set_option(:property_only_name, pattern)
+        end
+
+        desc = <<-DESC
+          Exclude properties where the property name matches the given regular
+          expression.
+        DESC
+        opts.on(
+          '--except-property PATTERN',
+          *help_description(desc, :add_separator => true)
+        ) do |pattern|
+          set_option(:property_except_name, pattern)
+        end
+
         colors = Twig::Display::COLORS.keys.map do |value|
           format_string(value, :color => value)
         end.join(', ')
@@ -326,7 +370,7 @@ class Twig
           '      except-branch: staging',
           '      header-style:  green bold',
           '      max-days-old:  30',
-          '      reverse:       true',
+          '      reverse:       true'
         ].join("\n"), :trailing => '')
 
         help_separator(opts, help_paragraph(%{
@@ -343,9 +387,8 @@ class Twig
     end
 
     def abort_for_option_exception(exception)
-      puts exception.message
-      puts 'For a list of options, run `twig --help`.'
-      exit
+      puts exception.message + "\nFor a list of options, run `twig --help`."
+      exit 1
     end
 
     def exec_subcommand_if_any(args)
@@ -362,7 +405,7 @@ class Twig
       exec_subcommand_if_any(args) if args.any?
 
       args = read_cli_options!(args)
-      branch_name = options[:branch] || current_branch_name
+      branch_name = target_branch_name
       format = options.delete(:format)
       property_to_unset = options.delete(:unset_property)