git 4.0.0 → 4.0.1

data/lib/git/lib.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'args_builder'
+
 require 'git/command_line'
 require 'git/errors'
 require 'logger'
@@ -11,6 +13,8 @@ require 'zlib'
 require 'open3'
 
 module Git
+  # Internal git operations
+  # @api private
   class Lib
     # The path to the Git working copy.  The default is '"./.git"'.
     #
@@ -59,23 +63,21 @@ module Git
     #   @param [Logger] logger
     #
     def initialize(base = nil, logger = nil)
-      @git_dir = nil
-      @git_index_file = nil
-      @git_work_dir = nil
-      @path = nil
       @logger = logger || Logger.new(nil)
 
-      if base.is_a?(Git::Base)
-        @git_dir = base.repo.path
-        @git_index_file = base.index.path if base.index
-        @git_work_dir = base.dir.path if base.dir
-      elsif base.is_a?(Hash)
-        @git_dir = base[:repository]
-        @git_index_file = base[:index]
-        @git_work_dir = base[:working_directory]
+      case base
+      when Git::Base
+        initialize_from_base(base)
+      when Hash
+        initialize_from_hash(base)
       end
     end
 
+    INIT_OPTION_MAP = [
+      { keys: [:bare], flag: '--bare', type: :boolean },
+      { keys: [:initial_branch], flag: '--initial-branch', type: :valued_equals }
+    ].freeze
+
     # creates or reinitializes the repository
     #
     # options:
@@ -83,17 +85,30 @@ module Git
     #   :working_directory
     #   :initial_branch
     #
-    def init(opts={})
-      arr_opts = []
-      arr_opts << '--bare' if opts[:bare]
-      arr_opts << "--initial-branch=#{opts[:initial_branch]}" if opts[:initial_branch]
-
-      command('init', *arr_opts)
+    def init(opts = {})
+      args = build_args(opts, INIT_OPTION_MAP)
+      command('init', *args)
     end
 
+    CLONE_OPTION_MAP = [
+      { keys: [:bare],      flag: '--bare',      type: :boolean },
+      { keys: [:recursive], flag: '--recursive', type: :boolean },
+      { keys: [:mirror],    flag: '--mirror',    type: :boolean },
+      { keys: [:branch],    flag: '--branch',    type: :valued_space },
+      { keys: [:filter],    flag: '--filter',    type: :valued_space },
+      { keys: %i[remote origin], flag: '--origin', type: :valued_space },
+      { keys: [:config], flag: '--config', type: :repeatable_valued_space },
+      {
+        keys: [:depth],
+        type: :custom,
+        builder: ->(value) { ['--depth', value.to_i] if value }
+      }
+    ].freeze
+
     # Clones a repository into a newly created directory
     #
     # @param [String] repository_url the URL of the repository to clone
+    #
     # @param [String, nil] directory the directory to clone into
     #
     #   If nil, the repository is cloned into a directory with the same name as
@@ -102,16 +117,28 @@ module Git
     # @param [Hash] opts the options for this command
     #
     # @option opts [Boolean] :bare (false) if true, clone as a bare repository
+    #
     # @option opts [String] :branch the branch to checkout
+    #
     # @option opts [String, Array] :config one or more configuration options to set
+    #
     # @option opts [Integer] :depth the number of commits back to pull
+    #
     # @option opts [String] :filter specify partial clone
+    #
     # @option opts [String] :mirror set up a mirror of the source repository
+    #
     # @option opts [String] :origin the name of the remote
+    #
     # @option opts [String] :path an optional prefix for the directory parameter
+    #
     # @option opts [String] :remote the name of the remote
-    # @option opts [Boolean] :recursive after the clone is created, initialize all submodules within, using their default settings
-    # @option opts [Numeric, nil] :timeout the number of seconds to wait for the command to complete
+    #
+    # @option opts [Boolean] :recursive after the clone is created, initialize all
+    #    within, using their default settings
+    #
+    # @option opts [Numeric, nil] :timeout the number of seconds to wait for the
+    #   command to complete
     #
     #   See {Git::Lib#command} for more information about :timeout
     #
@@ -123,34 +150,14 @@ module Git
       @path = opts[:path] || '.'
       clone_dir = opts[:path] ? File.join(@path, directory) : directory
 
-      arr_opts = []
-      arr_opts << '--bare' if opts[:bare]
-      arr_opts << '--branch' << opts[:branch] if opts[:branch]
-      arr_opts << '--depth' << opts[:depth].to_i if opts[:depth]
-      arr_opts << '--filter' << opts[:filter] if opts[:filter]
-      Array(opts[:config]).each { |c| arr_opts << '--config' << c }
-      arr_opts << '--origin' << opts[:remote] || opts[:origin] if opts[:remote] || opts[:origin]
-      arr_opts << '--recursive' if opts[:recursive]
-      arr_opts << '--mirror' if opts[:mirror]
-
-      arr_opts << '--'
-
-      arr_opts << repository_url
-      arr_opts << clone_dir
+      args = build_args(opts, CLONE_OPTION_MAP)
+      args.push('--', repository_url, clone_dir)
 
-      command('clone', *arr_opts, timeout: opts[:timeout])
+      command('clone', *args, timeout: opts[:timeout])
 
       return_base_opts_from_clone(clone_dir, opts)
     end
 
-    def return_base_opts_from_clone(clone_dir, opts)
-      base_opts = {}
-      base_opts[:repository] = clone_dir if (opts[:bare] || opts[:mirror])
-      base_opts[:working_directory] = clone_dir unless (opts[:bare] || opts[:mirror])
-      base_opts[:log] = opts[:log] if opts[:log]
-      base_opts
-    end
-
     # Returns the name of the default branch of the given repository
     #
     # @param repository [URI, Pathname, String] The (possibly remote) repository to clone from
@@ -171,6 +178,29 @@ module Git
 
     ## READ COMMANDS ##
 
+    # The map defining how to translate user options to git command arguments.
+    DESCRIBE_OPTION_MAP = [
+      { keys: [:all], flag: '--all', type: :boolean },
+      { keys: [:tags], flag: '--tags', type: :boolean },
+      { keys: [:contains], flag: '--contains', type: :boolean },
+      { keys: [:debug], flag: '--debug', type: :boolean },
+      { keys: [:long], flag: '--long', type: :boolean },
+      { keys: [:always], flag: '--always', type: :boolean },
+      { keys: %i[exact_match exact-match], flag: '--exact-match', type: :boolean },
+      { keys: [:abbrev], flag: '--abbrev', type: :valued_equals },
+      { keys: [:candidates], flag: '--candidates', type: :valued_equals },
+      { keys: [:match], flag: '--match', type: :valued_equals },
+      {
+        keys: [:dirty],
+        type: :custom,
+        builder: lambda do |value|
+          return '--dirty' if value == true
+
+          "--dirty=#{value}" if value.is_a?(String)
+        end
+      }
+    ].freeze
+
     # Finds most recent tag that is reachable from a commit
     #
     # @see https://git-scm.com/docs/git-describe git-describe
@@ -198,26 +228,10 @@ module Git
     def describe(commit_ish = nil, opts = {})
       assert_args_are_not_options('commit-ish object', commit_ish)
 
-      arr_opts = []
-
-      arr_opts << '--all' if opts[:all]
-      arr_opts << '--tags' if opts[:tags]
-      arr_opts << '--contains' if opts[:contains]
-      arr_opts << '--debug' if opts[:debug]
-      arr_opts << '--long' if opts[:long]
-      arr_opts << '--always' if opts[:always]
-      arr_opts << '--exact-match' if opts[:exact_match] || opts[:"exact-match"]
+      args = build_args(opts, DESCRIBE_OPTION_MAP)
+      args << commit_ish if commit_ish
 
-      arr_opts << '--dirty' if opts[:dirty] == true
-      arr_opts << "--dirty=#{opts[:dirty]}" if opts[:dirty].is_a?(String)
-
-      arr_opts << "--abbrev=#{opts[:abbrev]}" if opts[:abbrev]
-      arr_opts << "--candidates=#{opts[:candidates]}" if opts[:candidates]
-      arr_opts << "--match=#{opts[:match]}" if opts[:match]
-
-      arr_opts << commit_ish if commit_ish
-
-      command('describe', *arr_opts)
+      command('describe', *args)
     end
 
     # Return the commits that are within the given revision range
@@ -260,20 +274,35 @@ module Git
       command_lines('log', *arr_opts).map { |l| l.split.first }
     end
 
+    FULL_LOG_EXTRA_OPTIONS_MAP = [
+      { type: :static, flag: '--pretty=raw' },
+      { keys: [:skip], flag: '--skip', type: :valued_equals },
+      { keys: [:merges], flag: '--merges', type: :boolean }
+    ].freeze
+
     # Return the commits that are within the given revision range
     #
     # @see https://git-scm.com/docs/git-log git-log
     #
     # @param opts [Hash] the given options
     #
-    # @option opts :count [Integer] the maximum number of commits to return (maps to max-count)
+    # @option opts :count [Integer] the maximum number of commits to return (maps to
+    #   max-count)
+    #
     # @option opts :all [Boolean]
+    #
     # @option opts :cherry [Boolean]
+    #
     # @option opts :since [String]
+    #
     # @option opts :until [String]
+    #
     # @option opts :grep [String]
+    #
     # @option opts :author [String]
-    # @option opts :between [Array<String>] an array of two commit-ish strings to specify a revision range
+    #
+    # @option opts :between [Array<String>] an array of two commit-ish strings to
+    #   specify a revision range
     #
     #   Only :between or :object options can be used, not both.
     #
@@ -281,37 +310,39 @@ module Git
     #
     #   Only :between or :object options can be used, not both.
     #
-    # @option opts :path_limiter [Array<String>, String] only include commits that impact files from the specified paths
+    # @option opts :path_limiter [Array<String>, String] only include commits that
+    #   impact files from the specified paths
+    #
     # @option opts :skip [Integer]
     #
     # @return [Array<Hash>] the log output parsed into an array of hashs for each commit
     #
     #   Each hash contains the following keys:
+    #
     #   * 'sha' [String] the commit sha
     #   * 'author' [String] the author of the commit
     #   * 'message' [String] the commit message
     #   * 'parent' [Array<String>] the commit shas of the parent commits
     #   * 'tree' [String] the tree sha
-    #   * 'author' [String] the author of the commit and timestamp of when the changes were created
-    #   * 'committer' [String] the committer of the commit and timestamp of when the commit was applied
-    #   * 'merges' [Boolean] if truthy, only include merge commits (aka commits with 2 or more parents)
+    #   * 'author' [String] the author of the commit and timestamp of when the
+    #     changes were created
+    #   * 'committer' [String] the committer of the commit and timestamp of when the
+    #     commit was applied
+    #   * 'merges' [Boolean] if truthy, only include merge commits (aka commits with
+    #     2 or more parents)
     #
-    # @raise [ArgumentError] if the revision range (specified with :between or :object) is a string starting with a hyphen
+    # @raise [ArgumentError] if the revision range (specified with :between or
+    #   :object) is a string starting with a hyphen
     #
     def full_log_commits(opts = {})
       assert_args_are_not_options('between', opts[:between]&.first)
       assert_args_are_not_options('object', opts[:object])
 
-      arr_opts = log_common_options(opts)
-
-      arr_opts << '--pretty=raw'
-      arr_opts << "--skip=#{opts[:skip]}" if opts[:skip]
-      arr_opts << '--merges' if opts[:merges]
-
-      arr_opts += log_path_options(opts)
-
-      full_log = command_lines('log', *arr_opts)
+      args = log_common_options(opts)
+      args += build_args(opts, FULL_LOG_EXTRA_OPTIONS_MAP)
+      args += log_path_options(opts)
 
+      full_log = command_lines('log', *args)
       process_commit_log_data(full_log)
     end
 
@@ -319,7 +350,8 @@ module Git
     #
     # @see https://git-scm.com/docs/git-rev-parse git-rev-parse
     # @see https://git-scm.com/docs/git-rev-parse#_specifying_revisions Valid ways to specify revisions
-    # @see https://git-scm.com/docs/git-rev-parse#Documentation/git-rev-parse.txt-emltrefnamegtemegemmasterememheadsmasterememrefsheadsmasterem Ref disambiguation rules
+    # @see https://git-scm.com/docs/git-rev-parse#Documentation/git-rev-parse.txt-emltrefnamegtemegemmasterememheadsmasterememrefsheadsmasterem
+    #      Ref disambiguation rules
     #
     # @example
     #   lib.rev_parse('HEAD') # => '9b9b31e704c0b85ffdd8d2af2ded85170a5af87d'
@@ -339,7 +371,7 @@ module Git
     end
 
     # For backwards compatibility with the old method name
-    alias :revparse :rev_parse
+    alias revparse rev_parse
 
     # Find the first symbolic name for given commit_ish
     #
@@ -355,7 +387,7 @@ module Git
       command('name-rev', commit_ish).split[1]
     end
 
-    alias :namerev :name_rev
+    alias namerev name_rev
 
     # Output the contents or other properties of one or more objects.
     #
@@ -373,7 +405,7 @@ module Git
     #
     # @raise [ArgumentError] if object is a string starting with a hyphen
     #
-    def cat_file_contents(object, &block)
+    def cat_file_contents(object)
       assert_args_are_not_options('object', object)
 
       if block_given?
@@ -381,7 +413,7 @@ module Git
           # If a block is given, write the output from the process to a temporary
           # file and then yield the file to the block
           #
-          command('cat-file', "-p", object, out: file, err: file)
+          command('cat-file', '-p', object, out: file, err: file)
           file.rewind
           yield file
         end
@@ -391,7 +423,7 @@ module Git
       end
     end
 
-    alias :object_contents :cat_file_contents
+    alias object_contents cat_file_contents
 
     # Get the type for the given object
     #
@@ -409,7 +441,7 @@ module Git
       command('cat-file', '-t', object)
     end
 
-    alias :object_type :cat_file_type
+    alias object_type cat_file_type
 
     # Get the size for the given object
     #
@@ -427,7 +459,7 @@ module Git
       command('cat-file', '-s', object).to_i
     end
 
-    alias :object_size :cat_file_size
+    alias object_size cat_file_size
 
     # Return a hash of commit data
     #
@@ -454,25 +486,15 @@ module Git
       process_commit_data(cdata, object)
     end
 
-    alias :commit_data :cat_file_commit
+    alias commit_data cat_file_commit
 
     def process_commit_data(data, sha)
-      hsh = {
-        'sha'    => sha,
-        'parent' => []
-      }
+      # process_commit_headers consumes the header lines from the `data` array,
+      # leaving only the message lines behind.
+      headers = process_commit_headers(data)
+      message = "#{data.join("\n")}\n"
 
-      each_cat_file_header(data) do |key, value|
-        if key == 'parent'
-          hsh['parent'] << value
-        else
-          hsh[key] = value
-        end
-      end
-
-      hsh['message'] = data.join("\n") + "\n"
-
-      hsh
+      { 'sha' => sha, 'message' => message }.merge(headers)
     end
 
     CAT_FILE_HEADER_LINE = /\A(?<key>\w+) (?<value>.*)\z/
@@ -482,9 +504,7 @@ module Git
         key = match[:key]
         value_lines = [match[:value]]
 
-        while data.first.start_with?(' ')
-          value_lines << data.shift.lstrip
-        end
+        value_lines << data.shift.lstrip while data.first.start_with?(' ')
 
         yield key, value_lines.join("\n")
       end
@@ -492,10 +512,12 @@ module Git
 
     # Return a hash of annotated tag data
     #
-    # Does not work with lightweight tags. List all annotated tags in your repository with the following command:
+    # Does not work with lightweight tags. List all annotated tags in your repository
+    # with the following command:
     #
     # ```sh
-    # git for-each-ref --format='%(refname:strip=2)' refs/tags | while read tag; do git cat-file tag $tag >/dev/null 2>&1 && echo $tag; done
+    # git for-each-ref --format='%(refname:strip=2)' refs/tags | \
+    #   while read tag; do git cat-file tag $tag >/dev/null 2>&1 && echo $tag; done
     # ```
     #
     # @see https://git-scm.com/docs/git-cat-file git-cat-file
@@ -520,7 +542,8 @@ module Git
     #   * object [String] the sha of the tag object
     #   * type [String]
     #   * tag [String] tag name
-    #   * tagger [String] the name and email of the user who created the tag and the timestamp of when the tag was created
+    #   * tagger [String] the name and email of the user who created the tag
+    #     and the timestamp of when the tag was created
     #   * message [String] the tag message
     #
     # @raise [ArgumentError] if object is a string starting with a hyphen
@@ -532,7 +555,7 @@ module Git
       process_tag_data(tdata, object)
     end
 
-    alias :tag_data :cat_file_tag
+    alias tag_data cat_file_tag
 
     def process_tag_data(data, name)
       hsh = { 'name' => name }
@@ -541,64 +564,88 @@ module Git
         hsh[key] = value
       end
 
-      hsh['message'] = data.join("\n") + "\n"
+      hsh['message'] = "#{data.join("\n")}\n"
 
       hsh
     end
 
     def process_commit_log_data(data)
-      in_message = false
+      RawLogParser.new(data).parse
+    end
 
-      hsh_array = []
+    # A private parser class to process the output of `git log --pretty=raw`
+    # @api private
+    class RawLogParser
+      def initialize(lines)
+        @lines = lines
+        @commits = []
+        @current_commit = nil
+        @in_message = false
+      end
 
-      hsh = nil
+      def parse
+        @lines.each { |line| process_line(line.chomp) }
+        finalize_commit
+        @commits
+      end
 
-      data.each do |line|
-        line = line.chomp
+      private
 
-        if line[0].nil?
-          in_message = !in_message
-          next
+      def process_line(line)
+        if line.empty?
+          @in_message = !@in_message
+          return
         end
 
-        in_message = false if in_message && line[0..3] != "    "
+        @in_message = false if @in_message && !line.start_with?('    ')
 
-        if in_message
-          hsh['message'] << "#{line[4..-1]}\n"
-          next
-        end
+        @in_message ? process_message_line(line) : process_metadata_line(line)
+      end
 
+      def process_message_line(line)
+        @current_commit['message'] << "#{line[4..]}\n"
+      end
+
+      def process_metadata_line(line)
         key, *value = line.split
         value = value.join(' ')
 
         case key
-          when 'commit'
-            hsh_array << hsh if hsh
-            hsh = {'sha' => value, 'message' => +'', 'parent' => []}
-          when 'parent'
-            hsh['parent'] << value
-          else
-            hsh[key] = value
+        when 'commit'
+          start_new_commit(value)
+        when 'parent'
+          @current_commit['parent'] << value
+        else
+          @current_commit[key] = value
         end
       end
 
-      hsh_array << hsh if hsh
+      def start_new_commit(sha)
+        finalize_commit
+        @current_commit = { 'sha' => sha, 'message' => +'', 'parent' => [] }
+      end
 
-      hsh_array
+      def finalize_commit
+        @commits << @current_commit if @current_commit
+      end
     end
+    private_constant :RawLogParser
+
+    LS_TREE_OPTION_MAP = [
+      { keys: [:recursive], flag: '-r', type: :boolean }
+    ].freeze
 
     def ls_tree(sha, opts = {})
       data = { 'blob' => {}, 'tree' => {}, 'commit' => {} }
+      args = build_args(opts, LS_TREE_OPTION_MAP)
 
-      ls_tree_opts = []
-      ls_tree_opts << '-r' if opts[:recursive]
-      # path must be last arg
-      ls_tree_opts << opts[:path] if opts[:path]
+      args.unshift(sha)
+      args << opts[:path] if opts[:path]
 
-      command_lines('ls-tree', sha, *ls_tree_opts).each do |line|
+      command_lines('ls-tree', *args).each do |line|
         (info, filenm) = line.split("\t")
         (mode, type, sha) = info.split
-        data[type][filenm] = {:mode => mode, :sha => sha}
+        data[type][filenm] = { mode: mode, sha: sha }
       end
 
       data
@@ -646,31 +693,9 @@ module Git
 
     def branches_all
       lines = command_lines('branch', '-a')
-      lines.each_with_index.map do |line, line_index|
-        match_data = line.match(BRANCH_LINE_REGEXP)
-
-        raise Git::UnexpectedResultError, unexpected_branch_line_error(lines, line, line_index) unless match_data
-        next nil if match_data[:not_a_branch] || match_data[:detached_ref]
-
-        [
-          match_data[:refname],
-          !match_data[:current].nil?,
-          !match_data[:worktree].nil?,
-          match_data[:symref]
-        ]
-      end.compact
-    end
-
-    def unexpected_branch_line_error(lines, line, index)
-      <<~ERROR
-        Unexpected line in output from `git branch -a`, line #{index + 1}
-
-        Full output:
-          #{lines.join("\n  ")}
-
-        Line #{index + 1}:
-          "#{line}"
-      ERROR
+      lines.each_with_index.filter_map do |line, index|
+        parse_branch_line(line, index, lines)
+      end
     end
 
     def worktrees_all
@@ -686,7 +711,7 @@ module Git
       # detached
       #
       command_lines('worktree', 'list', '--porcelain').each do |w|
-        s = w.split("\s")
+        s = w.split
         directory = s[1] if s[0] == 'worktree'
         arr << [directory, s[1]] if s[0] == 'HEAD'
       end
@@ -694,7 +719,8 @@ module Git
     end
 
     def worktree_add(dir, commitish = nil)
-      return command('worktree', 'add', dir, commitish) if !commitish.nil?
+      return command('worktree', 'add', dir, commitish) unless commitish.nil?
+
       command('worktree', 'add', dir)
     end
 
@@ -708,12 +734,7 @@ module Git
 
     def list_files(ref_dir)
       dir = File.join(@git_dir, 'refs', ref_dir)
-      files = []
-      begin
-        files = Dir.glob('**/*', base: dir).select { |f| File.file?(File.join(dir, f)) }
-      rescue
-      end
-      files
+      Dir.glob('**/*', base: dir).select { |f| File.file?(File.join(dir, f)) }
     end
 
     # The state and name of branch pointed to by `HEAD`
@@ -748,16 +769,7 @@ module Git
       branch_name = command('branch', '--show-current')
       return HeadState.new(:detached, 'HEAD') if branch_name.empty?
 
-      state =
-        begin
-          command('rev-parse', '--verify', '--quiet', branch_name)
-          :active
-        rescue Git::FailedError => e
-          raise unless e.result.status.exitstatus == 1 && e.result.stderr.empty?
-
-          :unborn
-        end
-
+      state = get_branch_state(branch_name)
       HeadState.new(state, branch_name)
     end
 
@@ -766,38 +778,35 @@ module Git
       branch_name.empty? ? 'HEAD' : branch_name
     end
 
-    def branch_contains(commit, branch_name="")
-      command("branch",  branch_name, "--contains", commit)
+    def branch_contains(commit, branch_name = '')
+      command('branch',  branch_name, '--contains', commit)
     end
 
+    GREP_OPTION_MAP = [
+      { keys: [:ignore_case],     flag: '-i', type: :boolean },
+      { keys: [:invert_match],    flag: '-v', type: :boolean },
+      { keys: [:extended_regexp], flag: '-E', type: :boolean },
+      # For validation only, as these are handled manually
+      { keys: [:object],       type: :validate_only },
+      { keys: [:path_limiter], type: :validate_only }
+    ].freeze
+
     # returns hash
     # [tree-ish] = [[line_no, match], [line_no, match2]]
     # [tree-ish] = [[line_no, match], [line_no, match2]]
     def grep(string, opts = {})
       opts[:object] ||= 'HEAD'
+      ArgsBuilder.validate!(opts, GREP_OPTION_MAP)
 
-      grep_opts = ['-n']
-      grep_opts << '-i' if opts[:ignore_case]
-      grep_opts << '-v' if opts[:invert_match]
-      grep_opts << '-E' if opts[:extended_regexp]
-      grep_opts << '-e'
-      grep_opts << string
-      grep_opts << opts[:object] if opts[:object].is_a?(String)
-      grep_opts.push('--', opts[:path_limiter]) if opts[:path_limiter].is_a?(String)
-      grep_opts.push('--', *opts[:path_limiter]) if opts[:path_limiter].is_a?(Array)
+      boolean_flags = build_args(opts, GREP_OPTION_MAP)
+      args = ['-n', *boolean_flags, '-e', string, opts[:object]]
 
-      hsh = {}
-      begin
-        command_lines('grep', *grep_opts).each do |line|
-          if m = /(.*?)\:(\d+)\:(.*)/.match(line)
-            hsh[m[1]] ||= []
-            hsh[m[1]] << [m[2].to_i, m[3]]
-          end
-        end
-      rescue Git::FailedError => e
-        raise unless e.result.status.exitstatus == 1 && e.result.stderr == ''
+      if (limiter = opts[:path_limiter])
+        args.push('--', *Array(limiter))
       end
-      hsh
+
+      lines = execute_grep_command(args)
+      parse_grep_output(lines)
     end
 
     # Validate that the given arguments cannot be mistaken for a command-line option
@@ -810,58 +819,64 @@ module Git
     #
     def assert_args_are_not_options(arg_name, *args)
       invalid_args = args.select { |arg| arg&.start_with?('-') }
-      if invalid_args.any?
-        raise ArgumentError, "Invalid #{arg_name}: '#{invalid_args.join("', '")}'"
-      end
+      return unless invalid_args.any?
+
+      raise ArgumentError, "Invalid #{arg_name}: '#{invalid_args.join("', '")}'"
     end
 
+    DIFF_FULL_OPTION_MAP = [
+      { type: :static, flag: '-p' },
+      { keys: [:path_limiter], type: :validate_only }
+    ].freeze
+
     def diff_full(obj1 = 'HEAD', obj2 = nil, opts = {})
       assert_args_are_not_options('commit or commit range', obj1, obj2)
+      ArgsBuilder.validate!(opts, DIFF_FULL_OPTION_MAP)
 
-      diff_opts = ['-p']
-      diff_opts << obj1
-      diff_opts << obj2 if obj2.is_a?(String)
-      diff_opts << '--' << opts[:path_limiter] if opts[:path_limiter].is_a? String
+      args = build_args(opts, DIFF_FULL_OPTION_MAP)
+      args.push(obj1, obj2).compact!
 
-      command('diff', *diff_opts)
+      if (path = opts[:path_limiter]) && path.is_a?(String)
+        args.push('--', path)
+      end
+
+      command('diff', *args)
     end
 
+    DIFF_STATS_OPTION_MAP = [
+      { type: :static, flag: '--numstat' },
+      { keys: [:path_limiter], type: :validate_only }
+    ].freeze
+
     def diff_stats(obj1 = 'HEAD', obj2 = nil, opts = {})
       assert_args_are_not_options('commit or commit range', obj1, obj2)
+      ArgsBuilder.validate!(opts, DIFF_STATS_OPTION_MAP)
 
-      diff_opts = ['--numstat']
-      diff_opts << obj1
-      diff_opts << obj2 if obj2.is_a?(String)
-      diff_opts << '--' << opts[:path_limiter] if opts[:path_limiter].is_a? String
+      args = build_args(opts, DIFF_STATS_OPTION_MAP)
+      args.push(obj1, obj2).compact!
 
-      hsh = {:total => {:insertions => 0, :deletions => 0, :lines => 0, :files => 0}, :files => {}}
-
-      command_lines('diff', *diff_opts).each do |file|
-        (insertions, deletions, filename) = file.split("\t")
-        hsh[:total][:insertions] += insertions.to_i
-        hsh[:total][:deletions] += deletions.to_i
-        hsh[:total][:lines] = (hsh[:total][:deletions] + hsh[:total][:insertions])
-        hsh[:total][:files] += 1
-        hsh[:files][filename] = {:insertions => insertions.to_i, :deletions => deletions.to_i}
+      if (path = opts[:path_limiter]) && path.is_a?(String)
+        args.push('--', path)
       end
 
-      hsh
+      output_lines = command_lines('diff', *args)
+      parse_diff_stats_output(output_lines)
     end
 
+    DIFF_PATH_STATUS_OPTION_MAP = [
+      { type: :static, flag: '--name-status' },
+      { keys: [:path], type: :validate_only }
+    ].freeze
+
     def diff_path_status(reference1 = nil, reference2 = nil, opts = {})
       assert_args_are_not_options('commit or commit range', reference1, reference2)
+      ArgsBuilder.validate!(opts, DIFF_PATH_STATUS_OPTION_MAP)
 
-      opts_arr = ['--name-status']
-      opts_arr << reference1 if reference1
-      opts_arr << reference2 if reference2
+      args = build_args(opts, DIFF_PATH_STATUS_OPTION_MAP)
+      args.push(reference1, reference2).compact!
+      args.push('--', opts[:path]) if opts[:path]
 
-      opts_arr << '--' << opts[:path] if opts[:path]
-
-      command_lines('diff', *opts_arr).inject({}) do |memo, line|
-        status, path = line.split("\t")
-        memo[path] = status
-        memo
-      end
+      parse_diff_path_status(args)
     end
 
     # compares the index and the working directory
@@ -886,14 +901,14 @@ module Git
     #     * :sha_index [String] the file sha
     #     * :stage [String] the file stage
     #
-    def ls_files(location=nil)
+    def ls_files(location = nil)
       location ||= '.'
       {}.tap do |files|
         command_lines('ls-files', '--stage', location).each do |line|
           (info, file) = line.split("\t")
           (mode, sha, stage) = info.split
           files[unescape_quoted_path(file)] = {
-            :path => file, :mode_index => mode, :sha_index => sha, :stage => stage
+            path: file, mode_index: mode, sha_index: sha, stage: stage
           }
         end
       end
@@ -922,21 +937,18 @@ module Git
       end
     end
 
-    def ls_remote(location=nil, opts={})
-      arr_opts = []
-      arr_opts << '--refs' if opts[:refs]
-      arr_opts << (location || '.')
-
-      Hash.new{ |h,k| h[k] = {} }.tap do |hsh|
-        command_lines('ls-remote', *arr_opts).each do |line|
-          (sha, info) = line.split("\t")
-          (ref, type, name) = info.split('/', 3)
-          type ||= 'head'
-          type = 'branches' if type == 'heads'
-          value = {:ref => ref, :sha => sha}
-          hsh[type].update( name.nil? ? value : { name => value })
-        end
-      end
+    LS_REMOTE_OPTION_MAP = [
+      { keys: [:refs], flag: '--refs', type: :boolean }
+    ].freeze
+
+    def ls_remote(location = nil, opts = {})
+      ArgsBuilder.validate!(opts, LS_REMOTE_OPTION_MAP)
+
+      flags = build_args(opts, LS_REMOTE_OPTION_MAP)
+      positional_arg = location || '.'
+
+      output_lines = command_lines('ls-remote', *flags, positional_arg)
+      parse_ls_remote_output(output_lines)
     end
 
     def ignored_files
@@ -950,9 +962,7 @@ module Git
     def config_remote(name)
       hsh = {}
       config_list.each do |key, value|
-        if /remote.#{name}/.match(key)
-          hsh[key.gsub("remote.#{name}.", '')] = value
-        end
+        hsh[key.gsub("remote.#{name}.", '')] = value if /remote.#{name}/.match(key)
       end
       hsh
     end
@@ -991,7 +1001,7 @@ module Git
     # @param [String|NilClass] objectish the target object reference (nil == HEAD)
     # @param [String|NilClass] path the path of the file to be shown
     # @return [String] the object information
-    def show(objectish=nil, path=nil)
+    def show(objectish = nil, path = nil)
       arr_opts = []
 
       arr_opts << (path ? "#{objectish}:#{path}" : objectish)
@@ -1001,18 +1011,24 @@ module Git
 
     ## WRITE COMMANDS ##
 
+    CONFIG_SET_OPTION_MAP = [
+      { keys: [:file], flag: '--file', type: :valued_space }
+    ].freeze
+
     def config_set(name, value, options = {})
-      if options[:file].to_s.empty?
-        command('config', name, value)
-      else
-        command('config', '--file', options[:file], name, value)
-      end
+      ArgsBuilder.validate!(options, CONFIG_SET_OPTION_MAP)
+      flags = build_args(options, CONFIG_SET_OPTION_MAP)
+      command('config', *flags, name, value)
     end
 
     def global_config_set(name, value)
       command('config', '--global', name, value)
     end
 
+    ADD_OPTION_MAP = [
+      { keys: [:all], flag: '--all', type: :boolean },
+      { keys: [:force], flag: '--force', type: :boolean }
+    ].freeze
 
     # Update the index from the current worktree to prepare the for the next commit
     #
@@ -1027,29 +1043,28 @@ module Git
     # @option options [Boolean] :all Add, modify, and remove index entries to match the worktree
     # @option options [Boolean] :force Allow adding otherwise ignored files
     #
-    def add(paths='.',options={})
-      arr_opts = []
-
-      arr_opts << '--all' if options[:all]
-      arr_opts << '--force' if options[:force]
-
-      arr_opts << '--'
+    def add(paths = '.', options = {})
+      args = build_args(options, ADD_OPTION_MAP)
 
-      arr_opts << paths
+      args << '--'
+      args.concat(Array(paths))
 
-      arr_opts.flatten!
-
-      command('add', *arr_opts)
+      command('add', *args)
     end
 
+    RM_OPTION_MAP = [
+      { type: :static, flag: '-f' },
+      { keys: [:recursive], flag: '-r',       type: :boolean },
+      { keys: [:cached],    flag: '--cached', type: :boolean }
+    ].freeze
+
     def rm(path = '.', opts = {})
-      arr_opts = ['-f']  # overrides the up-to-date check by default
-      arr_opts << '-r' if opts[:recursive]
-      arr_opts << '--cached' if opts[:cached]
-      arr_opts << '--'
-      arr_opts += Array(path)
+      args = build_args(opts, RM_OPTION_MAP)
 
-      command('rm', *arr_opts)
+      args << '--'
+      args.concat(Array(path))
+
+      command('rm', *args)
     end
 
     # Returns true if the repository is empty (meaning it has no commits)
@@ -1061,10 +1076,32 @@ module Git
       false
     rescue Git::FailedError => e
       raise unless e.result.status.exitstatus == 128 &&
-        e.result.stderr == 'fatal: Needed a single revision'
+                   e.result.stderr == 'fatal: Needed a single revision'
+
       true
     end
 
+    COMMIT_OPTION_MAP = [
+      { keys: %i[add_all all], flag: '--all', type: :boolean },
+      { keys: [:allow_empty],         flag: '--allow-empty',         type: :boolean },
+      { keys: [:no_verify],           flag: '--no-verify',           type: :boolean },
+      { keys: [:allow_empty_message], flag: '--allow-empty-message', type: :boolean },
+      { keys: [:author],              flag: '--author',              type: :valued_equals },
+      { keys: [:message],             flag: '--message',             type: :valued_equals },
+      { keys: [:no_gpg_sign],         flag: '--no-gpg-sign',         type: :boolean },
+      { keys: [:date], flag: '--date', type: :valued_equals, validator: ->(v) { v.is_a?(String) } },
+      { keys: [:amend], type: :custom, builder: ->(value) { ['--amend', '--no-edit'] if value } },
+      {
+        keys: [:gpg_sign],
+        type: :custom,
+        builder: lambda { |value|
+          if value
+            value == true ? '--gpg-sign' : "--gpg-sign=#{value}"
+          end
+        }
+      }
+    ].freeze
+
     # Takes the commit message with the options and executes the commit command
     #
     # accepts options:
@@ -1080,59 +1117,52 @@ module Git
     #
     # @param [String] message the commit message to be used
     # @param [Hash] opts the commit options to be used
+
     def commit(message, opts = {})
-      arr_opts = []
-      arr_opts << "--message=#{message}" if message
-      arr_opts << '--amend' << '--no-edit' if opts[:amend]
-      arr_opts << '--all' if opts[:add_all] || opts[:all]
-      arr_opts << '--allow-empty' if opts[:allow_empty]
-      arr_opts << "--author=#{opts[:author]}" if opts[:author]
-      arr_opts << "--date=#{opts[:date]}" if opts[:date].is_a? String
-      arr_opts << '--no-verify' if opts[:no_verify]
-      arr_opts << '--allow-empty-message' if opts[:allow_empty_message]
-
-      if opts[:gpg_sign] && opts[:no_gpg_sign]
-        raise ArgumentError, 'cannot specify :gpg_sign and :no_gpg_sign'
-      elsif opts[:gpg_sign]
-        arr_opts <<
-          if opts[:gpg_sign] == true
-            '--gpg-sign'
-          else
-            "--gpg-sign=#{opts[:gpg_sign]}"
-          end
-      elsif opts[:no_gpg_sign]
-        arr_opts << '--no-gpg-sign'
-      end
+      opts[:message] = message if message # Handle message arg for backward compatibility
+
+      # Perform cross-option validation before building args
+      raise ArgumentError, 'cannot specify :gpg_sign and :no_gpg_sign' if opts[:gpg_sign] && opts[:no_gpg_sign]
 
-      command('commit', *arr_opts)
+      ArgsBuilder.validate!(opts, COMMIT_OPTION_MAP)
+
+      args = build_args(opts, COMMIT_OPTION_MAP)
+      command('commit', *args)
     end
+    RESET_OPTION_MAP = [
+      { keys: [:hard], flag: '--hard', type: :boolean }
+    ].freeze
 
     def reset(commit, opts = {})
-      arr_opts = []
-      arr_opts << '--hard' if opts[:hard]
-      arr_opts << commit if commit
-      command('reset', *arr_opts)
+      args = build_args(opts, RESET_OPTION_MAP)
+      args << commit if commit
+      command('reset', *args)
     end
 
-    def clean(opts = {})
-      arr_opts = []
-      arr_opts << '--force' if opts[:force]
-      arr_opts << '-ff' if opts[:ff]
-      arr_opts << '-d' if opts[:d]
-      arr_opts << '-x' if opts[:x]
+    CLEAN_OPTION_MAP = [
+      { keys: [:force], flag: '--force', type: :boolean },
+      { keys: [:ff],    flag: '-ff',     type: :boolean },
+      { keys: [:d],     flag: '-d',      type: :boolean },
+      { keys: [:x],     flag: '-x',      type: :boolean }
+    ].freeze
 
-      command('clean', *arr_opts)
+    def clean(opts = {})
+      args = build_args(opts, CLEAN_OPTION_MAP)
+      command('clean', *args)
     end
 
+    REVERT_OPTION_MAP = [
+      { keys: [:no_edit], flag: '--no-edit', type: :boolean }
+    ].freeze
+
     def revert(commitish, opts = {})
       # Forcing --no-edit as default since it's not an interactive session.
-      opts = {:no_edit => true}.merge(opts)
+      opts = { no_edit: true }.merge(opts)
 
-      arr_opts = []
-      arr_opts << '--no-edit' if opts[:no_edit]
-      arr_opts << commitish
+      args = build_args(opts, REVERT_OPTION_MAP)
+      args << commitish
 
-      command('revert', *arr_opts)
+      command('revert', *args)
     end
 
     def apply(patch_file)
@@ -1148,19 +1178,9 @@ module Git
     end
 
     def stashes_all
-      arr = []
-      filename = File.join(@git_dir, 'logs/refs/stash')
-      if File.exist?(filename)
-        File.open(filename) do |f|
-          f.each_with_index do |line, i|
-            _, msg = line.split("\t")
-            # NOTE this logic may be removed/changed in 3.x
-            m = msg.match(/^[^:]+:(.*)$/)
-            arr << [i, (m ? m[1] : msg).strip]
-          end
-        end
+      stash_log_lines.each_with_index.map do |line, index|
+        parse_stash_log_line(line, index)
       end
-      arr
     end
 
     def stash_save(message)
@@ -1192,6 +1212,12 @@ module Git
       command('branch', '-D', branch)
     end
 
+    CHECKOUT_OPTION_MAP = [
+      { keys: %i[force f],      flag: '--force', type: :boolean },
+      { keys: %i[new_branch b], type: :validate_only },
+      { keys: [:start_point], type: :validate_only }
+    ].freeze
+
     # Runs checkout command to checkout or create branch
     #
     # accepts options:
@@ -1202,18 +1228,16 @@ module Git
     # @param [String] branch
     # @param [Hash] opts
     def checkout(branch = nil, opts = {})
-      if branch.is_a?(Hash) && opts == {}
+      if branch.is_a?(Hash) && opts.empty?
         opts = branch
         branch = nil
       end
+      ArgsBuilder.validate!(opts, CHECKOUT_OPTION_MAP)
 
-      arr_opts = []
-      arr_opts << '-b' if opts[:new_branch] || opts[:b]
-      arr_opts << '--force' if opts[:force] || opts[:f]
-      arr_opts << branch if branch
-      arr_opts << opts[:start_point] if opts[:start_point] && arr_opts.include?('-b')
+      flags = build_args(opts, CHECKOUT_OPTION_MAP)
+      positional_args = build_checkout_positional_args(branch, opts)
 
-      command('checkout', *arr_opts)
+      command('checkout', *flags, *positional_args)
     end
 
     def checkout_file(version, file)
@@ -1223,63 +1247,74 @@ module Git
       command('checkout', *arr_opts)
     end
 
+    MERGE_OPTION_MAP = [
+      { keys: [:no_commit], flag: '--no-commit', type: :boolean },
+      { keys: [:no_ff],     flag: '--no-ff',     type: :boolean },
+      { keys: [:m],         flag: '-m',          type: :valued_space }
+    ].freeze
+
     def merge(branch, message = nil, opts = {})
-      arr_opts = []
-      arr_opts << '--no-commit' if opts[:no_commit]
-      arr_opts << '--no-ff' if opts[:no_ff]
-      arr_opts << '-m' << message if message
-      arr_opts += Array(branch)
-      command('merge', *arr_opts)
+      # For backward compatibility, treat the message arg as the :m option.
+      opts[:m] = message if message
+      ArgsBuilder.validate!(opts, MERGE_OPTION_MAP)
+
+      args = build_args(opts, MERGE_OPTION_MAP)
+      args.concat(Array(branch))
+
+      command('merge', *args)
     end
 
+    MERGE_BASE_OPTION_MAP = [
+      { keys: [:octopus],     flag: '--octopus',     type: :boolean },
+      { keys: [:independent], flag: '--independent', type: :boolean },
+      { keys: [:fork_point],  flag: '--fork-point',  type: :boolean },
+      { keys: [:all],         flag: '--all',         type: :boolean }
+    ].freeze
+
     def merge_base(*args)
       opts = args.last.is_a?(Hash) ? args.pop : {}
+      ArgsBuilder.validate!(opts, MERGE_BASE_OPTION_MAP)
 
-      arg_opts = []
-
-      arg_opts << '--octopus' if opts[:octopus]
-      arg_opts << '--independent' if opts[:independent]
-      arg_opts << '--fork-point' if opts[:fork_point]
-      arg_opts << '--all' if opts[:all]
+      flags = build_args(opts, MERGE_BASE_OPTION_MAP)
+      command_args = flags + args
 
-      arg_opts += args
-
-      command('merge-base', *arg_opts).lines.map(&:strip)
+      command('merge-base', *command_args).lines.map(&:strip)
     end
 
     def unmerged
       unmerged = []
-      command_lines('diff', "--cached").each do |line|
-        unmerged << $1 if line =~ /^\* Unmerged path (.*)/
+      command_lines('diff', '--cached').each do |line|
+        unmerged << ::Regexp.last_match(1) if line =~ /^\* Unmerged path (.*)/
       end
       unmerged
     end
 
     def conflicts # :yields: file, your, their
-      self.unmerged.each do |f|
-        Tempfile.create("YOUR-#{File.basename(f)}") do |your|
-          command('show', ":2:#{f}", out: your)
-          your.close
-
-          Tempfile.create("THEIR-#{File.basename(f)}") do |their|
-            command('show', ":3:#{f}", out: their)
-            their.close
+      unmerged.each do |file_path|
+        Tempfile.create(['YOUR-', File.basename(file_path)]) do |your_file|
+          write_staged_content(file_path, 2, your_file).flush
 
-            yield(f, your.path, their.path)
+          Tempfile.create(['THEIR-', File.basename(file_path)]) do |their_file|
+            write_staged_content(file_path, 3, their_file).flush
+            yield(file_path, your_file.path, their_file.path)
           end
         end
       end
     end
 
+    REMOTE_ADD_OPTION_MAP = [
+      { keys: %i[with_fetch fetch], flag: '-f', type: :boolean },
+      { keys: [:track], flag: '-t', type: :valued_space }
+    ].freeze
+
     def remote_add(name, url, opts = {})
-      arr_opts = ['add']
-      arr_opts << '-f' if opts[:with_fetch] || opts[:fetch]
-      arr_opts << '-t' << opts[:track] if opts[:track]
-      arr_opts << '--'
-      arr_opts << name
-      arr_opts << url
+      ArgsBuilder.validate!(opts, REMOTE_ADD_OPTION_MAP)
 
-      command('remote', *arr_opts)
+      flags = build_args(opts, REMOTE_ADD_OPTION_MAP)
+      positional_args = ['--', name, url]
+      command_args = ['add'] + flags + positional_args
+
+      command('remote', *command_args)
     end
 
     def remote_set_url(name, url)
@@ -1302,93 +1337,90 @@ module Git
       command_lines('tag')
     end
 
-    def tag(name, *opts)
-      target = opts[0].instance_of?(String) ? opts[0] : nil
-
-      opts = opts.last.instance_of?(Hash) ? opts.last : {}
+    TAG_OPTION_MAP = [
+      { keys: %i[force f],       flag: '-f', type: :boolean },
+      { keys: %i[annotate a],    flag: '-a', type: :boolean },
+      { keys: %i[sign s],        flag: '-s', type: :boolean },
+      { keys: %i[delete d],      flag: '-d', type: :boolean },
+      { keys: %i[message m],     flag: '-m', type: :valued_space }
+    ].freeze
 
-      if (opts[:a] || opts[:annotate]) && !(opts[:m] || opts[:message])
-        raise  ArgumentError, 'Cannot create an annotated tag without a message.'
-      end
-
-      arr_opts = []
+    def tag(name, *args)
+      opts = args.last.is_a?(Hash) ? args.pop : {}
+      target = args.first
 
-      arr_opts << '-f' if opts[:force] || opts[:f]
-      arr_opts << '-a' if opts[:a] || opts[:annotate]
-      arr_opts << '-s' if opts[:s] || opts[:sign]
-      arr_opts << '-d' if opts[:d] || opts[:delete]
-      arr_opts << name
-      arr_opts << target if target
+      validate_tag_options!(opts)
+      ArgsBuilder.validate!(opts, TAG_OPTION_MAP)
 
-      if opts[:m] || opts[:message]
-        arr_opts << '-m' << (opts[:m] || opts[:message])
-      end
+      flags = build_args(opts, TAG_OPTION_MAP)
+      positional_args = [name, target].compact
 
-      command('tag', *arr_opts)
+      command('tag', *flags, *positional_args)
     end
 
-    def fetch(remote, opts)
-      arr_opts = []
-      arr_opts << '--all' if opts[:all]
-      arr_opts << '--tags' if opts[:t] || opts[:tags]
-      arr_opts << '--prune' if opts[:p] || opts[:prune]
-      arr_opts << '--prune-tags' if opts[:P] || opts[:'prune-tags']
-      arr_opts << '--force' if opts[:f] || opts[:force]
-      arr_opts << '--update-head-ok' if opts[:u] || opts[:'update-head-ok']
-      arr_opts << '--unshallow' if opts[:unshallow]
-      arr_opts << '--depth' << opts[:depth] if opts[:depth]
-      arr_opts << '--' if remote || opts[:ref]
-      arr_opts << remote if remote
-      arr_opts << opts[:ref] if opts[:ref]
-
-      command('fetch', *arr_opts, merge: true)
-    end
+    FETCH_OPTION_MAP = [
+      { keys: [:all], flag: '--all', type: :boolean },
+      { keys: %i[tags t],            flag: '--tags',           type: :boolean },
+      { keys: %i[prune p],           flag: '--prune',          type: :boolean },
+      { keys: %i[prune-tags P], flag: '--prune-tags', type: :boolean },
+      { keys: %i[force f], flag: '--force', type: :boolean },
+      { keys: %i[update-head-ok u], flag: '--update-head-ok', type: :boolean },
+      { keys: [:unshallow],           flag: '--unshallow',      type: :boolean },
+      { keys: [:depth],               flag: '--depth',          type: :valued_space },
+      { keys: [:ref],                 type: :validate_only }
+    ].freeze
 
-    def push(remote = nil, branch = nil, opts = nil)
-      if opts.nil? && branch.instance_of?(Hash)
-        opts = branch
-        branch = nil
-      end
+    def fetch(remote, opts)
+      ArgsBuilder.validate!(opts, FETCH_OPTION_MAP)
+      args = build_args(opts, FETCH_OPTION_MAP)
 
-      if opts.nil? && remote.instance_of?(Hash)
-        opts = remote
-        remote = nil
+      if remote || opts[:ref]
+        args << '--'
+        args << remote if remote
+        args << opts[:ref] if opts[:ref]
       end
 
-      opts ||= {}
+      command('fetch', *args, merge: true)
+    end
 
-      # Small hack to keep backwards compatibility with the 'push(remote, branch, tags)' method signature.
-      opts = {:tags => opts} if [true, false].include?(opts)
+    PUSH_OPTION_MAP = [
+      { keys: [:mirror],      flag: '--mirror',      type: :boolean },
+      { keys: [:delete],      flag: '--delete',      type: :boolean },
+      { keys: %i[force f], flag: '--force', type: :boolean },
+      { keys: [:push_option], flag: '--push-option', type: :repeatable_valued_space },
+      { keys: [:all],         type: :validate_only }, # For validation purposes
+      { keys: [:tags],        type: :validate_only }  # From the `push` method's logic
+    ].freeze
 
-      raise ArgumentError, "You must specify a remote if a branch is specified" if remote.nil? && !branch.nil?
+    def push(remote = nil, branch = nil, opts = nil)
+      remote, branch, opts = normalize_push_args(remote, branch, opts)
+      ArgsBuilder.validate!(opts, PUSH_OPTION_MAP)
 
-      arr_opts = []
-      arr_opts << '--mirror'  if opts[:mirror]
-      arr_opts << '--delete'  if opts[:delete]
-      arr_opts << '--force'   if opts[:force] || opts[:f]
-      arr_opts << '--all'     if opts[:all] && remote
+      raise ArgumentError, 'remote is required if branch is specified' if !remote && branch
 
-      Array(opts[:push_option]).each { |o| arr_opts << '--push-option' << o } if opts[:push_option]
-      arr_opts << remote if remote
-      arr_opts_with_branch = arr_opts.dup
-      arr_opts_with_branch << branch if branch
+      args = build_push_args(remote, branch, opts)
 
       if opts[:mirror]
-          command('push', *arr_opts_with_branch)
+        command('push', *args)
       else
-          command('push', *arr_opts_with_branch)
-          command('push', '--tags', *arr_opts) if opts[:tags]
+        command('push', *args)
+        command('push', '--tags', *(args - [branch].compact)) if opts[:tags]
       end
     end
 
+    PULL_OPTION_MAP = [
+      { keys: [:allow_unrelated_histories], flag: '--allow-unrelated-histories', type: :boolean }
+    ].freeze
+
     def pull(remote = nil, branch = nil, opts = {})
-      raise ArgumentError, "You must specify a remote if a branch is specified" if remote.nil? && !branch.nil?
+      raise ArgumentError, 'You must specify a remote if a branch is specified' if remote.nil? && !branch.nil?
 
-      arr_opts = []
-      arr_opts << '--allow-unrelated-histories' if opts[:allow_unrelated_histories]
-      arr_opts << remote if remote
-      arr_opts << branch if branch
-      command('pull', *arr_opts)
+      ArgsBuilder.validate!(opts, PULL_OPTION_MAP)
+
+      flags = build_args(opts, PULL_OPTION_MAP)
+      positional_args = [remote, branch].compact
+
+      command('pull', *flags, *positional_args)
     end
 
     def tag_sha(tag_name)
@@ -1396,7 +1428,7 @@ module Git
       return File.read(head).chomp if File.exist?(head)
 
       begin
-        command('show-ref',  '--tags', '-s', tag_name)
+        command('show-ref', '--tags', '-s', tag_name)
       rescue Git::FailedError => e
         raise unless e.result.status.exitstatus == 1 && e.result.stderr == ''
 
@@ -1412,82 +1444,77 @@ module Git
       command('gc', '--prune', '--aggressive', '--auto')
     end
 
-    # reads a tree into the current index file
+    READ_TREE_OPTION_MAP = [
+      { keys: [:prefix], flag: '--prefix', type: :valued_equals }
+    ].freeze
+
     def read_tree(treeish, opts = {})
-      arr_opts = []
-      arr_opts << "--prefix=#{opts[:prefix]}" if opts[:prefix]
-      arr_opts += [treeish]
-      command('read-tree', *arr_opts)
+      ArgsBuilder.validate!(opts, READ_TREE_OPTION_MAP)
+      flags = build_args(opts, READ_TREE_OPTION_MAP)
+      command('read-tree', *flags, treeish)
     end
 
     def write_tree
       command('write-tree')
     end
 
+    COMMIT_TREE_OPTION_MAP = [
+      { keys: %i[parent parents], flag: '-p', type: :repeatable_valued_space },
+      { keys: [:message], flag: '-m', type: :valued_space }
+    ].freeze
+
     def commit_tree(tree, opts = {})
       opts[:message] ||= "commit tree #{tree}"
-      arr_opts = []
-      arr_opts << tree
-      arr_opts << '-p' << opts[:parent] if opts[:parent]
-      Array(opts[:parents]).each { |p| arr_opts << '-p' << p } if opts[:parents]
-      arr_opts << '-m' << opts[:message]
-      command('commit-tree', *arr_opts)
+      ArgsBuilder.validate!(opts, COMMIT_TREE_OPTION_MAP)
+
+      flags = build_args(opts, COMMIT_TREE_OPTION_MAP)
+      command('commit-tree', tree, *flags)
     end
 
     def update_ref(ref, commit)
       command('update-ref', ref, commit)
     end
 
+    CHECKOUT_INDEX_OPTION_MAP = [
+      { keys: [:prefix], flag: '--prefix', type: :valued_equals },
+      { keys: [:force],  flag: '--force',  type: :boolean },
+      { keys: [:all],    flag: '--all',    type: :boolean },
+      { keys: [:path_limiter], type: :validate_only }
+    ].freeze
+
     def checkout_index(opts = {})
-      arr_opts = []
-      arr_opts << "--prefix=#{opts[:prefix]}" if opts[:prefix]
-      arr_opts << "--force" if opts[:force]
-      arr_opts << "--all" if opts[:all]
-      arr_opts << '--' << opts[:path_limiter] if opts[:path_limiter].is_a? String
+      ArgsBuilder.validate!(opts, CHECKOUT_INDEX_OPTION_MAP)
+      args = build_args(opts, CHECKOUT_INDEX_OPTION_MAP)
+
+      if (path = opts[:path_limiter]) && path.is_a?(String)
+        args.push('--', path)
+      end
 
-      command('checkout-index', *arr_opts)
+      command('checkout-index', *args)
     end
 
-    # creates an archive file
-    #
-    # options
-    #  :format  (zip, tar)
-    #  :prefix
-    #  :remote
-    #  :path
+    ARCHIVE_OPTION_MAP = [
+      { keys: [:prefix],     flag: '--prefix', type: :valued_equals },
+      { keys: [:remote],     flag: '--remote', type: :valued_equals },
+      # These options are used by helpers or handled manually
+      { keys: [:path],       type: :validate_only },
+      { keys: [:format],     type: :validate_only },
+      { keys: [:add_gzip],   type: :validate_only }
+    ].freeze
+
     def archive(sha, file = nil, opts = {})
-      opts[:format] ||= 'zip'
+      ArgsBuilder.validate!(opts, ARCHIVE_OPTION_MAP)
+      file ||= temp_file_name
+      format, gzip = parse_archive_format_options(opts)
 
-      if opts[:format] == 'tgz'
-        opts[:format] = 'tar'
-        opts[:add_gzip] = true
-      end
+      args = build_args(opts, ARCHIVE_OPTION_MAP)
+      args.unshift("--format=#{format}")
+      args << sha
+      args.push('--', opts[:path]) if opts[:path]
 
-      if !file
-        tempfile = Tempfile.new('archive')
-        file = tempfile.path
-        # delete it now, before we write to it, so that Ruby doesn't delete it
-        # when it finalizes the Tempfile.
-        tempfile.close!
-      end
+      File.open(file, 'wb') { |f| command('archive', *args, out: f) }
+      apply_gzip(file) if gzip
 
-      arr_opts = []
-      arr_opts << "--format=#{opts[:format]}" if opts[:format]
-      arr_opts << "--prefix=#{opts[:prefix]}" if opts[:prefix]
-      arr_opts << "--remote=#{opts[:remote]}" if opts[:remote]
-      arr_opts << sha
-      arr_opts << '--' << opts[:path] if opts[:path]
-
-      f = File.open(file, 'wb')
-      command('archive', *arr_opts, out: f)
-      f.close
-
-      if opts[:add_gzip]
-        file_content = File.read(file)
-        Zlib::GzipWriter.open(file) do |gz|
-          gz.write(file_content)
-        end
-      end
       file
     end
 
@@ -1495,7 +1522,7 @@ module Git
     def current_command_version
       output = command('version')
       version = output[/\d+(\.\d+)+/]
-      version_parts = version.split('.').collect { |i| i.to_i }
+      version_parts = version.split('.').collect(&:to_i)
       version_parts.fill(0, version_parts.length...3)
     end
 
@@ -1520,27 +1547,331 @@ module Git
     end
 
     def meets_required_version?
-      (self.current_command_version <=>  self.required_command_version) >= 0
+      (current_command_version <=> required_command_version) >= 0
     end
 
-    def self.warn_if_old_command(lib)
+    def self.warn_if_old_command(lib) # rubocop:disable Naming/PredicateMethod
+      Git::Deprecation.warn('Git::Lib#warn_if_old_command is deprecated. Use meets_required_version?.')
+
       return true if @version_checked
+
       @version_checked = true
       unless lib.meets_required_version?
-        $stderr.puts "[WARNING] The git gem requires git #{lib.required_command_version.join('.')} or later, but only found #{lib.current_command_version.join('.')}. You should probably upgrade."
+        warn "[WARNING] The git gem requires git #{lib.required_command_version.join('.')} or later, " \
+             "but only found #{lib.current_command_version.join('.')}. You should probably upgrade."
       end
       true
     end
 
+    COMMAND_ARG_DEFAULTS = {
+      out: nil,
+      err: nil,
+      normalize: true,
+      chomp: true,
+      merge: false,
+      chdir: nil,
+      timeout: nil # Don't set to Git.config.timeout here since it is mutable
+    }.freeze
+
+    STATIC_GLOBAL_OPTS = %w[
+      -c core.quotePath=true
+      -c color.ui=false
+      -c color.advice=false
+      -c color.diff=false
+      -c color.grep=false
+      -c color.push=false
+      -c color.remote=false
+      -c color.showBranch=false
+      -c color.status=false
+      -c color.transport=false
+    ].freeze
+
+    LOG_OPTION_MAP = [
+      { type: :static, flag: '--no-color' },
+      { keys: [:all],    flag: '--all',    type: :boolean },
+      { keys: [:cherry], flag: '--cherry', type: :boolean },
+      { keys: [:since],  flag: '--since',     type: :valued_equals },
+      { keys: [:until],  flag: '--until',     type: :valued_equals },
+      { keys: [:grep],   flag: '--grep',      type: :valued_equals },
+      { keys: [:author], flag: '--author',    type: :valued_equals },
+      { keys: [:count],  flag: '--max-count', type: :valued_equals },
+      { keys: [:between], type: :custom, builder: ->(value) { "#{value[0]}..#{value[1]}" if value } }
+    ].freeze
+
     private
 
+    def parse_diff_path_status(args)
+      command_lines('diff', *args).each_with_object({}) do |line, memo|
+        status, path = line.split("\t")
+        memo[path] = status
+      end
+    end
+
+    def build_checkout_positional_args(branch, opts)
+      args = []
+      if opts[:new_branch] || opts[:b]
+        args.push('-b', branch)
+        args << opts[:start_point] if opts[:start_point]
+      elsif branch
+        args << branch
+      end
+      args
+    end
+
+    def build_args(opts, option_map)
+      Git::ArgsBuilder.new(opts, option_map).build
+    end
+
+    def initialize_from_base(base_object)
+      @git_dir = base_object.repo.path
+      @git_index_file = base_object.index&.path
+      @git_work_dir = base_object.dir&.path
+    end
+
+    def initialize_from_hash(base_hash)
+      @git_dir = base_hash[:repository]
+      @git_index_file = base_hash[:index]
+      @git_work_dir = base_hash[:working_directory]
+    end
+
+    def return_base_opts_from_clone(clone_dir, opts)
+      base_opts = {}
+      base_opts[:repository] = clone_dir if opts[:bare] || opts[:mirror]
+      base_opts[:working_directory] = clone_dir unless opts[:bare] || opts[:mirror]
+      base_opts[:log] = opts[:log] if opts[:log]
+      base_opts
+    end
+
+    def process_commit_headers(data)
+      headers = { 'parent' => [] } # Pre-initialize for multiple parents
+      each_cat_file_header(data) do |key, value|
+        if key == 'parent'
+          headers['parent'] << value
+        else
+          headers[key] = value
+        end
+      end
+      headers
+    end
+
+    def parse_branch_line(line, index, all_lines)
+      match_data = match_branch_line(line, index, all_lines)
+
+      return nil if match_data[:not_a_branch] || match_data[:detached_ref]
+
+      format_branch_data(match_data)
+    end
+
+    def match_branch_line(line, index, all_lines)
+      match_data = line.match(BRANCH_LINE_REGEXP)
+      raise Git::UnexpectedResultError, unexpected_branch_line_error(all_lines, line, index) unless match_data
+
+      match_data
+    end
+
+    def format_branch_data(match_data)
+      [
+        match_data[:refname],
+        !match_data[:current].nil?,
+        !match_data[:worktree].nil?,
+        match_data[:symref]
+      ]
+    end
+
+    def unexpected_branch_line_error(lines, line, index)
+      <<~ERROR
+        Unexpected line in output from `git branch -a`, line #{index + 1}
+
+        Full output:
+          #{lines.join("\n  ")}
+
+        Line #{index + 1}:
+          "#{line}"
+      ERROR
+    end
+
+    def get_branch_state(branch_name)
+      command('rev-parse', '--verify', '--quiet', branch_name)
+      :active
+    rescue Git::FailedError => e
+      # An exit status of 1 with empty stderr from `rev-parse --verify`
+      # indicates a ref that exists but does not yet point to a commit.
+      raise unless e.result.status.exitstatus == 1 && e.result.stderr.empty?
+
+      :unborn
+    end
+
+    def execute_grep_command(args)
+      command_lines('grep', *args)
+    rescue Git::FailedError => e
+      # `git grep` returns 1 when no lines are selected.
+      raise unless e.result.status.exitstatus == 1 && e.result.stderr.empty?
+
+      [] # Return an empty array for "no matches found"
+    end
+
+    def parse_grep_output(lines)
+      lines.each_with_object(Hash.new { |h, k| h[k] = [] }) do |line, hsh|
+        match = line.match(/\A(.*?):(\d+):(.*)/)
+        next unless match
+
+        _full, filename, line_num, text = match.to_a
+        hsh[filename] << [line_num.to_i, text]
+      end
+    end
+
+    def parse_diff_stats_output(lines)
+      file_stats = parse_stat_lines(lines)
+      build_final_stats_hash(file_stats)
+    end
+
+    def parse_stat_lines(lines)
+      lines.map do |line|
+        insertions_s, deletions_s, filename = line.split("\t")
+        {
+          filename: filename,
+          insertions: insertions_s.to_i,
+          deletions: deletions_s.to_i
+        }
+      end
+    end
+
+    def build_final_stats_hash(file_stats)
+      {
+        total: build_total_stats(file_stats),
+        files: build_files_hash(file_stats)
+      }
+    end
+
+    def build_total_stats(file_stats)
+      insertions = file_stats.sum { |s| s[:insertions] }
+      deletions = file_stats.sum { |s| s[:deletions] }
+      {
+        insertions: insertions,
+        deletions: deletions,
+        lines: insertions + deletions,
+        files: file_stats.size
+      }
+    end
+
+    def build_files_hash(file_stats)
+      file_stats.to_h { |s| [s[:filename], s.slice(:insertions, :deletions)] }
+    end
+
+    def parse_ls_remote_output(lines)
+      lines.each_with_object(Hash.new { |h, k| h[k] = {} }) do |line, hsh|
+        type, name, value = parse_ls_remote_line(line)
+        if name
+          hsh[type][name] = value
+        else # Handles the HEAD entry, which has no name
+          hsh[type].update(value)
+        end
+      end
+    end
+
+    def parse_ls_remote_line(line)
+      sha, info = line.split("\t", 2)
+      ref, type, name = info.split('/', 3)
+
+      type ||= 'head'
+      type = 'branches' if type == 'heads'
+
+      value = { ref: ref, sha: sha }
+
+      [type, name, value]
+    end
+
+    def stash_log_lines
+      path = File.join(@git_dir, 'logs/refs/stash')
+      return [] unless File.exist?(path)
+
+      File.readlines(path, chomp: true)
+    end
+
+    def parse_stash_log_line(line, index)
+      full_message = line.split("\t", 2).last
+      match_data = full_message.match(/^[^:]+:(.*)$/)
+      message = match_data ? match_data[1] : full_message
+
+      [index, message.strip]
+    end
+
+    # Writes the staged content of a conflicted file to an IO stream
+    #
+    # @param path [String] the path to the file in the index
+    #
+    # @param stage [Integer] the stage of the file to show (e.g., 2 for 'ours', 3 for 'theirs')
+    #
+    # @param out_io [IO] the IO object to write the staged content to
+    #
+    # @return [IO] the IO object that was written to
+    #
+    def write_staged_content(path, stage, out_io)
+      command('show', ":#{stage}:#{path}", out: out_io)
+      out_io
+    end
+
+    def validate_tag_options!(opts)
+      is_annotated = opts[:a] || opts[:annotate]
+      has_message = opts[:m] || opts[:message]
+
+      return unless is_annotated && !has_message
+
+      raise ArgumentError, 'Cannot create an annotated tag without a message.'
+    end
+
+    def normalize_push_args(remote, branch, opts)
+      if branch.is_a?(Hash)
+        opts = branch
+        branch = nil
+      elsif remote.is_a?(Hash)
+        opts = remote
+        remote = nil
+      end
+
+      opts ||= {}
+      # Backwards compatibility for `push(remote, branch, true)`
+      opts = { tags: opts } if [true, false].include?(opts)
+      [remote, branch, opts]
+    end
+
+    def build_push_args(remote, branch, opts)
+      # Build the simple flags using the ArgsBuilder
+      args = build_args(opts, PUSH_OPTION_MAP)
+
+      # Manually handle the flag with external dependencies and positional args
+      args << '--all' if opts[:all] && remote
+      args << remote if remote
+      args << branch if branch
+      args
+    end
+
+    def temp_file_name
+      tempfile = Tempfile.new('archive')
+      file = tempfile.path
+      tempfile.close! # Prevents Ruby from deleting the file on garbage collection
+      file
+    end
+
+    def parse_archive_format_options(opts)
+      format = opts[:format] || 'zip'
+      gzip = opts[:add_gzip] == true || format == 'tgz'
+      format = 'tar' if format == 'tgz'
+      [format, gzip]
+    end
+
+    def apply_gzip(file)
+      file_content = File.read(file)
+      Zlib::GzipWriter.open(file) { |gz| gz.write(file_content) }
+    end
+
     def command_lines(cmd, *opts, chdir: nil)
       cmd_op = command(cmd, *opts, chdir: chdir)
-      if cmd_op.encoding.name != "UTF-8"
-        op = cmd_op.encode("UTF-8", "binary", :invalid => :replace, :undef => :replace)
-      else
-        op = cmd_op
-      end
+      op = if cmd_op.encoding.name == 'UTF-8'
+             cmd_op
+           else
+             cmd_op.encode('UTF-8', 'binary', invalid: :replace, undef: :replace)
+           end
       op.split("\n")
     end
 
@@ -1555,19 +1886,10 @@ module Git
     end
 
     def global_opts
-      Array.new.tap do |global_opts|
-        global_opts << "--git-dir=#{@git_dir}" if !@git_dir.nil?
-        global_opts << "--work-tree=#{@git_work_dir}" if !@git_work_dir.nil?
-        global_opts << '-c' << 'core.quotePath=true'
-        global_opts << '-c' << 'color.ui=false'
-        global_opts << '-c' << 'color.advice=false'
-        global_opts << '-c' << 'color.diff=false'
-        global_opts << '-c' << 'color.grep=false'
-        global_opts << '-c' << 'color.push=false'
-        global_opts << '-c' << 'color.remote=false'
-        global_opts << '-c' << 'color.showBranch=false'
-        global_opts << '-c' << 'color.status=false'
-        global_opts << '-c' << 'color.transport=false'
+      [].tap do |global_opts|
+        global_opts << "--git-dir=#{@git_dir}" unless @git_dir.nil?
+        global_opts << "--work-tree=#{@git_work_dir}" unless @git_work_dir.nil?
+        global_opts.concat(STATIC_GLOBAL_OPTS)
       end
     end
 
@@ -1578,28 +1900,21 @@ module Git
 
     # Runs a git command and returns the output
     #
-    # @param args [Array] the git command to run and its arguments
-    #
-    #   This should exclude the 'git' command itself and global options.
-    #
-    #   For example, to run `git log --pretty=oneline`, you would pass `['log',
-    #   '--pretty=oneline']`
-    #
-    # @param out [String, nil] the path to a file or an IO to write the command's
-    #   stdout to
-    #
-    # @param err [String, nil] the path to a file or an IO to write the command's
-    #   stdout to
-    #
-    # @param normalize [Boolean] true to normalize the output encoding
-    #
-    # @param chomp [Boolean] true to remove trailing newlines from the output
-    #
-    # @param merge [Boolean] true to merge stdout and stderr
+    # Additional args are passed to the command line. They should exclude the 'git'
+    # command itself and global options. Remember to splat the the arguments if given
+    # as an array.
     #
-    # @param chdir [String, nil] the directory to run the command in
+    # For example, to run `git log --pretty=oneline`, you would create the array
+    # `args = ['log', '--pretty=oneline']` and call `command(*args)`.
     #
-    # @param timeout [Numeric, nil] the maximum seconds to wait for the command to complete
+    # @param options_hash [Hash] the options to pass to the command
+    # @option options_hash [IO, String, #write, nil] :out the destination for captured stdout
+    # @option options_hash [IO, String, #write, nil] :err the destination for captured stderr
+    # @option options_hash [Boolean] :normalize true to normalize the output encoding to UTF-8
+    # @option options_hash [Boolean] :chomp true to remove trailing newlines from the output
+    # @option options_hash [Boolean] :merge true to merge stdout and stderr into a single output
+    # @option options_hash [String, nil] :chdir the directory to run the command in
+    # @option options_hash [Numeric, nil] :timeout the maximum seconds to wait for the command to complete
     #
     #   If timeout is nil, the global timeout from {Git::Config} is used.
     #
@@ -1614,9 +1929,14 @@ module Git
     # @return [String] the command's stdout (or merged stdout and stderr if `merge`
     # is true)
     #
+    # @raise [ArgumentError] if an unknown option is passed
+    #
     # @raise [Git::FailedError] if the command failed
+    #
     # @raise [Git::SignaledError] if the command was signaled
+    #
     # @raise [Git::TimeoutError] if the command times out
+    #
     # @raise [Git::ProcessIOError] if an exception was raised while collecting subprocess output
     #
     #   The exception's `result` attribute is a {Git::CommandLineResult} which will
@@ -1625,9 +1945,14 @@ module Git
     #
     # @api private
     #
-    def command(*args, out: nil, err: nil, normalize: true, chomp: true, merge: false, chdir: nil, timeout: nil)
-      timeout = timeout || Git.config.timeout
-      result = command_line.run(*args, out: out, err: err, normalize: normalize, chomp: chomp, merge: merge, chdir: chdir, timeout: timeout)
+    def command(*, **options_hash)
+      options_hash = COMMAND_ARG_DEFAULTS.merge(options_hash)
+      options_hash[:timeout] ||= Git.config.timeout
+
+      extra_options = options_hash.keys - COMMAND_ARG_DEFAULTS.keys
+      raise ArgumentError, "Unknown options: #{extra_options.join(', ')}" if extra_options.any?
+
+      result = command_line.run(*, **options_hash)
       result.stdout
     end
 
@@ -1636,23 +1961,18 @@ module Git
     # @param [String] diff_command the diff commadn to be used
     # @param [Array] opts the diff options to be used
     # @return [Hash] the diff as Hash
-    def diff_as_hash(diff_command, opts=[])
+    def diff_as_hash(diff_command, opts = [])
       # update index before diffing to avoid spurious diffs
       command('status')
-      command_lines(diff_command, *opts).inject({}) do |memo, line|
+      command_lines(diff_command, *opts).each_with_object({}) do |line, memo|
         info, file = line.split("\t")
         mode_src, mode_dest, sha_src, sha_dest, type = info.split
 
         memo[file] = {
-          :mode_index => mode_dest,
-          :mode_repo => mode_src.to_s[1, 7],
-          :path => file,
-          :sha_repo => sha_src,
-          :sha_index => sha_dest,
-          :type => type
+          mode_index: mode_dest, mode_repo: mode_src.to_s[1, 7],
+          path: file, sha_repo: sha_src, sha_index: sha_dest,
+          type: type
         }
-
-        memo
       end
     end
 
@@ -1661,23 +1981,11 @@ module Git
     # @param [Hash] opts the given options
     # @return [Array] the set of common options that the log command will use
     def log_common_options(opts)
-      arr_opts = []
-
       if opts[:count] && !opts[:count].is_a?(Integer)
         raise ArgumentError, "The log count option must be an Integer but was #{opts[:count].inspect}"
       end
 
-      arr_opts << "--max-count=#{opts[:count]}" if opts[:count]
-      arr_opts << "--all" if opts[:all]
-      arr_opts << "--no-color"
-      arr_opts << "--cherry" if opts[:cherry]
-      arr_opts << "--since=#{opts[:since]}" if opts[:since].is_a? String
-      arr_opts << "--until=#{opts[:until]}" if opts[:until].is_a? String
-      arr_opts << "--grep=#{opts[:grep]}" if opts[:grep].is_a? String
-      arr_opts << "--author=#{opts[:author]}" if opts[:author].is_a? String
-      arr_opts << "#{opts[:between][0].to_s}..#{opts[:between][1].to_s}" if (opts[:between] && opts[:between].size == 2)
-
-      arr_opts
+      build_args(opts, LOG_OPTION_MAP)
     end
 
     # Retrurns an array holding path options for the log commands