twig 1.6 → 1.7

data/lib/twig/branch.rb

@@ -2,14 +2,14 @@ class Twig
 
   # Represents a Git branch.
   class Branch
-
-    EMPTY_PROPERTY_NAME_ERROR      = 'Branch property names cannot be empty strings.'
+    PARENT_PROPERTY = 'diff-branch'
     PROPERTY_NAME_FROM_GIT_CONFIG  = /^branch\.[^.]+\.([^=]+)=.*$/
     RESERVED_BRANCH_PROPERTY_NAMES = %w[branch merge property rebase remote]
 
     class EmptyPropertyNameError < ArgumentError
+      DEFAULT_MESSAGE = 'Branch property names cannot be empty strings.'
       def initialize(message = nil)
-        message ||= EMPTY_PROPERTY_NAME_ERROR
+        message ||= DEFAULT_MESSAGE
         super
       end
     end
@@ -24,9 +24,9 @@ class Twig
           split("\n")
 
         branch_tuples.inject([]) do |result, branch_tuple|
-          name, time_string, time_ago = branch_tuple.split(REF_FORMAT_SEPARATOR)
+          name, time_string = branch_tuple.split(REF_FORMAT_SEPARATOR)
           time        = Time.parse(time_string)
-          commit_time = Twig::CommitTime.new(time, time_ago)
+          commit_time = Twig::CommitTime.new(time)
           branch      = Branch.new(name, :last_commit_time => commit_time)
           result << branch
         end
@@ -34,7 +34,7 @@ class Twig
     end
 
     def self.all_branch_names
-      @_all_branch_names ||= self.all_branches.map { |branch| branch.name }
+      @_all_branch_names ||= all_branches.map { |branch| branch.name }
     end
 
     def self.all_property_names
@@ -59,6 +59,10 @@ class Twig
       raise EmptyPropertyNameError if property_name.empty?
     end
 
+    def self.shellescape_property_value(property_value)
+      Shellwords.escape(property_value).gsub('\\ ', ' ')
+    end
+
     def initialize(name, attrs = {})
       self.name = name
       raise ArgumentError, '`name` is required' if name.empty?
@@ -76,6 +80,10 @@ class Twig
       }
     end
 
+    def parent_name
+      get_property(PARENT_PROPERTY)
+    end
+
     def sanitize_property(property_name)
       property_name.gsub(/[ _]+/, '')
     end
@@ -92,7 +100,7 @@ class Twig
       return {} if property_names.empty?
 
       property_names_regexp = escaped_property_names(property_names).join('|')
-      git_config_regexp     = "branch\.#{name}\.(#{ property_names_regexp })$"
+      git_config_regexp     = "branch\.#{Shellwords.escape(name)}\.(#{ property_names_regexp })$"
       cmd = %{git config --get-regexp "#{git_config_regexp}"}
 
       git_result = Twig.run(cmd) || ''
@@ -114,7 +122,6 @@ class Twig
           properties.merge(property_name => property_value)
         end
       end
-
     end
 
     def get_property(property_name)
@@ -134,8 +141,9 @@ class Twig
         raise ArgumentError,
           %{Can't set a branch property to an empty string.}
       else
-        git_config = "branch.#{name}.#{property_name}"
-        Twig.run(%{git config #{git_config} "#{value}"})
+        git_config = "branch.#{name.shellescape}.#{property_name}"
+        escaped_value = Branch.shellescape_property_value(value)
+        Twig.run(%{git config #{git_config} "#{escaped_value}"})
         result_body = %{property "#{property_name}" as "#{value}" for branch "#{name}".}
         if $?.success?
           "Saved #{result_body}"
@@ -152,7 +160,7 @@ class Twig
       value = get_property(property_name)
 
       if value
-        git_config = "branch.#{name}.#{property_name}"
+        git_config = "branch.#{name.shellescape}.#{property_name}"
         Twig.run(%{git config --unset #{git_config}})
         %{Removed property "#{property_name}" for branch "#{name}".}
       else
@@ -160,6 +168,5 @@ class Twig
           %{The branch "#{name}" does not have the property "#{property_name}".}
       end
     end
-
   end
 end

data/lib/twig/cli.rb

@@ -1,17 +1,16 @@
 require 'optparse'
 require 'rbconfig'
+require File.expand_path(File.join(File.dirname(__FILE__), 'cli', 'help'))
 
 class Twig
+  # Handles raw input from the command-line interface.
   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
+      raise ArgumentError, 'At least two choices required' if choices.size < 2
 
       puts prompt
       choices.each_with_index do |choice, index|
@@ -23,106 +22,11 @@ class Twig
       choices[input - 1]
     end
 
-    def help_intro
-      version_string = "Twig v#{Twig::VERSION}"
-
-      intro = help_paragraph(%{
-        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(/^[ ]+/, '')
-
-        #{version_string}
-        #{'-' * version_string.size}
-
-        #{intro}
-
-        #{Twig::HOMEPAGE}
-      BANNER
-
-      intro + ' ' # Force extra blank line
-    end
-
-    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
-      words = text.gsub(/\n?\s+/, ' ').strip.split(' ')
-      lines = []
-
-      # Split words into lines
-      while words.any?
-        current_word      = words.shift
-        current_word_size = unformat_string(current_word).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)
-          last_line << ' ' << current_word
-        elsif current_word_size >= width
-          lines << current_word[0...width]
-          words.unshift(current_word[width..-1])
-        else
-          lines << current_word
-        end
-      end
-
-      lines << ' ' if options[:add_separator]
-      lines
-    end
-
-    def help_description_for_custom_property(option_parser, desc_lines, options = {})
-      options[:trailing] ||= "\n"
-      indent = '      '
-      left_column_width = 29
-
-      help_desc = desc_lines.inject('') do |desc, (left_column, right_column)|
-        desc + indent +
-        sprintf("%-#{left_column_width}s", left_column) + right_column + "\n"
-      end
-
-      help_separator(option_parser, help_desc, :trailing => options[:trailing])
-    end
-
-    def help_paragraph(text)
-      help_description(text, :width => 80).join("\n")
-    end
-
-    def help_line_for_custom_property?(line)
-      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 = (
-        line =~ /--.+-width/ &&
-        !line.include?('--branch-width') &&
-        !line.include?('--PROPERTY-width')
-      )
-
-      is_custom_property_except ||
-      is_custom_property_only ||
-      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?
+      return if Twig::System.windows? || !$stdout.tty? || !Kernel.respond_to?(:fork)
 
       read_io, write_io = IO.pipe
 
@@ -152,28 +56,28 @@ class Twig
       custom_properties = Twig::Branch.all_property_names
 
       option_parser = OptionParser.new do |opts|
-        opts.banner         = help_intro
+        opts.banner         = Help.intro
         opts.summary_indent = ' ' * 2
         opts.summary_width  = 32
 
+        ###
 
-
-        help_separator(opts, 'Common options:')
+        Help.header(opts, 'Common options')
 
         desc = 'Use a specific branch.'
         opts.on(
-          '-b BRANCH', '--branch BRANCH', *help_description(desc)
+          '-b BRANCH', '--branch BRANCH', *Help.description(desc)
         ) do |branch|
           set_option(:branch, branch)
         end
 
         desc = 'Unset a branch property.'
-        opts.on('--unset PROPERTY', *help_description(desc)) do |property_name|
+        opts.on('--unset PROPERTY', *Help.description(desc)) do |property_name|
           set_option(:unset_property, property_name)
         end
 
         desc = 'Show this help content.'
-        opts.on('--help', *help_description(desc)) do
+        opts.on('--help', *Help.description(desc)) do
           summary_lines = opts.to_s.split("\n")
           run_pager
 
@@ -183,7 +87,7 @@ class Twig
             # Squash successive blank lines
             next if line == "\n" && prev_line == "\n"
 
-            unless help_line_for_custom_property?(line)
+            unless Help.line_for_custom_property?(line)
               puts line
               prev_line = line
             end
@@ -193,17 +97,18 @@ class Twig
         end
 
         desc = 'Show Twig version.'
-        opts.on('--version', *help_description(desc)) do
-          puts Twig::VERSION; exit
+        opts.on('--version', *Help.description(desc)) do
+          puts Twig::VERSION
+          exit
         end
 
+        ###
 
-
-        help_separator(opts, 'Filtering branches:')
+        Help.header(opts, 'Filtering branches')
 
         desc = 'Only list branches below a given age.'
         opts.on(
-          '--max-days-old AGE', *help_description(desc, :add_separator => true)
+          '--max-days-old AGE', *Help.description(desc, :add_blank_line => true)
         ) do |age|
           set_option(:max_days_old, age)
         end
@@ -211,13 +116,13 @@ class Twig
         desc = 'Only list branches whose name matches a given pattern.'
         opts.on(
           '--only-branch PATTERN',
-          *help_description(desc, :add_separator => true)
+          *Help.description(desc, :add_blank_line => true)
         ) do |pattern|
           set_option(:property_only, :branch => pattern)
         end
 
         desc = 'Do not list branches whose name matches a given pattern.'
-        opts.on('--except-branch PATTERN', *help_description(desc)) do |pattern|
+        opts.on('--except-branch PATTERN', *Help.description(desc)) do |pattern|
           set_option(:property_except, :branch => pattern)
         end
 
@@ -232,43 +137,43 @@ class Twig
             set_option(:property_except, property_name_sym => pattern)
           end
         end
-        help_description_for_custom_property(opts, [
+        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, [
+        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 ' +
+          '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)
+          '--format FORMAT', *Help.description(desc, :add_blank_line => true)
         ) do |format|
           set_option(:format, format)
         end
 
         desc =
-          'Lists all branches regardless of other filtering options. ' +
+          'Lists all branches regardless of other filtering options. ' \
           'Useful for overriding options in ' +
           File.basename(Twig::Options::CONFIG_PATH) + '.'
-        opts.on('--all', *help_description(desc)) do |pattern|
+        opts.on('--all', *Help.description(desc)) do |pattern|
           unset_option(:max_days_old)
           unset_option(:property_except)
           unset_option(:property_only)
         end
 
+        ###
 
-
-        help_separator(opts, 'Listing branches:')
+        Help.header(opts, 'Listing branches')
 
         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|
+        opts.on('--branch-width NUMBER', *Help.description(desc)) do |width|
           set_option(:property_width, :branch => width)
         end
 
@@ -277,7 +182,7 @@ class Twig
             set_option(:property_width, property_name.to_sym => width)
           end
         end
-        help_description_for_custom_property(opts, [
+        Help.description_for_custom_property(opts, [
           ['--PROPERTY-width NUMBER', "Set the width for a given property's column."],
           ['',                        "(Default: #{Twig::DEFAULT_PROPERTY_COLUMN_WIDTH})"]
         ])
@@ -288,7 +193,7 @@ class Twig
         DESC
         opts.on(
           '--only-property PATTERN',
-          *help_description(desc, :add_separator => true)
+          *Help.description(desc, :add_blank_line => true)
         ) do |pattern|
           set_option(:property_only_name, pattern)
         end
@@ -299,17 +204,17 @@ class Twig
         DESC
         opts.on(
           '--except-property PATTERN',
-          *help_description(desc, :add_separator => true)
+          *Help.description(desc, :add_blank_line => 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(', ')
-        weights = Twig::Display::WEIGHTS.keys.map do |value|
-          format_string(value, :weight => value)
-        end.join(' and ')
+        colors = Twig::Display::COLORS.keys.
+          map { |value| format_string(value, :color => value) }.
+          join(', ')
+        weights = Twig::Display::WEIGHTS.keys.
+          map { |value| format_string(value, :weight => value) }.
+          join(' and ')
         default_header_style = format_string(
           Twig::DEFAULT_HEADER_COLOR.to_s,
           :color => Twig::DEFAULT_HEADER_COLOR
@@ -321,19 +226,19 @@ class Twig
         DESC
         opts.on(
           '--header-style "STYLE"',
-          *help_description(desc, :add_separator => true)
+          *Help.description(desc, :add_blank_line => true)
         ) do |style|
           set_option(:header_style, style)
         end
 
         desc = 'Show oldest branches first. (Default: false)'
-        opts.on('--reverse', *help_description(desc)) do
+        opts.on('--reverse', *Help.description(desc)) do
           set_option(:reverse, true)
         end
 
+        ###
 
-
-        help_separator(opts, 'GitHub integration:')
+        Help.header(opts, 'GitHub integration')
 
         desc = <<-DESC
           Set a custom GitHub API URI prefix, e.g.,
@@ -342,7 +247,7 @@ class Twig
         DESC
         opts.on(
           '--github-api-uri-prefix PREFIX',
-          *help_description(desc, :add_separator => true)
+          *Help.description(desc, :add_blank_line => true)
         ) do |prefix|
           set_option(:github_api_uri_prefix, prefix)
         end
@@ -352,31 +257,78 @@ class Twig
           https://github-enterprise.example.com.
           (Default: "#{Twig::DEFAULT_GITHUB_URI_PREFIX}")
         DESC
-        opts.on(
-          '--github-uri-prefix PREFIX',
-          *help_description(desc, :add_separator => true)
-        ) do |prefix|
+        opts.on('--github-uri-prefix PREFIX', *Help.description(desc)) do |prefix|
           set_option(:github_uri_prefix, prefix)
         end
 
+        ###
+
+        Help.header(opts, 'Config files and tab completion', :trailing => '')
 
+        Help.print_paragraph(opts, %{
+          Twig can automatically set up a config file for you, where you can put
+          your most frequently used options for filtering and listing branches.
+          To get started, run `twig init` and follow the instructions. This does
+          two things:
+        })
 
-        help_separator(opts, help_paragraph(%{
-          You can put your most frequently used options for filtering and
-          listing branches into #{Twig::Options::CONFIG_PATH}. For example:
-        }), :trailing => '')
+        Help.print_paragraph(opts, %{
+          * Creates #{Twig::Options::CONFIG_PATH}, where you can put your
+            favorite options, e.g.:
+        })
 
-        help_separator(opts, [
+        Help.print_section(opts, [
           '      except-branch: staging',
           '      header-style:  green bold',
           '      max-days-old:  30',
           '      reverse:       true'
+        ].join("\n"))
+
+        Help.print_paragraph(opts, %{
+          * Enables tab completion for Twig subcommands and branch names, e.g.:
+        })
+
+        Help.print_section(opts, [
+          '      `twig cre<tab>` -> `twig create-branch`',
+          '      `twig status -b my-br<tab>` -> `twig status -b my-branch`'
         ].join("\n"), :trailing => '')
 
-        help_separator(opts, help_paragraph(%{
-          To enable tab completion for Twig, run `twig init-completion` and
-          follow the instructions.
-        }))
+        ###
+
+        Help.header(opts, 'Subcommands', :trailing => '')
+
+        Help.print_paragraph(opts, "Twig comes with these subcommands:", :trailing => "\n\n")
+
+        Help.subcommand_descriptions.each do |desc|
+          Help.print_line(opts, desc)
+        end
+
+        Help.subheader(opts, 'Writing a subcommand', :trailing => '')
+
+        Help.print_paragraph(opts, %{
+          You can write any Twig subcommand that fits your own Git workflow. To
+          write a Twig subcommand:
+        })
+
+        Help.print_section(opts, [
+          '1.  Write a script; any language will do. (If you want to take',
+          '    advantage of Twig\'s option parsing and branch processing, you\'ll',
+          '    need Ruby. See `twig-checkout-parent` for an example.)'
+        ].join("\n"))
+
+        Help.print_section(opts, [
+          '2.  Save it with the `twig-` prefix in your `$PATH`,',
+          '    e.g., `~/bin/twig-my-subcommand`.'
+        ].join("\n"))
+
+        Help.print_section(opts, [
+          '3.  Make it executable: `chmod ugo+x ~/bin/twig-my-subcommand`'
+        ].join("\n"))
+
+        Help.print_section(opts, [
+          '4.  Run your subcommand: `twig my-subcommand` (with a *space* after',
+          '    `twig`'
+        ].join("\n"))
       end
 
       option_parser.parse!(args)
@@ -387,22 +339,12 @@ class Twig
     end
 
     def abort_for_option_exception(exception)
-      puts exception.message + "\nFor a list of options, run `twig --help`."
+      puts exception.message + "\nFor a list of options, run `twig help`."
       exit 1
     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?
+      Twig::Subcommands.exec_subcommand_if_any(args) if args.any?
 
       args = read_cli_options!(args)
       branch_name = target_branch_name
@@ -436,34 +378,27 @@ class Twig
     end
 
     def get_branch_property_for_cli(branch_name, property_name)
-      begin
-        value = get_branch_property(branch_name, property_name)
-        if value
-          puts value
-        else
-          raise Twig::Branch::MissingPropertyError,
-            %{The branch "#{branch_name}" does not have the property "#{property_name}".}
-        end
-      rescue ArgumentError, Twig::Branch::MissingPropertyError => exception
-        abort exception.message
+      value = get_branch_property(branch_name, property_name)
+      if value
+        puts value
+      else
+        raise Twig::Branch::MissingPropertyError,
+          %{The branch "#{branch_name}" does not have the property "#{property_name}".}
       end
+    rescue ArgumentError, Twig::Branch::MissingPropertyError => exception
+      abort exception.message
     end
 
     def set_branch_property_for_cli(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
+      puts set_branch_property(branch_name, property_name, property_value)
+    rescue ArgumentError, RuntimeError => exception
+      abort exception.message
     end
 
     def unset_branch_property_for_cli(branch_name, property_name)
-      begin
-        puts unset_branch_property(branch_name, property_name)
-      rescue ArgumentError, Twig::Branch::MissingPropertyError => exception
-        abort exception.message
-      end
+      puts unset_branch_property(branch_name, property_name)
+    rescue ArgumentError, Twig::Branch::MissingPropertyError => exception
+      abort exception.message
     end
-
   end
 end