git_reflow 0.8.10 → 0.9.4

data/lib/git_reflow/git_server/git_hub.rb

@@ -84,56 +84,69 @@ module GitReflow
       end
 
       def authenticate(options = {silent: false})
+        if !options[:user].to_s.empty?
+          self.class.user = options[:user]
+        elsif self.class.user.empty?
+          self.class.user = ask("Please enter your GitHub username: ")
+        end
+
         if connection and self.class.oauth_token.length > 0
-          unless options[:silent]
-            GitReflow.say "Your GitHub account was already setup with: "
-            GitReflow.say "\tUser Name: #{self.class.user}"
-            GitReflow.say "\tEndpoint: #{self.class.api_endpoint}"
-          end
-        else
           begin
-            gh_user     = options[:user] || ask("Please enter your GitHub username: ")
-            gh_password = options[:password] || ask("Please enter your GitHub password (we do NOT store this): ") { |q| q.echo = false }
-
-            @connection = ::Github.new do |config|
-              config.basic_auth = "#{gh_user}:#{gh_password}"
-              config.endpoint   = GitServer::GitHub.api_endpoint
-              config.site       = GitServer::GitHub.site_url
-              config.adapter    = :net_http
+            connection.users.get
+            unless options[:silent]
+              GitReflow.say "Your GitHub account was already setup with: "
+              GitReflow.say "\tUser Name: #{self.class.user}"
+              GitReflow.say "\tEndpoint: #{self.class.api_endpoint}"
             end
+            return connection
+          rescue ::Github::Error::Unauthorized => e
+            GitReflow.logger.debug "[GitHub Error] Current oauth-token is invalid or expired..."
+          end
+        end
 
-            @connection.connection_options = {headers: {"X-GitHub-OTP" => options[:two_factor_auth_code]}} if options[:two_factor_auth_code]
+        begin
+          gh_password = options[:password] || ask("Please enter your GitHub password (we do NOT store this): ") { |q| q.echo = false }
 
-            previous_authorizations = @connection.oauth.all.select {|auth| auth.note == "git-reflow (#{run('hostname', loud: false).strip})" }
-            if previous_authorizations.any?
-              authorization = previous_authorizations.last
-              GitReflow.say "You have previously setup git-reflow on this machine, but we can no longer find the stored token.", :error
-              GitReflow.say "Please visit https://github.com/settings/tokens and delete the token for: git-reflow (#{run('hostname', loud: false).strip})", :notice
-              raise "Setup could not be completed."
-            else
-              authorization = @connection.oauth.create scopes: ['repo'], note: "git-reflow (#{run('hostname', loud: false).strip})"
-            end
+          @connection = ::Github.new do |config|
+            config.basic_auth = "#{self.class.user}:#{gh_password}"
+            config.endpoint   = GitServer::GitHub.api_endpoint
+            config.site       = GitServer::GitHub.site_url
+            config.adapter    = :net_http
+          end
 
-            self.class.oauth_token = authorization.token
+          @connection.connection_options = {headers: {"X-GitHub-OTP" => options[:two_factor_auth_code]}} if options[:two_factor_auth_code]
 
-          rescue ::Github::Error::Unauthorized => e
-            if e.inspect.to_s.include?('two-factor')
-              begin
-                # dummy request to trigger a 2FA SMS since a HTTP GET won't do it
-                @connection.oauth.create scopes: ['repo'], note: "thank Github for not making this straightforward"
-              rescue ::Github::Error::Unauthorized
-              ensure
-                two_factor_code = ask("Please enter your two-factor authentication code: ")
-                self.authenticate options.merge({user: gh_user, password: gh_password, two_factor_auth_code: two_factor_code})
-              end
-            else
-              GitReflow.say "Github Authentication Error: #{e.inspect}", :error
+          previous_authorizations = @connection.oauth.all.select {|auth| auth.note == "git-reflow (#{run('hostname', loud: false).strip})" }
+          if previous_authorizations.any?
+            authorization = previous_authorizations.last
+            GitReflow.say "You have previously setup git-reflow on this machine, but we can no longer find the stored token.", :error
+            GitReflow.say "Please visit https://github.com/settings/tokens and delete the token for: git-reflow (#{run('hostname', loud: false).strip})", :notice
+            raise "Setup could not be completed."
+          else
+            authorization = @connection.oauth.create scopes: ['repo'], note: "git-reflow (#{run('hostname', loud: false).strip})"
+          end
+
+          self.class.oauth_token = authorization.token
+
+        rescue ::Github::Error::Unauthorized => e
+          if e.inspect.to_s.include?('two-factor')
+            begin
+              # dummy request to trigger a 2FA SMS since a HTTP GET won't do it
+              @connection.oauth.create scopes: ['repo'], note: "thank Github for not making this straightforward"
+            rescue ::Github::Error::Unauthorized
+            ensure
+              two_factor_code = ask("Please enter your two-factor authentication code: ")
+              self.authenticate options.merge({user: self.class.user, password: gh_password, two_factor_auth_code: two_factor_code})
             end
-          rescue StandardError => e
-            raise "We were unable to authenticate with Github."
           else
-            GitReflow.say "Your GitHub account was successfully setup!", :success
+            GitReflow.say "Github Authentication Error: #{e.inspect}", :error
+            raise "Setup could not be completed."
           end
+        rescue StandardError => e
+          raise "We were unable to authenticate with Github."
+        else
+          GitReflow.say "Your GitHub account was successfully setup!", :success
+
         end
 
         @connection

data/lib/git_reflow/git_server/git_hub/pull_request.rb

@@ -38,7 +38,7 @@ module GitReflow
 
         def commit_author
           begin
-            username, branch = base.label.split(':')
+            username, _  = base.label.split(':')
             first_commit = GitReflow.git_server.connection.pull_requests.commits(username, GitReflow.git_server.class.remote_repo_name, number.to_s).first
             "#{first_commit.commit.author.name} <#{first_commit.commit.author.email}>".strip
           rescue Github::Error::NotFound
@@ -47,7 +47,7 @@ module GitReflow
         end
 
         def reviewers
-          (comment_authors + pull_request_reviews.map(&:user).map(&:login)).uniq
+          (comment_authors + pull_request_reviews.map(&:user).map(&:login)).uniq - [user.login]
         end
 
         def approvals
@@ -65,7 +65,7 @@ module GitReflow
           comments        = GitReflow.git_server.connection.issues.comments.all        GitReflow.remote_user, GitReflow.remote_repo_name, number: self.number
           review_comments = GitReflow.git_server.connection.pull_requests.comments.all GitReflow.remote_user, GitReflow.remote_repo_name, number: self.number
 
-          review_comments.to_a + comments.to_a
+          (review_comments.to_a + comments.to_a).select { |c| c.user.login != user.login }
         end
 
         def last_comment
@@ -80,7 +80,10 @@ module GitReflow
           if self.class.minimum_approvals.to_i == 0
             super
           else
-            approvals.size >= self.class.minimum_approvals.to_i and !last_comment.match(self.class.approval_regex).nil?
+            approvals.size >= self.class.minimum_approvals.to_i and (
+              last_comment.empty? ||
+              !last_comment.match(self.class.approval_regex).nil?
+            )
           end
         end
 
@@ -93,20 +96,22 @@ module GitReflow
             if deliver?
               GitReflow.say "Merging pull request ##{self.number}: '#{self.title}', from '#{self.feature_branch_name}' into '#{self.base_branch_name}'", :notice
 
+              merge_method       = options[:merge_method] || GitReflow::Config.get("reflow.merge-method")
+              merge_method       = "squash" if "#{merge_method}".length < 1
+              merge_message_file = GitReflow.merge_message_path(merge_method: merge_method)
+
               unless options[:title] || options[:message]
                 # prompts user for commit_title and commit_message
-                squash_merge_message_file = "#{GitReflow.git_root_dir}/.git/SQUASH_MSG"
-
-                File.open(squash_merge_message_file, 'w') do |file|
+                File.open(merge_message_file, 'w') do |file|
                   file.write("#{self.title}\n#{self.commit_message_for_merge}\n")
                 end
 
-                GitReflow.run("#{GitReflow.git_editor_command} #{squash_merge_message_file}", with_system: true)
-                merge_message = File.read(squash_merge_message_file).split(/[\r\n]|\r\n/).map(&:strip)
+                GitReflow.run("#{GitReflow.git_editor_command} #{merge_message_file}", with_system: true)
+                merge_message = File.read(merge_message_file).split(/[\r\n]|\r\n/).map(&:strip)
 
                 title  = merge_message.shift
 
-                File.delete(squash_merge_message_file)
+                File.delete(merge_message_file)
 
                 unless merge_message.empty?
                   merge_message.shift if merge_message.first.empty?
@@ -124,9 +129,6 @@ module GitReflow
 
               options[:body] = "#{options[:message]}\n" if options[:body].nil? and "#{options[:message]}".length > 0
 
-              merge_method   = options[:merge_method] || GitReflow::Config.get("reflow.merge-method")
-              merge_method   = "squash" if "#{merge_method}".length < 1
-
               merge_response = GitReflow::GitServer::GitHub.connection.pull_requests.merge(
                 "#{GitReflow.git_server.class.remote_user}",
                 "#{GitReflow.git_server.class.remote_repo_name}",
@@ -145,13 +147,19 @@ module GitReflow
                 GitReflow.run_command_with_label "git pull origin #{self.base_branch_name}"
                 GitReflow.say "Pull request ##{self.number} successfully merged.", :success
 
-                if cleanup_feature_branch?
-                  GitReflow.run_command_with_label "git push origin :#{self.feature_branch_name}"
+                if cleanup_remote_feature_branch?
+                  GitReflow.run_command_with_label "git push origin :#{self.feature_branch_name}", blocking: false
+                else
+                  GitReflow.say "Skipped. Remote feature branch #{self.feature_branch_name} left in tact."
+                end
+
+                if cleanup_local_feature_branch?
                   GitReflow.run_command_with_label "git branch -D #{self.feature_branch_name}"
-                  GitReflow.say "Nice job buddy."
                 else
-                  cleanup_failure_message
+                  GitReflow.say "Skipped. Local feature branch #{self.feature_branch_name} left in tact."
                 end
+
+                GitReflow.say "Nice job buddy."
               else
                 GitReflow.say merge_response.to_s, :deliver_halted
                 GitReflow.say "There were problems commiting your feature... please check the errors above and try again.", :error

data/lib/git_reflow/git_server/pull_request.rb

@@ -158,6 +158,8 @@ module GitReflow
       end
 
       def commit_message_for_merge
+        return GitReflow.merge_commit_template unless GitReflow.merge_commit_template.nil?
+
         message = ""
 
         if "#{self.description}".length > 0
@@ -176,7 +178,21 @@ module GitReflow
       end
 
       def cleanup_feature_branch?
-        GitReflow::Config.get('reflow.always-cleanup') == "true" || (ask "Would you like to push this branch to your remote repo and cleanup your feature branch? ") =~ /^y/i
+        cleanup_local_feature_branch? || cleanup_remote_feature_branch?
+      end
+
+      def cleanup_local_feature_branch?
+        # backwards compat
+        always_cleanup_local = GitReflow::Config.get('reflow.always-cleanup').to_s
+        always_cleanup_local = GitReflow::Config.get('reflow.always-cleanup-local') if always_cleanup_local.empty?
+        always_cleanup_local == "true" || (ask "Would you like to cleanup your local feature branch? ") =~ /^y/i
+      end
+
+      def cleanup_remote_feature_branch?
+        # backwards compat
+        always_cleanup_remote = GitReflow::Config.get('reflow.always-cleanup').to_s
+        always_cleanup_remote = GitReflow::Config.get('reflow.always-cleanup-remote') if always_cleanup_remote.empty?
+        always_cleanup_remote == "true" || (ask "Would you like to cleanup your remote feature branch? ") =~ /^y/i
       end
 
       def deliver?
@@ -204,14 +220,14 @@ module GitReflow
           GitReflow.run_command_with_label "git checkout #{self.base_branch_name}"
           GitReflow.run_command_with_label "git pull origin #{self.base_branch_name}"
 
-          case merge_method
+          case merge_method.to_s
           when /squash/i
             GitReflow.run_command_with_label "git merge --squash #{self.feature_branch_name}"
           else
             GitReflow.run_command_with_label "git merge #{self.feature_branch_name}"
           end
 
-          GitReflow.append_to_squashed_commit_message(message) if message.length > 0
+          GitReflow.append_to_merge_commit_message(message) if message.length > 0
 
           if GitReflow.run_command_with_label 'git commit', with_system: true
             GitReflow.say "Pull request ##{self.number} successfully merged.", :success

data/lib/git_reflow/merge_error.rb

@@ -1,9 +1,9 @@
-module GitReflow
-  module GitServer
-    class MergeError < StandardError
-      def initialize(msg="Merge failed")
-        super(msg)
-      end
-    end
-  end
-end
+module GitReflow
+  module GitServer
+    class MergeError < StandardError
+      def initialize(msg="Merge failed")
+        super(msg)
+      end
+    end
+  end
+end

data/lib/git_reflow/rspec.rb

@@ -1,2 +1,3 @@
 require_relative 'rspec/command_line_helpers'
 require_relative 'rspec/stub_helpers'
+require_relative 'rspec/workflow_helpers'

data/lib/git_reflow/rspec/command_line_helpers.rb

@@ -2,11 +2,12 @@ require "highline"
 
 module GitReflow
   module RSpec
+    # @nodoc
     module CommandLineHelpers
-
       def stub_command_line
         $commands_ran     = []
         $stubbed_commands = {}
+        $stubbed_runners  = Set.new
         $output           = []
         $says             = []
 
@@ -33,6 +34,7 @@ module GitReflow
       end
 
       def stub_run_for(module_to_stub)
+        $stubbed_runners << module_to_stub
         allow(module_to_stub).to receive(:run) do |command, options|
           options = { loud: true, blocking: true }.merge(options || {})
           $commands_ran << Hashie::Mash.new(command: command, options: options)
@@ -52,16 +54,31 @@ module GitReflow
         $says = []
       end
 
-      def stub_command(command, return_value)
+      def stub_command(command:, return_value: "", options: {})
         $stubbed_commands[command] = return_value
-        allow(GitReflow::Sandbox).to receive(:run).with(command).and_return(return_value)
+        $stubbed_runners.each do |runner|
+          allow(runner).to receive(:run).with(command, options) do |command, options|
+            options = { loud: true, blocking: true }.merge(options || {})
+            $commands_ran << Hashie::Mash.new(command: command, options: options)
+            $stubbed_commands[command] = return_value
+            raise GitReflow::Sandbox::CommandError.new(return_value, "\"#{command}\" failed to run.") if options[:raise]
+          end
+        end
+      end
+
+      def stub_command_line_inputs_for(module_to_stub, inputs)
+        allow(module_to_stub).to receive(:ask) do |terminal, question|
+          return_value = inputs[question]
+          question = ""
+          return_value
+        end
       end
 
       def stub_command_line_inputs(inputs)
         allow_any_instance_of(HighLine).to receive(:ask) do |terminal, question|
-        return_value = inputs[question]
-        question = ""
-        return_value
+          return_value = inputs[question]
+          question = ""
+          return_value
         end
       end
 

data/lib/git_reflow/rspec/stub_helpers.rb

@@ -1,13 +1,13 @@
-module GitReflow
-  module RSpec
-    module StubHelpers
-
-      def stub_with_fallback(obj, method)
-        original_method = obj.method(method)
-        allow(obj).to receive(method).with(anything()) { |*args| original_method.call(*args) }
-        return allow(obj).to receive(method)
-      end
-
-    end
-  end
-end
+module GitReflow
+  module RSpec
+    module StubHelpers
+
+      def stub_with_fallback(obj, method)
+        original_method = obj.method(method)
+        allow(obj).to receive(method).with(anything()) { |*args| original_method.call(*args) }
+        return allow(obj).to receive(method)
+      end
+
+    end
+  end
+end

data/lib/git_reflow/rspec/workflow_helpers.rb

@@ -0,0 +1,18 @@
+module GitReflow
+  module RSpec
+    # @nodoc
+    module WorkflowHelpers
+      def use_workflow(path)
+        allow(GitReflow::Workflows::Core).to receive(:load_workflow).and_return(
+          GitReflow::Workflows::Core.load_raw_workflow(File.read(path))
+        )
+      end
+
+      def suppress_loading_of_external_workflows
+        allow(GitReflow::Workflows::Core).to receive(:load__workflow).with("#{GitReflow.git_root_dir}/Workflow").and_return(false)
+        return if GitReflow::Config.get('reflow.workflow').to_s.empty?
+        allow(GitReflow::Workflows::Core).to receive(:load_workflow).with(GitReflow::Config.get('reflow.workflow')).and_return(false)
+      end
+    end
+  end
+end

data/lib/git_reflow/sandbox.rb

@@ -4,6 +4,7 @@ module GitReflow
 
     COLOR_FOR_LABEL = {
       notice:         :yellow,
+      info:           :yellow,
       error:          :red,
       deliver_halted: :red,
       review_halted:  :red,
@@ -11,8 +12,16 @@ module GitReflow
       plain:          :white
     }
 
+    class CommandError < StandardError;
+      attr_reader :output
+      def initialize(output, *args)
+        @output = output
+        super(*args)
+      end
+    end
+
     def run(command, options = {})
-      options = { loud: true, blocking: true }.merge(options)
+      options = { loud: true, blocking: true, raise: false }.merge(options)
 
       GitReflow.logger.debug "Running... #{command}"
 
@@ -21,12 +30,13 @@ module GitReflow
       else
         output = %x{#{command}}
 
-        if options[:blocking] == true && !$?.success?
-          abort "\"#{command}\" failed to run."
-        else
-          puts output if options[:loud] == true
-          output
+        if !$?.success?
+          raise CommandError.new(output, "\"#{command}\" failed to run.") if options[:raise] == true
+          abort "\"#{command}\" failed to run." if options[:blocking] == true
         end
+
+        puts output if options[:loud] == true
+        output
       end
     end
 

data/lib/git_reflow/version.rb

@@ -1,3 +1,3 @@
 module GitReflow
-  VERSION = "0.8.10"
+  VERSION = "0.9.4"
 end

data/lib/git_reflow/workflow.rb

@@ -1,5 +1,6 @@
 require 'git_reflow/sandbox'
 require 'git_reflow/git_helpers'
+require 'bundler/inline'
 
 module GitReflow
   module Workflow
@@ -9,21 +10,129 @@ module GitReflow
 
     # @nodoc
     def self.current
-      workflow_file = GitReflow::Config.get('reflow.workflow')
-      if workflow_file.length > 0 and File.exists?(workflow_file)
-        GitReflow.logger.debug "Using workflow: #{workflow_file}"
-        eval(File.read(workflow_file))
-      else
-        GitReflow.logger.debug "Using core workflow..."
-        GitReflow::Workflows::Core
+      return @current unless @current.nil?
+      # First look for a "Workflow" file in the current directory, then check
+      # for a global Workflow file stored in git-reflow git config.
+      loaded_local_workflow  = GitReflow::Workflows::Core.load_workflow "#{GitReflow.git_root_dir}/Workflow"
+      loaded_global_workflow = false
+
+      unless loaded_local_workflow
+        loaded_global_workflow = GitReflow::Workflows::Core.load_workflow GitReflow::Config.get('reflow.workflow')
       end
+
+      @current = GitReflow::Workflows::Core
+    end
+
+    # @nodoc
+    # This is primarily a helper method for tests.  Due to the nature of how the
+    # tests load many different workflows, this helps start fresh and isolate
+    # the scenario at hand.
+    def self.reset!
+      GitReflow.logger.debug "Resetting GitReflow workflow..."
+      current.commands = {}
+      current.callbacks = { before: {}, after: {}}
+      @current = nil
+      # We'll need to reload the core class again in order to clear previously
+      # eval'd content in the context of the class
+      load File.expand_path('../workflows/core.rb', __FILE__)
     end
 
     module ClassMethods
       include GitReflow::Sandbox
       include GitReflow::GitHelpers
 
-      # Creates a singleton method on the inlcuded class
+      def commands
+        @commands ||= {}
+      end
+
+      def commands=(command_hash)
+        @commands = command_hash
+      end
+
+      def command_docs
+        @command_docs ||= {}
+      end
+
+      def command_docs=(command_doc_hash)
+        @command_docs = command_doc_hash
+      end
+
+      def callbacks
+        @callbacks ||= {
+          before: {},
+          after: {}
+        }
+      end
+
+      def callbacks=(callback_hash)
+        @callbacks = callback_hash
+      end
+
+      # Proxy our Config class so that it's available in workflow files
+      def git_config
+        GitReflow::Config
+      end
+
+      def git_server
+        GitReflow.git_server
+      end
+
+      def logger
+        GitReflow.logger
+      end
+
+      # Checks for an installed gem, and if none is installed use bundler's
+      # inline gemfile to install it.
+      #
+      # @param name [String] the name of the gem to require as a dependency
+      def use_gem(name, *args)
+        run("gem list -ie #{name}", loud: false, raise: true)
+        logger.info "Using installed gem '#{name}' with options: #{args.inspect}"
+      rescue ::GitReflow::Sandbox::CommandError => e
+        abort e.message unless e.output =~ /\Afalse/
+        logger.info "Installing gem '#{name}' with options: #{args.inspect}"
+        say "Installing gem '#{name}'...", :notice
+        gemfile do
+          source "https://rubygems.org"
+          gem name, *args
+        end
+      end
+
+      # Use bundler's inline gemfile to install dependencies.
+      # See: https://bundler.io/v1.16/guides/bundler_in_a_single_file_ruby_script.html
+      #
+      # @yield A block to be executed in the context of Bundler's `gemfile` DSL
+      def use_gemfile(&block)
+        logger.info "Using a custom gemfile"
+        gemfile(true, &block)
+      end
+
+      # Loads a pre-defined workflow (FlatMergeWorkflow) from within another
+      # Workflow file
+      #
+      # @param name [String] the name of the Workflow file to use as a basis
+      def use(workflow_name)
+        if workflows.key?(workflow_name)
+          GitReflow.logger.debug "Using Workflow: #{workflow_name}"
+          GitReflow::Workflows::Core.load_workflow(workflows[workflow_name])
+        else
+          GitReflow.logger.error "Tried to use non-existent Workflow: #{workflow_name}"
+        end
+      end
+
+      # Keeps track of available workflows when using `.use(workflow_name)`
+      # Workflow file
+      #
+      # @return [Hash, nil] A hash with [workflow_name, workflow_path] as key/value pairs
+      def workflows
+        return @workflows if @workflows
+        workflow_paths = Dir["#{File.dirname(__FILE__)}/workflows/*Workflow"]
+        @workflows = {}
+        workflow_paths.each { |p| @workflows[File.basename(p)] = p }
+        @workflows
+      end
+
+      # Creates a singleton method on the included class
       #
       # This method will take any number of keyword parameters. If @defaults keyword is provided, and the given
       # key(s) in the defaults are not provided as keyword parameters, then it will use the value given in the
@@ -34,11 +143,24 @@ module GitReflow
       #
       # @yield [a:, b:, c:, ...] Invokes the block with an arbitrary number of keyword arguments
       def command(name, **params, &block)
-        defaults = params[:defaults] || {}
+        params[:flags]     ||= {}
+        params[:switches]  ||= {}
+        params[:arguments] ||= {}
+        defaults           ||= params[:arguments].merge(params[:flags]).merge(params[:switches])
+
+        # Ensure flags and switches use kebab-case
+        kebab_case_keys!(params[:flags])
+        kebab_case_keys!(params[:switches])
+
+        # Register the command with the workflow so that we can properly handle
+        # option parsing from the command line
+        self.commands[name] = params
+        self.command_docs[name] = params
+
         self.define_singleton_method(name) do |**args|
           args_with_defaults = {}
           args.each do |name, value|
-            if "#{value}".length <= 0
+            if "#{value}".length <= 0 && !defaults[name].nil?
               args_with_defaults[name] = defaults[name]
             else
               args_with_defaults[name] = value
@@ -51,9 +173,182 @@ module GitReflow
             end
           end
 
+          GitReflow.logger.debug "callbacks: #{callbacks.inspect}"
+          Array(callbacks[:before][name]).each do |block|
+            GitReflow.logger.debug "(before) callback running for `#{name}` command..."
+            argument_overrides = block.call(**args_with_defaults) || {}
+            args_with_defaults.merge!(argument_overrides) if argument_overrides.is_a?(Hash)
+          end
+
+          GitReflow.logger.info "Running command `#{name}` with args: #{args_with_defaults.inspect}..."
           block.call(**args_with_defaults)
+
+          Array(callbacks[:after][name]).each do |block|
+            GitReflow.logger.debug "(after) callback running for `#{name}` command..."
+            block.call(**args_with_defaults)
+          end
         end
       end
+
+      # Stores a Proc to be called once the command successfully finishes
+      #
+      # Procs declared with `before` are executed sequentially in the order they are defined in a custom Workflow
+      # file.
+      #
+      # @param name [Symbol] the name of the method to create
+      #
+      # @yield A block to be executed before the given command.  These blocks
+      # are executed in the context of `GitReflow::Workflows::Core`
+      def before(name, &block)
+        name = name.to_sym
+        if commands[name].nil?
+          GitReflow.logger.error "Attempted to register (before) callback for non-existing command: #{name}"
+        else
+          GitReflow.logger.debug "(before) callback registered for: #{name}"
+          callbacks[:before][name] ||= []
+          callbacks[:before][name] << block
+        end
+      end
+
+      # Stores a Proc to be called once the command successfully finishes
+      #
+      # Procs declared with `after` are executed sequentially in the order they are defined in a custom Workflow
+      # file.
+      #
+      # @param name [Symbol] the name of the method to create
+      #
+      # @yield A block to be executed after the given command.  These blocks
+      # are executed in the context of `GitReflow::Workflows::Core`
+      def after(name, &block)
+        name = name.to_sym
+        if commands[name].nil?
+          GitReflow.logger.error "Attempted to register (after) callback for non-existing command: #{name}"
+        else
+          GitReflow.logger.debug "(after) callback registered for: #{name}"
+          callbacks[:after][name] ||= []
+          callbacks[:after][name] << block
+        end
+      end
+
+      # Creates a singleton method on the included class
+      #
+      # This method updates the help text associated with the provided command.
+      #
+      # @param name [Symbol] the name of the command to add/update help text for
+      # @param defaults [Hash] keyword arguments to provide fallbacks for
+      def command_help(name, summary:, arguments: {}, flags: {}, switches: {},  description: "")
+        command_docs[name] = {
+          summary: summary,
+          description: description,
+          arguments: arguments,
+          flags: kebab_case_keys!(flags),
+          switches: kebab_case_keys!(switches)
+        }
+      end
+
+      # Outputs documentation for the provided command
+      #
+      # @param name [Symbol] the name of the command to output help text for
+      def documentation_for_command(name)
+        name = name.to_sym
+        docs = command_docs[name]
+        if !docs.nil?
+          GitReflow.say "USAGE"
+          GitReflow.say "    git-reflow #{name} [command options] #{docs[:arguments].keys.map {|arg| "[#{arg}]" }.join(' ')}"
+          if docs[:arguments].any?
+            GitReflow.say "ARGUMENTS"
+            docs[:arguments].each do |arg_name, arg_desc|
+              default_text = commands[name][:arguments][arg_name].nil? ? "" : "(default: #{commands[name][:arguments][arg_name]}) "
+              GitReflow.say "    #{arg_name} – #{default_text}#{arg_desc}"
+            end
+          end
+          if docs[:flags].any? || docs[:switches].any?
+            cmd = commands[name.to_sym]
+            GitReflow.say "COMMAND OPTIONS"
+            docs[:flags].each do |flag_name, flag_desc|
+              flag_names = ["-#{flag_name.to_s[0]}", "--#{flag_name}"]
+              flag_default = cmd[:flags][flag_name]
+
+              GitReflow.say "    #{flag_names} – #{!flag_default.nil? ? "(default: #{flag_default})  " : ""}#{flag_desc}"
+            end
+            docs[:switches].each do |switch_name, switch_desc|
+              switch_names = [switch_name.to_s[0], "-#{switch_name}"].map {|s| "-#{s}" }.join(', ')
+              switch_default = cmd[:switches][switch_name]
+
+              GitReflow.say "    #{switch_names} – #{!switch_default.nil? ? "(default: #{switch_default})  " : ""}#{switch_desc}"
+            end
+          end
+        else
+          help
+        end
+      end
+
+      # Outputs documentation for git-reflow
+      def help
+        GitReflow.say "NAME"
+        GitReflow.say "    git-reflow – Git Reflow manages your git workflow."
+        GitReflow.say "VERSION"
+        GitReflow.say "    #{GitReflow::VERSION}"
+        GitReflow.say "USAGE"
+        GitReflow.say "    git-reflow command [command options] [arguments...]"
+        GitReflow.say "COMMANDS"
+        command_docs.each do |command_name, command_doc|
+          GitReflow.say "    #{command_name}\t– #{command_doc[:summary]}"
+        end
+      end
+
+      # Parses ARGV for the provided git-reflow command name
+      #
+      # @param name [Symbol, String] the name of the git-reflow command to parse from ARGV
+      def parse_command_options!(name)
+        name = name.to_sym
+        options = {}
+        docs = command_docs[name]
+        OptionParser.new do |opts|
+          opts.banner = "USAGE:\n  git-reflow #{name} [command options] #{docs[:arguments].keys.map {|arg| "[#{arg}]" }.join(' ')}"
+          opts.separator  ""
+          opts.separator  "COMMAND OPTIONS:" if docs[:flags].any? || docs[:switches].any?
+
+          self.commands[name][:flags].each do |flag_name, flag_default|
+            opts.on("-#{flag_name[0]}", "--#{flag_name} #{flag_name.upcase}", command_docs[name][:flags][flag_name]) do |f|
+              options[kebab_to_underscore(flag_name)] = f || flag_default
+            end
+          end
+
+          self.commands[name][:switches].each do |switch_name, switch_default|
+            opts.on("-#{switch_name[0]}", "--[no-]#{switch_name}", command_docs[name][:switches][switch_name]) do |s|
+              options[kebab_to_underscore(switch_name)] = s || switch_default
+            end
+          end
+        end.parse!
+
+        # Add arguments to optiosn to pass to defined commands
+        commands[name][:arguments].each do |arg_name, arg_default|
+          options[arg_name] = ARGV.shift || arg_default
+        end
+        options
+      rescue OptionParser::InvalidOption
+        documentation_for_command(name)
+        exit 1
+      end
+
+      private
+
+      def kebab_case_keys!(hsh)
+        hsh.keys.each do |key_to_update|
+          hsh[underscore_to_kebab(key_to_update)] = hsh.delete(key_to_update) if key_to_update =~ /_/
+        end
+
+        hsh
+      end
+
+      def kebab_to_underscore(sym_or_string)
+        sym_or_string.to_s.gsub('-', '_').to_sym
+      end
+
+      def underscore_to_kebab(sym_or_string)
+        sym_or_string.to_s.gsub('_', '-').to_sym
+      end
     end
   end
 end