git 4.3.1 → 5.0.0.beta.1

data/lib/git/lib.rb

@@ -1,9 +1,16 @@
 # frozen_string_literal: true
 
 require_relative 'args_builder'
+require_relative 'commands'
 
 require 'git/command_line'
 require 'git/errors'
+require 'git/parsers/branch'
+require 'git/parsers/fsck'
+require 'git/parsers/grep'
+require 'git/parsers/stash'
+require 'git/parsers/tag'
+require 'git/url'
 require 'logger'
 require 'pathname'
 require 'pp'
@@ -11,12 +18,15 @@ require 'process_executer'
 require 'stringio'
 require 'tempfile'
 require 'zlib'
-require 'open3'
 
 module Git
   # Internal git operations
   # @api private
   class Lib
+    # Thread-safe cache for git versions, keyed by binary path
+    @git_version_cache_mutex = Mutex.new
+    @git_version_cache = {}
+
     # The path to the Git working copy.  The default is '"./.git"'.
     #
     # @return [Pathname] the path to the Git working copy.
@@ -75,52 +85,29 @@ module Git
       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
+    # Creates or reinitializes the repository in the current directory
+    #
+    # This is a low-level method that just runs `git init` with the given options.
+    # For full repository initialization including directory creation and path
+    # resolution, use Git.init instead.
+    #
+    # @param opts [Hash] command options
+    #
+    # @option opts [Boolean, nil] :bare (nil) create a bare repository
+    #
+    # @option opts [String, nil] :initial_branch (nil) use the specified name for the initial branch
+    #
+    # @option opts [String, nil] :separate_git_dir (nil) path to put the .git directory (`--separate-git-dir`)
     #
-    # options:
-    #   :bare
-    #   :working_directory
-    #   :initial_branch
+    # @option opts [String, nil] :repository (nil) deprecated — use `:separate_git_dir` instead
+    #
+    # @return [String] the command output
     #
     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: [:single_branch],
-        type: :custom,
-        validator: ->(value) { [nil, true, false].include?(value) },
-        builder: lambda do |value|
-          case value
-          when true
-            ['--single-branch']
-          when false
-            ['--no-single-branch']
-          else
-            []
-          end
-        end
-      },
-      {
-        keys: [:depth],
-        type: :custom,
-        builder: ->(value) { ['--depth', value.to_i] if value }
-      }
-    ].freeze
+      opts = opts.dup
+      opts[:separate_git_dir] ||= opts.delete(:repository)
+      Git::Commands::Init.new(self).call(**opts).stdout
+    end
 
     # Clones a repository into a newly created directory
     #
@@ -133,28 +120,42 @@ module Git
     #
     # @param [Hash] opts the options for this command
     #
-    # @option opts [Boolean] :bare (false) if true, clone as a bare repository
+    # @option opts [Boolean, nil] :bare (nil) if true, clone as a bare repository
     #
-    # @option opts [String] :branch the branch to checkout
+    # @option opts [String, nil] :branch (nil) the branch to checkout
     #
-    # @option opts [String, Array] :config one or more configuration options to set
+    # @option opts [String, Array<String>, nil] :config (nil) one or more configuration options to set
     #
-    # @option opts [Integer] :depth the number of commits back to pull
+    # @option opts [Integer, nil] :depth (nil) the number of commits back to pull
     #
-    # @option opts [String] :filter specify partial clone
+    # @option opts [String, nil] :filter (nil) specify partial clone
     #
-    # @option opts [String] :mirror set up a mirror of the source repository
+    # @option opts [String, nil] :git_ssh (nil) SSH command or binary to use for git over SSH
     #
-    # @option opts [String] :origin the name of the remote
+    # @option opts [Logger, nil] :log (nil) Logger instance to use for git operations
     #
-    # @option opts [String] :path an optional prefix for the directory parameter
+    # @option opts [Boolean, nil] :mirror (nil) set up a mirror of the source repository
     #
-    # @option opts [String] :remote the name of the remote
+    # @option opts [String, nil] :origin (nil) the name of the remote
     #
-    # @option opts [Boolean] :recursive after the clone is created, initialize all
-    #    within, using their default settings
+    # @option opts [String, nil] :chdir (nil) run `git clone` from this directory
     #
-    # @option opts [Numeric, nil] :timeout the number of seconds to wait for the
+    #   When given, `directory` (or the repository basename when `directory` is nil)
+    #   is resolved relative to `:chdir`, just as if you had `cd`'d into it before
+    #   running `git clone`. The returned path is the join of `:chdir` and the
+    #   cloned directory path.
+    #
+    # @option opts [String] :path deprecated: use `:chdir` instead.
+    #
+    # @option opts [String] :remote deprecated: use `:origin` instead.
+    #
+    # @option opts [Boolean, String, Array<String>, nil] :recurse_submodules (nil) initialize
+    #   submodules after cloning; pass `true` for all submodules, or a pathspec string/array
+    #   for a subset
+    #
+    # @option opts [Boolean, String, Array<String>, nil] :recursive (nil) deprecated: use `:recurse_submodules` instead
+    #
+    # @option opts [Numeric, nil] :timeout (nil) the number of seconds to wait for the
     #   command to complete
     #
     #   See {Git::Lib#command} for more information about :timeout
@@ -163,16 +164,16 @@ module Git
     #
     # @todo make this work with SSH password or auth_key
     #
-    def clone(repository_url, directory, opts = {})
-      @path = opts[:path] || '.'
-      clone_dir = opts[:path] ? File.join(@path, directory) : directory
-
-      args = build_args(opts, CLONE_OPTION_MAP)
-      args.push('--', repository_url, clone_dir)
-
-      command('clone', *args, timeout: opts[:timeout])
-
-      return_base_opts_from_clone(clone_dir, opts)
+    def clone(repository_url, directory = nil, opts = {})
+      opts = opts.dup
+      deprecate_clone_options!(opts)
+      chdir = opts.delete(:chdir)
+      execution_opts = extract_clone_execution_context_opts(opts)
+      opts[:chdir] = chdir if chdir
+      command_line_result = Git::Commands::Clone.new(self).call(repository_url, directory, **opts)
+      result = build_clone_result(command_line_result, execution_opts)
+      prefix_clone_result_paths!(result, chdir)
+      result
     end
 
     # Returns the name of the default branch of the given repository
@@ -182,7 +183,7 @@ module Git
     # @return [String] the name of the default branch
     #
     def repository_default_branch(repository)
-      output = command('ls-remote', '--symref', '--', repository, 'HEAD')
+      output = Git::Commands::LsRemote.new(self).call(repository, 'HEAD', symref: true).stdout
 
       match_data = output.match(%r{^ref: refs/remotes/origin/(?<default_branch>[^\t]+)\trefs/remotes/origin/HEAD$})
       return match_data[:default_branch] if match_data
@@ -195,29 +196,6 @@ 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
@@ -226,13 +204,13 @@ module Git
     #
     # @param opts [Hash] the given options
     #
-    # @option opts :all [Boolean]
-    # @option opts :tags [Boolean]
-    # @option opts :contains [Boolean]
-    # @option opts :debug [Boolean]
-    # @option opts :long [Boolean]
-    # @option opts :always [Boolean]
-    # @option opts :exact_match [Boolean]
+    # @option opts [Boolean, nil] :all (nil) use refs from all branches, tags, and remotes
+    # @option opts [Boolean, nil] :tags (nil) consider any tag, not just annotated ones
+    # @option opts [Boolean, nil] :contains (nil) find the tag that comes after the commit
+    # @option opts [Boolean, nil] :debug (nil) enable verbose searching strategy output
+    # @option opts [Boolean, nil] :long (nil) always output the long format
+    # @option opts [Boolean, nil] :always (nil) show uniquely abbreviated commit as a fallback
+    # @option opts [Boolean, nil] :exact_match (nil) only output exact tag matches
     # @option opts :dirty [true, String]
     # @option opts :abbrev [String]
     # @option opts :candidates [String]
@@ -245,59 +223,14 @@ module Git
     def describe(commit_ish = nil, opts = {})
       assert_args_are_not_options('commit-ish object', commit_ish)
 
-      args = build_args(opts, DESCRIBE_OPTION_MAP)
-      args << commit_ish if commit_ish
-
-      command('describe', *args)
-    end
-
-    # 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 :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
-    #
-    #   Only :between or :object options can be used, not both.
-    #
-    # @option opts :object [String] the revision range for the git log command
-    #
-    #   Only :between or :object options can be used, not both.
-    #
-    # @option opts :path_limiter [String, Pathname, Array<String, Pathname>] only
-    #   include commits that impact files from the specified paths
-    #
-    # @return [Array<String>] the log output
-    #
-    # @raise [ArgumentError] if the resulting revision range is a string starting with a hyphen
-    #
-    def 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=oneline'
-
-      arr_opts += log_path_options(opts)
+      # Translate legacy :"exact-match" (hyphenated) key to :exact_match (underscored)
+      opts = opts.dup
+      opts[:exact_match] ||= opts.delete(:'exact-match') if opts.key?(:'exact-match')
 
-      command_lines('log', *arr_opts).map { |l| l.split.first }
+      commit_ishes = Array(commit_ish).compact
+      Git::Commands::Describe.new(self).call(*commit_ishes, **opts).stdout
     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
@@ -307,9 +240,9 @@ module Git
     # @option opts :count [Integer] the maximum number of commits to return (maps to
     #   max-count)
     #
-    # @option opts :all [Boolean]
+    # @option opts [Boolean, nil] :all (nil) include commits reachable from any ref
     #
-    # @option opts :cherry [Boolean]
+    # @option opts [Boolean, nil] :cherry (nil) omit commits equivalent to cherry-picked commits
     #
     # @option opts :since [String]
     #
@@ -353,15 +286,11 @@ module Git
     #   :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])
+      assert_valid_opts(opts, FULL_LOG_ALLOWED_OPTS)
+      validate_log_count_option!(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)
+      call_opts = log_base_call_options(opts, skip: opts[:skip], merges: opts[:merges])
+      run_log_command(log_revision_range_args(opts), call_opts)
     end
 
     # Verify and resolve a Git revision to its full SHA
@@ -380,12 +309,9 @@ module Git
     # @return [String] the full commit hash
     #
     # @raise [Git::FailedError] if the revision cannot be resolved
-    # @raise [ArgumentError] if the revision is a string starting with a hyphen
     #
     def rev_parse(revision)
-      assert_args_are_not_options('rev', revision)
-
-      command('rev-parse', '--revs-only', '--end-of-options', revision, '--')
+      Git::Commands::RevParse.new(self).call(revision, '--', revs_only: true).stdout
     end
 
     # For backwards compatibility with the old method name
@@ -402,42 +328,69 @@ module Git
     def name_rev(commit_ish)
       assert_args_are_not_options('commit_ish', commit_ish)
 
-      command('name-rev', commit_ish).split[1]
+      Git::Commands::NameRev.new(self).call(commit_ish).stdout.split[1]
     end
 
     alias namerev name_rev
 
-    # Output the contents or other properties of one or more objects.
+    # Returns the raw content of a git object, or streams it into a tempfile
+    #
+    # Without a block, the full content is buffered in memory and returned as a
+    # `String`. With a block, git output is streamed directly to disk without memory
+    # buffering — safe for large blobs.
     #
     # @see https://git-scm.com/docs/git-cat-file git-cat-file
     #
-    # @example Get the contents of a file without a block
-    #   lib.cat_file_contents('README.md') # => "This is a README file\n"
+    # @overload cat_file_contents(object)
+    #   Returns the object's raw content as a string.
     #
-    # @example Get the contents of a file with a block
-    #  lib.cat_file_contents('README.md') { |f| f.read } # => "This is a README file\n"
+    #   @param object [String] the object name (SHA, ref, `HEAD`, treeish path, etc.)
     #
-    # @param object [String] the object whose contents to return
+    #   @return [String] the raw content of the object
     #
-    # @return [String] the object contents
+    #   @raise [ArgumentError] if `object` starts with a hyphen
     #
-    # @raise [ArgumentError] if object is a string starting with a hyphen
+    #   @raise [Git::FailedError] if the object does not exist or the command fails
+    #
+    #   @example Get the contents of a blob
+    #     lib.cat_file_contents('HEAD:README.md') # => "This is a README file\n"
+    #
+    # @overload cat_file_contents(object, &block)
+    #   Streams the object's raw content to a temporary file and yields it.
+    #
+    #   Git output is written directly to a file on disk without being
+    #   buffered in memory first, then the file is rewound and yielded to the block.
+    #   The return value is whatever the block returns.
+    #
+    #   @param object [String] the object name (SHA, ref, `HEAD`, treeish path, etc.)
+    #
+    #   @yield [file] the temporary file containing the streamed content, positioned at the start
+    #
+    #   @yieldparam file [File] readable `IO` object positioned at the beginning of the content
+    #
+    #   @yieldreturn [Object] the value to return from this method
+    #
+    #   @return [Object] the value returned by the block
+    #
+    #   @raise [ArgumentError] if `object` starts with a hyphen
+    #
+    #   @raise [Git::FailedError] if the object does not exist or the command fails
+    #
+    #   @example Read a large blob without buffering it in memory
+    #     lib.cat_file_contents('HEAD:large_file.bin') { |f| process(f) }
     #
     def cat_file_contents(object)
       assert_args_are_not_options('object', object)
 
-      if block_given?
-        Tempfile.create do |file|
-          # 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)
-          file.rewind
-          yield file
-        end
-      else
-        # If a block is not given, return the file contents as a string
-        command('cat-file', '-p', object)
+      return Git::Commands::CatFile::Raw.new(self).call(object, p: true).stdout unless block_given?
+
+      # Stream git output directly to a tempfile to avoid buffering large
+      # object content in memory when a block is given.
+      Tempfile.create do |file|
+        file.binmode
+        Git::Commands::CatFile::Raw.new(self).call(object, p: true, out: file)
+        file.rewind
+        yield file
       end
     end
 
@@ -456,7 +409,7 @@ module Git
     def cat_file_type(object)
       assert_args_are_not_options('object', object)
 
-      command('cat-file', '-t', object)
+      cat_file_object_meta(object)[:type]
     end
 
     alias object_type cat_file_type
@@ -465,16 +418,16 @@ module Git
     #
     # @see https://git-scm.com/docs/git-cat-file git-cat-file
     #
-    # @param object [String] the object to get the type
+    # @param object [String] the object to get the size of
     #
-    # @return [String] the object type
+    # @return [Integer] the object size in bytes
     #
     # @raise [ArgumentError] if object is a string starting with a hyphen
     #
     def cat_file_size(object)
       assert_args_are_not_options('object', object)
 
-      command('cat-file', '-s', object).to_i
+      cat_file_object_meta(object)[:size]
     end
 
     alias object_size cat_file_size
@@ -500,7 +453,7 @@ module Git
     def cat_file_commit(object)
       assert_args_are_not_options('object', object)
 
-      cdata = command_lines('cat-file', 'commit', object)
+      cdata = Git::Commands::CatFile::Raw.new(self).call('commit', object).stdout.split("\n")
       process_commit_data(cdata, object)
     end
 
@@ -517,6 +470,26 @@ module Git
 
     CAT_FILE_HEADER_LINE = /\A(?<key>\w+) (?<value>.*)\z/
 
+    # Yields parsed header key/value pairs from `git cat-file` output lines
+    #
+    # Consumes header lines from the front of `data` until a non-header line is
+    # encountered. Continuation lines that begin with a space are folded into the
+    # previous header value using newline separators.
+    #
+    # @param data [Array<String>] mutable output lines from a cat-file response
+    #
+    # @yield [key, value] each parsed header pair
+    #
+    # @yieldparam key [String] header field name
+    #
+    # @yieldparam value [String] unfolded header value text
+    #
+    # @yieldreturn [void]
+    #
+    # @return [void]
+    #
+    # @raise [NoMethodError] if `data` contains non-string entries
+    #
     def each_cat_file_header(data)
       while (match = CAT_FILE_HEADER_LINE.match(data.shift))
         key = match[:key]
@@ -569,12 +542,39 @@ module Git
     def cat_file_tag(object)
       assert_args_are_not_options('object', object)
 
-      tdata = command_lines('cat-file', 'tag', object)
+      tdata = Git::Commands::CatFile::Raw.new(self).call('tag', object).stdout.split("\n")
       process_tag_data(tdata, object)
     end
 
     alias tag_data cat_file_tag
 
+    def cat_file_object_meta(object)
+      stdout = Git::Commands::CatFile::Batch.new(self).call(object, batch_check: true).stdout
+      parse_cat_file_meta(stdout, object)
+    end
+
+    def parse_cat_file_meta(output, object)
+      line = output.to_s.lines.first.to_s.chomp
+
+      request_object_to_raise_error!(object) if line == "#{object} missing"
+
+      match = /\A\S+ (?<type>\S+) (?<size>\d+)\z/.match(line)
+      raise Git::UnexpectedResultError, "unexpected git cat-file metadata output: #{line.inspect}" if match.nil?
+
+      {
+        type: match[:type],
+        size: match[:size].to_i
+      }
+    end
+
+    # Re-request the missing object via non-batch cat-file so git produces a
+    # real non-zero exit and a FailedError with an accurate stderr message.
+    def request_object_to_raise_error!(object)
+      Git::Commands::CatFile::Raw.new(self).call(object, p: true)
+      raise Git::UnexpectedResultError,
+            "expected git cat-file to raise Git::FailedError for missing object #{object.inspect}"
+    end
+
     def process_tag_data(data, name)
       hsh = { 'name' => name }
 
@@ -649,32 +649,48 @@ module Git
     end
     private_constant :RawLogParser
 
-    LS_TREE_OPTION_MAP = [
-      { keys: [:recursive], flag: '-r', type: :boolean }
-    ].freeze
+    # Allowed option keys for {#ls_tree}
+    LS_TREE_ALLOWED_OPTS = %i[recursive path].freeze
 
+    # Lists the objects in a git tree
+    #
+    # @param sha [String] the tree-ish object to list
+    #
+    # @param opts [Hash] additional options
+    #
+    # @return [Hash<String, Hash<String, Hash>>] parsed ls-tree output
+    #
+    # @api private
+    #
     def ls_tree(sha, opts = {})
-      data = { 'blob' => {}, 'tree' => {}, 'commit' => {} }
-      args = build_args(opts, LS_TREE_OPTION_MAP)
-
-      args.unshift(sha)
-      args << opts[:path] if opts[:path]
+      assert_valid_opts(opts, LS_TREE_ALLOWED_OPTS)
+      r_value = opts[:recursive]
+      paths = Array(opts[:path]).compact
+      safe_options = {}
+      safe_options[:r] = r_value unless r_value.nil?
+      result = Git::Commands::LsTree.new(self).call(sha, *paths, **safe_options)
+      parse_ls_tree_output(result.stdout)
+    end
 
-      command_lines('ls-tree', *args).each do |line|
+    def parse_ls_tree_output(output)
+      data = { 'blob' => {}, 'tree' => {}, 'commit' => {} }
+      output.split("\n").each do |line|
         (info, filenm) = split_status_line(line)
-        (mode, type, sha) = info.split
-        data[type][filenm] = { mode: mode, sha: sha }
+        (mode, type, entry_sha) = info.split
+        data[type][filenm] = { mode: mode, sha: entry_sha }
       end
-
       data
     end
+    private :parse_ls_tree_output
 
-    def mv(file1, file2)
-      command_lines('mv', '--', file1, file2)
+    # @return [String] the command output
+    #
+    def mv(source, destination, options = {})
+      Git::Commands::Mv.new(self).call(*Array(source), destination, verbose: true, **options).stdout
     end
 
     def full_tree(sha)
-      command_lines('ls-tree', '-r', sha)
+      Git::Commands::LsTree.new(self).call(sha, r: true).stdout.split("\n")
     end
 
     def tree_depth(sha)
@@ -682,38 +698,12 @@ module Git
     end
 
     def change_head_branch(branch_name)
-      command('symbolic-ref', 'HEAD', "refs/heads/#{branch_name}")
+      Git::Commands::SymbolicRef::Update.new(self).call('HEAD', "refs/heads/#{branch_name}")
     end
 
-    BRANCH_LINE_REGEXP = /
-      ^
-        # Prefix indicates if this branch is checked out. The prefix is one of:
-        (?:
-          (?<current>\*[[:blank:]]) |  # Current branch (checked out in the current worktree)
-          (?<worktree>\+[[:blank:]]) | # Branch checked out in a different worktree
-          [[:blank:]]{2}               # Branch not checked out
-        )
-
-        # The branch's full refname
-        (?:
-          (?<not_a_branch>\(not[[:blank:]]a[[:blank:]]branch\)) |
-           (?:\(HEAD[[:blank:]]detached[[:blank:]]at[[:blank:]](?<detached_ref>[^)]+)\)) |
-          (?<refname>[^[[:blank:]]]+)
-        )
-
-        # Optional symref
-        # If this ref is a symbolic reference, this is the ref referenced
-        (?:
-          [[:blank:]]->[[:blank:]](?<symref>.*)
-        )?
-      $
-    /x
-
     def branches_all
-      lines = command_lines('branch', '-a')
-      lines.each_with_index.filter_map do |line, index|
-        parse_branch_line(line, index, lines)
-      end
+      result = Git::Commands::Branch::List.new(self).call(all: true, format: Git::Parsers::Branch::FORMAT_STRING)
+      Git::Parsers::Branch.parse_list(result.stdout)
     end
 
     def worktrees_all
@@ -728,7 +718,7 @@ module Git
       # HEAD b8c63206f8d10f57892060375a86ae911fad356e
       # detached
       #
-      command_lines('worktree', 'list', '--porcelain').each do |w|
+      Git::Commands::Worktree::List.new(self).call(porcelain: true).stdout.split("\n").each do |w|
         s = w.split
         directory = s[1] if s[0] == 'worktree'
         arr << [directory, s[1]] if s[0] == 'HEAD'
@@ -737,17 +727,19 @@ module Git
     end
 
     def worktree_add(dir, commitish = nil)
-      return worktree_command('worktree', 'add', dir, commitish) unless commitish.nil?
-
-      worktree_command('worktree', 'add', dir)
+      if commitish.nil?
+        Git::Commands::Worktree::Add.new(self).call(dir).stdout
+      else
+        Git::Commands::Worktree::Add.new(self).call(dir, commitish).stdout
+      end
     end
 
     def worktree_remove(dir)
-      worktree_command('worktree', 'remove', dir)
+      Git::Commands::Worktree::Remove.new(self).call(dir).stdout
     end
 
     def worktree_prune
-      worktree_command('worktree', 'prune')
+      Git::Commands::Worktree::Prune.new(self).call.stdout
     end
 
     def list_files(ref_dir)
@@ -784,7 +776,7 @@ module Git
     # @return [HeadState] the state and name of the current branch
     #
     def current_branch_state
-      branch_name = command('branch', '--show-current')
+      branch_name = Git::Commands::Branch::ShowCurrent.new(self).call.stdout
       return HeadState.new(:detached, 'HEAD') if branch_name.empty?
 
       state = get_branch_state(branch_name)
@@ -792,39 +784,36 @@ module Git
     end
 
     def branch_current
-      branch_name = command('branch', '--show-current')
-      branch_name.empty? ? 'HEAD' : branch_name
+      result = Git::Commands::Branch::ShowCurrent.new(self).call
+      name = result.stdout.strip
+      name.empty? ? 'HEAD' : name
     end
 
     def branch_contains(commit, branch_name = '')
-      command('branch',  branch_name, '--contains', commit)
+      branch_name = branch_name.to_s
+      pattern = branch_name.empty? ? nil : branch_name
+      Git::Commands::Branch::List.new(self).call(*[pattern].compact, contains: commit, no_color: true).stdout
     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
+    GREP_ALLOWED_OPTS = %i[ignore_case i invert_match v extended_regexp E object path_limiter].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)
+    def grep(pattern, opts = {})
+      assert_valid_opts(opts, GREP_ALLOWED_OPTS)
 
-      boolean_flags = build_args(opts, GREP_OPTION_MAP)
-      args = ['-n', *boolean_flags, '-e', string, opts[:object]]
+      opts = normalize_grep_opts(opts)
+      object = opts.delete(:object) || 'HEAD'
+      result = Git::Commands::Grep.new(self).call(
+        object, pattern:, **opts, no_color: true, line_number: true, null: true
+      )
+      exitstatus = result.status.exitstatus
 
-      if (limiter = opts[:path_limiter])
-        args.push('--', *Array(limiter))
-      end
+      # Exit status 1 with empty stderr means no lines matched (not an error)
+      return {} if exitstatus == 1 && result.stderr.empty?
+
+      # Exit status 1 with non-empty stderr is a real error (e.g. bad object reference)
+      raise Git::FailedError, result if exitstatus == 1
 
-      lines = execute_grep_command(args)
-      parse_grep_output(lines)
+      parse_grep_output(result.stdout)
     end
 
     # Validate that the given arguments cannot be mistaken for a command-line option
@@ -877,7 +866,24 @@ module Git
       raise ArgumentError, "Invalid #{arg_name}: must be a String, Pathname, or Array of Strings/Pathnames"
     end
 
+    # Allowed option keys for {#full_log_commits}
+    FULL_LOG_ALLOWED_OPTS = %i[count all cherry since until grep author between object path_limiter skip merges].freeze
+
+    # Allowed option keys for {#diff_full}
+    DIFF_FULL_ALLOWED_OPTS = %i[path_limiter].freeze
+
+    # Allowed option keys for {#diff_stats}
+    DIFF_STATS_ALLOWED_OPTS = %i[path_limiter].freeze
+
+    # Allowed option keys for {#diff_path_status}
+    DIFF_PATH_STATUS_ALLOWED_OPTS = %i[path_limiter path].freeze
+
     # Handle deprecated :path option in favor of :path_limiter
+    #
+    # @param opts [Hash] options hash that may contain :path or :path_limiter
+    #
+    # @return [String, Pathname, Array<String, Pathname>, nil] the resolved path limiter
+    #
     def handle_deprecated_path_option(opts)
       if opts.key?(:path_limiter)
         opts[:path_limiter]
@@ -889,74 +895,131 @@ module Git
       end
     end
 
-    DIFF_FULL_OPTION_MAP = [
-      { type: :static, flag: '-p' },
-      { keys: [:path_limiter], type: :validate_only }
-    ].freeze
+    # Validate that opts contains only allowed keys
+    #
+    # @param opts [Hash] options hash to validate
+    #
+    # @param allowed [Array<Symbol>] allowed option keys
+    #
+    # @raise [ArgumentError] if unknown keys are present
+    #
+    def assert_valid_opts(opts, allowed)
+      unknown = opts.keys - allowed
+      raise ArgumentError, "Unknown options: #{unknown.join(', ')}" if unknown.any?
+    end
 
+    # Show full diff patch output between commits or the working tree
+    #
+    # Delegates to {Git::Commands::Diff}.
+    #
+    # @param obj1 [String] first commit reference (default: 'HEAD')
+    #
+    # @param obj2 [String, nil] second commit reference (default: nil)
+    #
+    # @param opts [Hash] options
+    #
+    # @option opts [String, Pathname, Array<String, Pathname>] :path_limiter (nil)
+    #   pathspecs to limit the diff
+    #
+    # @return [String] the unified diff patch output
+    #
+    # @raise [Git::FailedError] if git returns exit code > 2
+    #
+    # @see Git::Commands::Diff
+    #
     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)
-
-      args = build_args(opts, DIFF_FULL_OPTION_MAP)
-      args.push(obj1, obj2).compact!
-
-      if (pathspecs = normalize_pathspecs(opts[:path_limiter], 'path limiter'))
-        args.push('--', *pathspecs)
-      end
-
-      command('diff', *args)
+      assert_valid_opts(opts, DIFF_FULL_ALLOWED_OPTS)
+      pathspecs = normalize_pathspecs(opts[:path_limiter], 'path limiter')
+      result = Git::Commands::Diff.new(self).call(
+        *[obj1, obj2].compact,
+        patch: true, numstat: true, shortstat: true,
+        src_prefix: 'a/', dst_prefix: 'b/',
+        path: pathspecs
+      )
+      extract_patch_text(result.stdout)
     end
 
-    DIFF_STATS_OPTION_MAP = [
-      { type: :static, flag: '--numstat' },
-      { keys: [:path_limiter], type: :validate_only }
-    ].freeze
-
+    # Show numstat diff output between commits or the working tree
+    #
+    # Delegates to {Git::Commands::Diff}.
+    #
+    # @param obj1 [String] first commit reference (default: 'HEAD')
+    #
+    # @param obj2 [String, nil] second commit reference (default: nil)
+    #
+    # @param opts [Hash] options
+    #
+    # @option opts [String, Pathname, Array<String, Pathname>] :path_limiter (nil)
+    #   pathspecs to limit the diff
+    #
+    # @return [Hash] diff statistics with the shape:
+    #   `{ total: { insertions:, deletions:, lines:, files: }, files: { ... } }`
+    #
+    # @raise [Git::FailedError] if git returns exit code > 2
+    #
+    # @see Git::Commands::Diff
+    #
     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)
-
-      args = build_args(opts, DIFF_STATS_OPTION_MAP)
-      args.push(obj1, obj2).compact!
-
-      if (pathspecs = normalize_pathspecs(opts[:path_limiter], 'path limiter'))
-        args.push('--', *pathspecs)
-      end
-
-      output_lines = command_lines('diff', *args)
+      assert_valid_opts(opts, DIFF_STATS_ALLOWED_OPTS)
+      pathspecs = normalize_pathspecs(opts[:path_limiter], 'path limiter')
+      result = Git::Commands::Diff.new(self).call(
+        *[obj1, obj2].compact,
+        numstat: true, shortstat: true,
+        src_prefix: 'a/', dst_prefix: 'b/',
+        path: pathspecs
+      )
+      output_lines = extract_numstat_lines(result.stdout)
       parse_diff_stats_output(output_lines)
     end
 
-    DIFF_PATH_STATUS_OPTION_MAP = [
-      { type: :static, flag: '--name-status' },
-      { keys: [:path_limiter], type: :validate_only },
-      { keys: [:path], type: :validate_only }
-    ].freeze
-
+    # Show path status (name-status) for diff between commits or the working tree
+    #
+    # Delegates to {Git::Commands::Diff} and extracts status letters and
+    # paths from the raw output lines.
+    #
+    # @param reference1 [String, nil] first commit reference (default: nil)
+    #
+    # @param reference2 [String, nil] second commit reference (default: nil)
+    #
+    # @param opts [Hash] options
+    #
+    # @option opts [String, Pathname, Array<String, Pathname>] :path_limiter (nil)
+    #   pathspecs to limit the diff
+    #
+    # @option opts [String, Pathname, Array<String, Pathname>] :path (nil)
+    #   deprecated; use :path_limiter instead
+    #
+    # @return [Hash] mapping of file paths to status letters
+    #   (e.g. `{ "lib/foo.rb" => "M", "README.md" => "A" }`)
+    #
+    # @raise [Git::FailedError] if git returns exit code > 2
+    #
+    # @see Git::Commands::Diff
+    #
     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)
-
-      args = build_args(opts, DIFF_PATH_STATUS_OPTION_MAP)
-      args.push(reference1, reference2).compact!
+      assert_valid_opts(opts, DIFF_PATH_STATUS_ALLOWED_OPTS)
 
       path_limiter = handle_deprecated_path_option(opts)
-      if (pathspecs = normalize_pathspecs(path_limiter, 'path limiter'))
-        args.push('--', *pathspecs)
-      end
-
-      parse_diff_path_status(args)
+      pathspecs = normalize_pathspecs(path_limiter, 'path limiter')
+      result = Git::Commands::Diff.new(self).call(
+        *[reference1, reference2].compact,
+        raw: true, numstat: true, shortstat: true,
+        src_prefix: 'a/', dst_prefix: 'b/',
+        path: pathspecs
+      )
+      extract_name_status_from_raw(result.stdout)
     end
 
     # compares the index and the working directory
     def diff_files
-      diff_as_hash('diff-files')
+      Git::Commands::Status.new(self).call
+      parse_raw_diff_output(Git::Commands::DiffFiles.new(self).call.stdout)
     end
 
     # compares the index and the repository
     def diff_index(treeish)
-      diff_as_hash('diff-index', treeish)
+      Git::Commands::Status.new(self).call
+      parse_raw_diff_output(Git::Commands::DiffIndex.new(self).call(treeish).stdout)
     end
 
     # List all files that are in the index
@@ -974,7 +1037,7 @@ module Git
     def ls_files(location = nil)
       location ||= '.'
       {}.tap do |files|
-        command_lines('ls-files', '--stage', location).each do |line|
+        Git::Commands::LsFiles.new(self).call(location, stage: true).stdout.split("\n").each do |line|
           (info, file) = split_status_line(line)
           (mode, sha, stage) = info.split
           files[file] = {
@@ -1007,28 +1070,22 @@ module Git
       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)
+      repository = location || '.'
+      output_lines = Git::Commands::LsRemote.new(self).call(repository, **opts).stdout.split("\n")
       parse_ls_remote_output(output_lines)
     end
 
     def ignored_files
-      command_lines('ls-files', '--others', '-i', '--exclude-standard').map { |f| unescape_quoted_path(f) }
+      Git::Commands::LsFiles.new(self).call(
+        others: true, ignored: true, exclude_standard: true
+      ).stdout.split("\n").map { |f| unescape_quoted_path(f) }
     end
 
     def untracked_files
-      command_lines('ls-files', '--others', '--exclude-standard', chdir: @git_work_dir).map do |f|
-        unescape_quoted_path(f)
-      end
+      Git::Commands::LsFiles.new(self).call(
+        others: true, exclude_standard: true, chdir: @git_work_dir
+      ).stdout.split("\n").map { |f| unescape_quoted_path(f) }
     end
 
     def config_remote(name)
@@ -1040,19 +1097,25 @@ module Git
     end
 
     def config_get(name)
-      command('config', '--get', name, chdir: @git_dir)
+      result = Git::Commands::ConfigOptionSyntax::Get.new(self).call(name)
+      raise Git::FailedError, result if result.status.exitstatus != 0
+
+      result.stdout
     end
 
     def global_config_get(name)
-      command('config', '--global', '--get', name)
+      result = Git::Commands::ConfigOptionSyntax::Get.new(self).call(name, global: true)
+      raise Git::FailedError, result if result.status.exitstatus != 0
+
+      result.stdout
     end
 
     def config_list
-      parse_config_list command_lines('config', '--list', chdir: @git_dir)
+      parse_config_list Git::Commands::ConfigOptionSyntax::List.new(self).call.stdout.split("\n")
     end
 
     def global_config_list
-      parse_config_list command_lines('config', '--global', '--list')
+      parse_config_list Git::Commands::ConfigOptionSyntax::List.new(self).call(global: true).stdout.split("\n")
     end
 
     def parse_config_list(lines)
@@ -1065,7 +1128,7 @@ module Git
     end
 
     def parse_config(file)
-      parse_config_list command_lines('config', '--list', '--file', file)
+      parse_config_list Git::Commands::ConfigOptionSyntax::List.new(self).call(file: file).stdout.split("\n")
     end
 
     # Shows objects
@@ -1074,34 +1137,23 @@ module Git
     # @param [String|NilClass] path the path of the file to be shown
     # @return [String] the object information
     def show(objectish = nil, path = nil)
-      arr_opts = []
-
-      arr_opts << (path ? "#{objectish}:#{path}" : objectish)
-
-      command('show', *arr_opts.compact, chomp: false)
+      object = path ? "#{objectish}:#{path}" : objectish
+      Git::Commands::Show.new(self).call(*[object].compact).stdout
     end
 
     ## WRITE COMMANDS ##
 
-    CONFIG_SET_OPTION_MAP = [
-      { keys: [:file], flag: '--file', type: :valued_space }
-    ].freeze
+    CONFIG_SET_ALLOWED_OPTS = %i[file].freeze
 
     def config_set(name, value, options = {})
-      ArgsBuilder.validate!(options, CONFIG_SET_OPTION_MAP)
-      flags = build_args(options, CONFIG_SET_OPTION_MAP)
-      command('config', *flags, name, value)
+      assert_valid_opts(options, CONFIG_SET_ALLOWED_OPTS)
+      Git::Commands::ConfigOptionSyntax::Set.new(self).call(name, value, **options.slice(*CONFIG_SET_ALLOWED_OPTS))
     end
 
     def global_config_set(name, value)
-      command('config', '--global', name, value)
+      Git::Commands::ConfigOptionSyntax::Set.new(self).call(name, value, global: true)
     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
     #
     # @example
@@ -1112,31 +1164,28 @@ module Git
     # @param [String, Array<String>] paths files to be added to the repository (relative to the worktree root)
     # @param [Hash] options
     #
-    # @option options [Boolean] :all Add, modify, and remove index entries to match the worktree
-    # @option options [Boolean] :force Allow adding otherwise ignored files
+    # @option options [Boolean, nil] :all (nil) add, modify, and remove index entries to match the worktree
+    # @option options [Boolean, nil] :force (nil) allow adding otherwise ignored files
+    #
+    # @return [String] the command output (typically empty on success)
     #
     def add(paths = '.', options = {})
-      args = build_args(options, ADD_OPTION_MAP)
-
-      args << '--'
-      args.concat(Array(paths))
-
-      command('add', *args)
+      Git::Commands::Add.new(self).call(*Array(paths), **options).stdout
     end
 
-    RM_OPTION_MAP = [
-      { type: :static, flag: '-f' },
-      { keys: [:recursive], flag: '-r',       type: :boolean },
-      { keys: [:cached],    flag: '--cached', type: :boolean }
-    ].freeze
-
+    # Remove files from the working tree and from the index
+    #
+    # @param path [String, Array<String>] files or directories to remove
+    # @param opts [Hash] command options
+    #
+    # @option opts [Boolean, nil] :force (nil) force removal, bypassing the up-to-date check; alias: `:f`
+    # @option opts [Boolean, nil] :recursive (nil) remove directories and their contents recursively
+    # @option opts [Boolean, nil] :cached (nil) only remove from the index, keeping working tree files
+    #
+    # @return [String] the command output
+    #
     def rm(path = '.', opts = {})
-      args = build_args(opts, RM_OPTION_MAP)
-
-      args << '--'
-      args.concat(Array(path))
-
-      command('rm', *args)
+      Git::Commands::Rm.new(self).call(*Array(path), **opts).stdout
     end
 
     # Returns true if the repository is empty (meaning it has no commits)
@@ -1144,7 +1193,7 @@ module Git
     # @return [Boolean]
     #
     def empty?
-      command('rev-parse', '--verify', 'HEAD')
+      Git::Commands::RevParse.new(self).call('HEAD', verify: true)
       false
     rescue Git::FailedError => e
       raise unless e.result.status.exitstatus == 128 &&
@@ -1153,27 +1202,6 @@ module Git
       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:
@@ -1189,176 +1217,284 @@ module Git
     #
     # @param [String] message the commit message to be used
     # @param [Hash] opts the commit options to be used
-
+    #
     def commit(message, opts = {})
-      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]
-
-      ArgsBuilder.validate!(opts, COMMIT_OPTION_MAP)
-
-      args = build_args(opts, COMMIT_OPTION_MAP)
-      command('commit', *args)
+      opts = opts.merge(message: message) if message
+      deprecate_commit_add_all_option!(opts)
+      Git::Commands::Commit.new(self).call(no_edit: true, **opts).stdout
     end
-    RESET_OPTION_MAP = [
-      { keys: [:hard], flag: '--hard', type: :boolean }
-    ].freeze
 
-    def reset(commit, opts = {})
-      args = build_args(opts, RESET_OPTION_MAP)
-      args << commit if commit
-      command('reset', *args)
+    # @return [String] the command output
+    #
+    def reset(commit = nil, opts = {})
+      Git::Commands::Reset.new(self).call(commit, **opts).stdout
     end
 
-    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
-
+    # @return [String] the command output
+    #
     def clean(opts = {})
-      args = build_args(opts, CLEAN_OPTION_MAP)
-      command('clean', *args)
+      opts = migrate_clean_legacy_options(opts)
+      Git::Commands::Clean.new(self).call(**opts).stdout
     end
 
-    REVERT_OPTION_MAP = [
-      { keys: [:no_edit], flag: '--no-edit', type: :boolean }
-    ].freeze
+    REVERT_ALLOWED_OPTS = %i[no_edit].freeze
 
     def revert(commitish, opts = {})
-      # Forcing --no-edit as default since it's not an interactive session.
+      assert_valid_opts(opts, REVERT_ALLOWED_OPTS)
       opts = { no_edit: true }.merge(opts)
-
-      args = build_args(opts, REVERT_OPTION_MAP)
-      args << commitish
-
-      command('revert', *args)
+      Git::Commands::Revert::Start.new(self).call(commitish, **opts).stdout
     end
 
     def apply(patch_file)
-      arr_opts = []
-      arr_opts << '--' << patch_file if patch_file
-      command('apply', *arr_opts)
+      Git::Commands::Apply.new(self).call(*[patch_file].compact, chdir: @git_work_dir).stdout
     end
 
     def apply_mail(patch_file)
-      arr_opts = []
-      arr_opts << '--' << patch_file if patch_file
-      command('am', *arr_opts)
+      Git::Commands::Am::Apply.new(self).call(*[patch_file].compact, chdir: @git_work_dir).stdout
     end
 
+    # Returns all stash entries as an array of index and message pairs
+    #
+    # List all stash entries in the repository ordered from oldest to newest
+    #
+    # The index is a sequential number starting from 0 for the oldest stash, and the
+    # message is the description of the stash entry.
+    #
+    # @example List all stashes (oldest first)
+    #   lib.stashes_all # => [[0, "Fix bug"], [1, "Add feature"]]
+    #
+    # @return [Array<Array(Integer, String)>] array of [index, message] pairs where
+    #   index is the sequential position (0 is oldest) and message is the stash description
+    #
+    # @see https://git-scm.com/docs/git-stash git-stash documentation
+    #
     def stashes_all
-      stash_log_lines.each_with_index.map do |line, index|
-        parse_stash_log_line(line, index)
-      end
+      result = Git::Commands::Stash::List.new(self).call
+      stashes = Git::Parsers::Stash.parse_list(result.stdout)
+      stashes.reverse.each_with_index.map { |info, i| stash_info_to_legacy(info, i) }
     end
 
-    def stash_save(message)
-      output = command('stash', 'save', message)
-      output =~ /HEAD is now at/
+    # Save the current working directory and index state to a new stash
+    #
+    # This method preserves v4.0.0 backward compatibility by returning a truthy/falsy
+    # value indicating whether a stash was created.
+    #
+    # @param message [String] the stash message
+    #
+    # @return [Boolean] true if changes were stashed, false if there were no local changes to save
+    #
+    # @example Save current changes
+    #   lib.stash_save('WIP: feature work')
+    #
+    # @see https://git-scm.com/docs/git-stash git-stash documentation
+    #
+    def stash_save(message) # rubocop:disable Naming/PredicateMethod
+      result = Git::Commands::Stash::Push.new(self).call(message: message)
+      !result.stdout.include?('No local changes to save')
     end
 
+    # Apply a stash to the working directory
+    #
+    # This method preserves v4.0.0 backward compatibility by returning the command output.
+    #
+    # @param id [String, Integer, nil] the stash identifier (e.g., 'stash@\\{0}', 0) or nil for latest
+    #
+    # @return [String] the output from the git stash apply command
+    #
+    # @example Apply the latest stash
+    #   lib.stash_apply
+    #
+    # @example Apply a specific stash
+    #   lib.stash_apply('stash@{1}')
+    #
+    # @see https://git-scm.com/docs/git-stash git-stash documentation
+    #
     def stash_apply(id = nil)
-      if id
-        command('stash', 'apply', id)
-      else
-        command('stash', 'apply')
-      end
+      result = Git::Commands::Stash::Apply.new(self).call(id)
+      result.stdout
     end
 
+    # Remove all stash entries
+    #
+    # This method preserves v4.0.0 backward compatibility by returning the command output.
+    #
+    # @return [String] the output from the git stash clear command
+    #
+    # @example Clear all stashes
+    #   lib.stash_clear
+    #
+    # @see https://git-scm.com/docs/git-stash git-stash documentation
+    #
     def stash_clear
-      command('stash', 'clear')
-    end
-
-    def stash_list
-      command('stash', 'list')
+      result = Git::Commands::Stash::Clear.new(self).call
+      result.stdout
     end
 
-    def branch_new(branch)
-      command('branch', branch)
+    # List all stash entries in standard git stash list format
+    #
+    # This method preserves v4.0.0 backward compatibility by returning a formatted
+    # string matching the output of `git stash list`.
+    #
+    # @return [String] newline-separated list of stash entries in the format
+    #   "stash@\\{n}: <message>", or an empty string if no stashes exist
+    #
+    # @example List all stashes
+    #   lib.stash_list # => "stash@\\{0}: On main: WIP\nstash@\\{1}: On feature: test"
+    #
+    # @see https://git-scm.com/docs/git-stash git-stash documentation
+    #
+    def stash_list
+      result = Git::Commands::Stash::List.new(self).call
+      stashes = Git::Parsers::Stash.parse_list(result.stdout)
+      stashes.map { |info| "#{info.name}: #{info.message}" }.join("\n")
     end
 
-    def branch_delete(branch)
-      command('branch', '-D', branch)
+    # Create a new branch
+    #
+    # @param branch [String] the name of the branch to create
+    # @param start_point [String, nil] the commit, branch, or tag to start the new branch from
+    # @param options [Hash] command options (see {Git::Commands::Branch::Create#call})
+    #
+    # @return [nil]
+    #
+    def branch_new(branch, start_point = nil, options = {})
+      Git::Commands::Branch::Create.new(self).call(branch, start_point, **options)
+      nil
     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
+    # Delete one or more branches
+    #
+    # @param branches [Array<String>] the name(s) of the branch(es) to delete
+    # @param options [Hash] command options (see {Git::Commands::Branch::Delete#call})
+    # @option options [Boolean, nil] :force (nil) allow deleting unmerged branches (defaults to `true` when not given)
+    # @option options [Boolean, nil] :remotes (nil) delete remote-tracking branches
+    #
+    # @return [String] newline-separated list of "Deleted branch <name> (was <sha>)." messages
+    #
+    # @raise [Git::Error] if any branch fails to delete
+    #
+    def branch_delete(*branches, **options)
+      options = { force: true }.merge(options)
+      result = Git::Commands::Branch::Delete.new(self).call(*branches, **options)
+
+      raise Git::Error, result.stderr.strip unless result.status.success?
+
+      result.stdout.strip
+    end
 
     # Runs checkout command to checkout or create branch
     #
     # accepts options:
-    #  :new_branch
-    #  :force
-    #  :start_point
+    #  :new_branch / :b - create a new branch with the given name (true = legacy, string = new)
+    #  :force / :f - proceed even with uncommitted changes
+    #  :start_point - start the new branch at this commit (used with :new_branch in legacy mode)
+    #
+    # @param [String] branch the branch to checkout, or nil
+    # @param [Hash] opts options for the checkout command
+    # @return [String] the command output
     #
-    # @param [String] branch
-    # @param [Hash] opts
     def checkout(branch = nil, opts = {})
       if branch.is_a?(Hash) && opts.empty?
         opts = branch
         branch = nil
       end
-      ArgsBuilder.validate!(opts, CHECKOUT_OPTION_MAP)
 
-      flags = build_args(opts, CHECKOUT_OPTION_MAP)
-      positional_args = build_checkout_positional_args(branch, opts)
+      target, translated_opts = translate_checkout_opts(branch, opts)
+      Git::Commands::Checkout::Branch.new(self).call(target, **translated_opts).stdout
+    end
 
-      command('checkout', *flags, *positional_args)
+    # Translates legacy checkout options to the new command interface.
+    # Legacy: checkout('branch', new_branch: true, start_point: 'main')
+    # New: checkout('main', b: 'branch')
+    def translate_checkout_opts(branch, opts)
+      if opts[:new_branch] == true || opts[:b] == true
+        [opts[:start_point], opts.except(:new_branch, :b, :start_point).merge(b: branch)]
+      elsif opts[:new_branch].is_a?(String)
+        [branch, opts.except(:new_branch).merge(b: opts[:new_branch])]
+      else
+        [branch, opts]
+      end
     end
+    private :translate_checkout_opts
 
+    # Checkout a specific version of a file
+    #
+    # @param version [String] the tree-ish (commit, branch, tag) to restore from
+    # @param file [String] the file path to restore
+    # @return [String] the command output
+    #
     def checkout_file(version, file)
-      arr_opts = []
-      arr_opts << version
-      arr_opts << file
-      command('checkout', *arr_opts)
+      Git::Commands::Checkout::Files.new(self).call(version, pathspec: [file]).stdout
     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
-
+    # Merge one or more branches into the current branch
+    #
+    # @param branch [String, Array<String>] branch name(s) to merge
+    # @param message [String, nil] commit message for merge commit
+    # @param opts [Hash] merge options
+    #
+    # @option opts [Boolean, nil] :no_commit (nil) stop before creating merge commit
+    #   (deprecated: use no_commit: true instead)
+    # @option opts [Boolean, nil] :no_ff (nil) create merge commit even for fast-forward
+    #   (deprecated: use no_ff: true instead)
+    # @option opts [String] :m (nil) commit message (deprecated: use message: option)
+    # @option opts [Boolean, nil] :commit (nil) true for --commit (`--commit`)
+    # @option opts [Boolean, nil] :ff (nil) true for --ff (`--ff`)
+    # @option opts [Boolean, nil] :ff_only (nil) only merge if fast-forward possible
+    # @option opts [Boolean, nil] :squash (nil) squash commits into single commit
+    # @option opts [String] :message (nil) commit message
+    # @option opts [String] :strategy (nil) merge strategy (e.g., 'ort', 'ours')
+    # @option opts [String, Array<String>] :strategy_option (nil) strategy-specific options
+    # @option opts [Boolean, nil] :allow_unrelated_histories (nil) allow merging unrelated histories
+    #
+    # @return [String] the command output
+    #
     def merge(branch, message = nil, opts = {})
-      # For backward compatibility, treat the message arg as the :m option.
-      opts[:m] = message if message
-      ArgsBuilder.validate!(opts, MERGE_OPTION_MAP)
+      # Handle legacy positional message argument
+      opts = opts.merge(message: message) if message
 
-      args = build_args(opts, MERGE_OPTION_MAP)
-      args.concat(Array(branch))
+      # Map legacy option names to new interface
+      opts = translate_merge_options(opts)
 
-      command('merge', *args)
+      Git::Commands::Merge::Start.new(self).call(*Array(branch), no_edit: true, **opts).stdout
     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
-
+    # Find common ancestor commit(s) for merge
+    #
+    # @overload merge_base(*commits, options = {})
+    #
+    #   @param commits [Array<String>] commits to find common ancestor(s) of
+    #
+    #   @param options [Hash] merge-base options
+    #
+    #   @option options [Boolean, nil] :octopus (nil) compute best ancestor for n-way merge
+    #   @option options [Boolean, nil] :independent (nil) list commits not reachable from others
+    #   @option options [Boolean, nil] :fork_point (nil) find fork point
+    #   @option options [Boolean, nil] :all (nil) output all merge bases
+    #
+    # @return [Array<String>] array of commit SHAs
+    #
     def merge_base(*args)
       opts = args.last.is_a?(Hash) ? args.pop : {}
-      ArgsBuilder.validate!(opts, MERGE_BASE_OPTION_MAP)
-
-      flags = build_args(opts, MERGE_BASE_OPTION_MAP)
-      command_args = flags + args
-
-      command('merge-base', *command_args).lines.map(&:strip)
+      result = Git::Commands::MergeBase.new(self).call(*args, **opts)
+      result.stdout.lines.map(&:strip).reject(&:empty?)
     end
 
+    # List paths that remain unmerged after a failed or partial merge
+    #
+    # Delegates to {Git::Commands::Diff}.
+    #
+    # @return [Array<String>] paths of files with unresolved merge conflicts
+    #
+    # @raise [Git::FailedError] if git returns exit code > 2
+    #
+    # @see Git::Commands::Diff
+    #
     def unmerged
-      unmerged = []
-      command_lines('diff', '--cached').each do |line|
-        unmerged << ::Regexp.last_match(1) if line =~ /^\* Unmerged path (.*)/
+      result = Git::Commands::Diff.new(self).call(cached: true)
+      result.stdout.split("\n").filter_map do |line|
+        ::Regexp.last_match(1) if line =~ /^\* Unmerged path (.*)/
       end
-      unmerged
     end
 
     def conflicts # :yields: file, your, their
@@ -1374,416 +1510,961 @@ module Git
       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 = {})
-      ArgsBuilder.validate!(opts, REMOTE_ADD_OPTION_MAP)
-
-      flags = build_args(opts, REMOTE_ADD_OPTION_MAP)
-      positional_args = ['--', name, url]
-      command_args = ['add'] + flags + positional_args
+      translated_opts = opts.dup
+      translated_opts[:fetch] = translated_opts.delete(:with_fetch) if translated_opts.key?(:with_fetch)
 
-      command('remote', *command_args)
+      Git::Commands::Remote::Add.new(self).call(name, url, **translated_opts)
     end
 
-    REMOTE_SET_BRANCHES_OPTION_MAP = [
-      { keys: [:add], flag: '--add', type: :boolean }
-    ].freeze
-
     def remote_set_branches(name, branches, opts = {})
-      ArgsBuilder.validate!(opts, REMOTE_SET_BRANCHES_OPTION_MAP)
-
-      flags = build_args(opts, REMOTE_SET_BRANCHES_OPTION_MAP)
-      branch_args = Array(branches).flatten
-      command_args = ['set-branches'] + flags + [name] + branch_args
-
-      command('remote', *command_args)
+      Git::Commands::Remote::SetBranches.new(self).call(name, *Array(branches).flatten, **opts)
     end
 
-    def remote_set_url(name, url)
-      arr_opts = ['set-url']
-      arr_opts << name
-      arr_opts << url
-
-      command('remote', *arr_opts)
+    def remote_set_url(name, url, opts = {})
+      Git::Commands::Remote::SetUrl.new(self).call(name, url, **opts)
     end
 
     def remote_remove(name)
-      command('remote', 'rm', name)
+      Git::Commands::Remote::Remove.new(self).call(name)
     end
 
     def remotes
-      command_lines('remote')
+      Git::Commands::Remote::List.new(self).call.stdout.split("\n")
     end
 
+    # List all tags in the repository
+    #
+    # @see https://git-scm.com/docs/git-tag git-tag
+    #
+    # @return [Array<String>] tag names
+    #
     def tags
-      command_lines('tag')
+      result = Git::Commands::Tag::List.new(self).call(format: Git::Parsers::Tag::FORMAT_STRING)
+      Git::Parsers::Tag.parse_list(result.stdout).map(&:name)
     end
 
-    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
-
+    # Create or delete a tag
+    #
+    # When the `:d` or `:delete` option is set, deletes the named tag.
+    # Otherwise, creates a new tag pointing at HEAD or the specified target.
+    #
+    # @see https://git-scm.com/docs/git-tag git-tag
+    #
+    # @overload tag(name, target, opts = {})
+    #
+    #   Create a tag on the specified target
+    #
+    #   @param name [String] the tag name to create
+    #
+    #   @param target [String] the commit or object to tag
+    #
+    #   @param opts [Hash] options for creating the tag
+    #
+    #   @option opts [Boolean, nil] :annotate (nil) create an unsigned, annotated tag object.
+    #     Requires `:message` or `:file`.
+    #
+    #     Alias: `:a`
+    #
+    #   @option opts [Boolean, nil] :sign (nil) create a GPG-signed tag. Requires `:message` or `:file`.
+    #
+    #     Alias: `:s`
+    #
+    #   @option opts [Boolean, nil] :force (nil) replace an existing tag with the given name.
+    #
+    #     Alias: `:f`
+    #
+    #   @option opts [String] :message (nil) use the given string as the tag message.
+    #     Implies annotated tag if none of `:annotate`, `:sign`, or `:local_user` is given.
+    #
+    #     Alias: `:m`
+    #
+    # @overload tag(name, opts = {})
+    #
+    #   Create a lightweight tag on HEAD
+    #
+    #   @param name [String] the tag name to create
+    #
+    #   @param opts [Hash] options for creating the tag
+    #
+    #   @option opts [Boolean, nil] :annotate (nil) create an unsigned, annotated tag object.
+    #     Requires `:message` or `:file`.
+    #
+    #     Alias: `:a`
+    #
+    #   @option opts [Boolean, nil] :sign (nil) create a GPG-signed tag. Requires `:message` or `:file`.
+    #
+    #     Alias: `:s`
+    #
+    #   @option opts [Boolean, nil] :force (nil) replace an existing tag with the given name.
+    #
+    #     Alias: `:f`
+    #
+    #   @option opts [String] :message (nil) use the given string as the tag message.
+    #     Implies annotated tag if none of `:annotate`, `:sign`, or `:local_user` is given.
+    #
+    #     Alias: `:m`
+    #
+    # @overload tag(name, opts = {})
+    #
+    #   Delete the named tag
+    #
+    #   @param name [String] the tag name to delete
+    #
+    #   @param opts [Hash] options
+    #
+    #   @option opts [Boolean, nil] :delete (nil) delete the named tag.
+    #
+    #     Alias: `:d`
+    #
+    # @return [String] command output
+    #
+    # @raise [ArgumentError] if creating an annotated or signed tag without a message
+    #
+    # @raise [Git::FailedError] if the tag already exists (without `:force`) or if
+    #   the tag to delete does not exist
+    #
     def tag(name, *args)
       opts = args.last.is_a?(Hash) ? args.pop : {}
       target = args.first
 
-      validate_tag_options!(opts)
-      ArgsBuilder.validate!(opts, TAG_OPTION_MAP)
+      if opts[:d] || opts[:delete]
+        delete_tag(name)
+      else
+        validate_tag_options!(opts)
+        create_tag(name, target, opts)
+      end
+    end
+
+    def fetch(remote, opts)
+      opts = opts.dup
+      refspecs = Array(opts.delete(:ref)).compact
+      positionals = [*([remote] if remote), *refspecs]
+      Git::Commands::Fetch.new(self).call(*positionals, **opts, merge: true).stdout
+    end
+
+    PUSH_ALLOWED_OPTS = %i[mirror delete force f push_option all tags].freeze
+
+    # Push refs to a remote repository
+    #
+    # @overload push(options = {})
+    #   Push using the current branch's default remote and push configuration
+    #
+    #   @param options [Hash] push options
+    #
+    #   @option options [Boolean, nil] :all (nil) push all branches
+    #
+    #   @option options [Boolean, nil] :mirror (nil) push all refs
+    #
+    #   @option options [Boolean, nil] :tags (nil) push all tags
+    #
+    #   @option options [Boolean, nil] :force (nil) force updates
+    #
+    #   @option options [Boolean, nil] :delete (nil) delete the named remote ref
+    #
+    #   @option options [String, Array<String>] :push_option (nil) server-side push option values
+    #
+    #   @return [String] the stdout from the final `git push` invocation
+    #
+    #   @raise [Git::FailedError] if git exits with a non-zero exit status
+    #
+    # @overload push(remote, options = {})
+    #   Push to the given remote using the current branch's default push configuration
+    #
+    #   @param remote [String] the remote name or URL to push to
+    #
+    #   @param options [Hash] push options
+    #
+    #   @option options [Boolean, nil] :all (nil) push all branches
+    #
+    #   @option options [Boolean, nil] :mirror (nil) push all refs
+    #
+    #   @option options [Boolean, nil] :tags (nil) push all tags
+    #
+    #   @option options [Boolean, nil] :force (nil) force updates
+    #
+    #   @option options [Boolean, nil] :delete (nil) delete the named remote ref
+    #
+    #   @option options [String, Array<String>] :push_option (nil) server-side push option values
+    #
+    #   @return [String] the stdout from the final `git push` invocation
+    #
+    #   @raise [Git::FailedError] if git exits with a non-zero exit status
+    #
+    # @overload push(remote, branch, options = {})
+    #   Push a branch or refspec to the given remote
+    #
+    #   @param remote [String] the remote name or URL to push to
+    #
+    #   @param branch [String] the branch name or refspec to push
+    #
+    #   @param options [Hash] push options
+    #
+    #   @option options [Boolean, nil] :all (nil) push all branches
+    #
+    #   @option options [Boolean, nil] :mirror (nil) push all refs
+    #
+    #   @option options [Boolean, nil] :tags (nil) push all tags
+    #
+    #   @option options [Boolean, nil] :force (nil) force updates
+    #
+    #   @option options [Boolean, nil] :delete (nil) delete the named remote ref
+    #
+    #   @option options [String, Array<String>] :push_option (nil) server-side push option values
+    #
+    #   @return [String] the stdout from the final `git push` invocation
+    #
+    #   @raise [Git::FailedError] if git exits with a non-zero exit status
+    #
+    #   @raise [ArgumentError] if `remote` is nil
+    #
+    # @overload push(remote, branch, tags)
+    #   Backward-compatible shorthand for `push(remote, branch, tags: tags)`
+    #
+    #   @param remote [String] the remote name or URL to push to
+    #
+    #   @param branch [String] the branch name or refspec to push
+    #
+    #   @param tags [Boolean] whether to push all tags
+    #
+    #   @return [String] the stdout from the final `git push` invocation
+    #
+    #   @raise [Git::FailedError] if git exits with a non-zero exit status
+    #
+    #   @raise [ArgumentError] if `remote` is nil
+    #
+    def push(remote = nil, branch = nil, opts = nil)
+      remote, branch, opts = normalize_push_args(remote, branch, opts)
+      validate_push_args!(remote, branch, opts)
+
+      first_result = push_refs(remote, branch, opts)
+      return first_result.stdout unless push_tags_separately?(opts)
+
+      push_tags(remote, opts).stdout
+    end
 
-      flags = build_args(opts, TAG_OPTION_MAP)
-      positional_args = [name, target].compact
+    PULL_ALLOWED_OPTS = %i[allow_unrelated_histories].freeze
 
-      command('tag', *flags, *positional_args)
+    def pull(remote = nil, branch = nil, opts = {})
+      raise ArgumentError, 'You must specify a remote if a branch is specified' if remote.nil? && !branch.nil?
+
+      assert_valid_opts(opts, PULL_ALLOWED_OPTS)
+      allowed_opts = opts.slice(*PULL_ALLOWED_OPTS)
+      positional_args = [remote, branch].compact
+      Git::Commands::Pull.new(self).call(*positional_args, no_edit: true, no_progress: true, **allowed_opts).stdout
     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
+    # Return the SHA of a tag reference
+    #
+    # Looks up the tag first in the local refs directory, then falls back to
+    # `git show-ref`. Returns an empty string if the tag does not exist.
+    #
+    # @param tag_name [String] the tag name to look up
+    #
+    # @return [String] the SHA of the tag, or an empty string if not found
+    #
+    def tag_sha(tag_name)
+      head = File.join(@git_dir, 'refs', 'tags', tag_name)
+      return File.read(head).chomp if File.exist?(head)
 
-    def fetch(remote, opts)
-      ArgsBuilder.validate!(opts, FETCH_OPTION_MAP)
-      args = build_args(opts, FETCH_OPTION_MAP)
+      result = Git::Commands::ShowRef::List.new(self).call(tag_name, tags: true, hash: true)
+      result.stdout
+    end
+
+    def repack
+      Git::Commands::Repack.new(self).call(a: true, d: true)
+    end
+
+    def gc
+      Git::Commands::Gc.new(self).call(prune: true, aggressive: true, auto: true)
+    end
 
-      if remote || opts[:ref]
-        args << '--'
-        args << remote if remote
-        args << opts[:ref] if opts[:ref]
+    # Execute git fsck to verify repository integrity
+    #
+    # @param objects [Array<String>] optional object identifiers to check
+    # @param opts [Hash] command options (see {Git::Commands::Fsck#call})
+    #
+    # @return [Git::FsckResult] the structured result
+    #
+    # rubocop:disable Style/ArgumentsForwarding
+    def fsck(*objects, **opts)
+      result = Git::Commands::Fsck.new(self).call(*objects, no_progress: true, **opts)
+      Git::Parsers::Fsck.parse(result.stdout)
+    end
+    # rubocop:enable Style/ArgumentsForwarding
+
+    READ_TREE_ALLOWED_OPTS = %i[prefix].freeze
+
+    def read_tree(treeish, opts = {})
+      assert_valid_opts(opts, READ_TREE_ALLOWED_OPTS)
+      allowed_opts = opts.slice(*READ_TREE_ALLOWED_OPTS)
+      Git::Commands::ReadTree.new(self).call(treeish, **allowed_opts)
+    end
+
+    def write_tree
+      Git::Commands::WriteTree.new(self).call.stdout
+    end
+
+    COMMIT_TREE_ALLOWED_OPTS = %i[p parent parents m message].freeze
+
+    def commit_tree(tree, opts = {})
+      assert_valid_opts(opts, COMMIT_TREE_ALLOWED_OPTS)
+      actual_opts = normalize_commit_tree_opts(opts, tree)
+      Git::Commands::CommitTree.new(self).call(tree, **actual_opts).stdout
+    end
+
+    def update_ref(ref, commit)
+      Git::Commands::UpdateRef::Update.new(self).call(ref, commit)
+    end
+
+    def checkout_index(opts = {})
+      paths = normalize_pathspecs(opts[:path_limiter], 'path_limiter')
+      keyword_opts = opts.except(:path_limiter)
+      Git::Commands::CheckoutIndex.new(self).call(*paths.to_a, **keyword_opts)
+    end
+
+    ARCHIVE_ALLOWED_OPTS = %i[prefix remote path format add_gzip].freeze
+
+    # Creates an archive of the given tree-ish and writes it to a file
+    #
+    # Delegates to {Git::Commands::Archive} for CLI execution. Format coercion
+    # (`tgz` → `tar` + gzip), temp file management, and gzip post-processing
+    # remain in this adapter.
+    #
+    # @see https://git-scm.com/docs/git-archive git-archive
+    #
+    # @param sha [String] tree-ish to archive (commit, tag, branch, or tree SHA)
+    #
+    # @param file [String, nil] destination file path; a unique temp file is
+    #   created and returned if `nil`
+    #
+    # @param opts [Hash] archive options
+    #
+    # @option opts [String] :prefix prefix to prepend to each filename in the archive
+    #
+    # @option opts [String] :remote URL of a remote repository to archive from
+    #
+    # @option opts [String] :path limit the archive to a path within the tree
+    #
+    # @option opts [String] :format archive format — `'tar'`, `'tgz'`, or `'zip'`
+    #   (default: `'zip'`)
+    #
+    # @option opts [Boolean, nil] :add_gzip (nil) wrap the archive in gzip compression
+    #
+    # @return [String] the path to the written archive file
+    #
+    # @raise [Git::FailedError] if `git archive` fails
+    #
+    def archive(sha, file = nil, opts = {})
+      assert_valid_opts(opts, ARCHIVE_ALLOWED_OPTS)
+      file ||= temp_file_name
+      format, gzip = parse_archive_format_options(opts)
+
+      command_opts = opts.slice(:prefix, :remote).merge(format: format)
+      path_args = opts[:path] ? [opts[:path]] : []
+
+      File.open(file, 'wb') do |f|
+        Git::Commands::Archive.new(self).call(sha, *path_args, **command_opts, out: f)
       end
+      apply_gzip(file) if gzip
 
-      command('fetch', *args, merge: true)
+      file
     end
 
-    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
+    # Returns the git version as a Git::Version
+    #
+    # Parses the output of `git version`, strips platform suffixes (like
+    # `.windows.1` or `.vfs.0`), and pads two-segment versions to three segments.
+    #
+    # Results are cached globally (keyed by binary path). It is assumed that the
+    # git version doesn't change during runtime for a given binary.
+    #
+    # @return [Git::Version] the parsed git version
+    #
+    # @raise [Git::UnexpectedResultError] if the version string cannot be parsed
+    #
+    # @example
+    #   lib.git_version #=> Git::Version.new(2, 42, 1)
+    #
+    def git_version
+      self.class.cached_git_version(Git::Base.config.binary_path) do
+        output = Git::Commands::Version.new(self).call.stdout
+        Git::Version.parse(output)
+      end
+    end
 
-    def push(remote = nil, branch = nil, opts = nil)
-      remote, branch, opts = normalize_push_args(remote, branch, opts)
-      ArgsBuilder.validate!(opts, PUSH_OPTION_MAP)
+    # Class-level cache for git versions, keyed by binary path
+    #
+    # Thread-safe for JRuby/TruffleRuby where true parallelism exists.
+    #
+    # @api private
+    #
+    def self.cached_git_version(binary_path, &block)
+      @git_version_cache_mutex.synchronize do
+        @git_version_cache[binary_path] ||= block.call
+      end
+    end
 
-      raise ArgumentError, 'remote is required if branch is specified' if !remote && branch
+    # Clear the git version cache (primarily for testing)
+    #
+    # @api private
+    #
+    def self.clear_git_version_cache
+      @git_version_cache_mutex.synchronize do
+        @git_version_cache.clear
+      end
+    end
 
-      args = build_push_args(remote, branch, opts)
+    # Returns the current version of git, as an Array<Integer>
+    #
+    # @deprecated Use {Git.git_version} instead, which returns a {Git::Version} (not an Array).
+    #   For the legacy array shape, call: `Git.git_version.to_a`
+    #
+    def current_command_version
+      Git::Deprecation.warn(
+        'Git::Lib#current_command_version is deprecated and will be removed in 6.0. ' \
+        'Use Git.git_version instead, which returns a Git::Version (not an Array). ' \
+        'For the legacy array shape, call: Git.git_version.to_a'
+      )
+      git_version.to_a
+    end
 
-      if opts[:mirror]
-        command('push', *args)
-      else
-        command('push', *args)
-        command('push', '--tags', *(args - [branch].compact)) if opts[:tags]
+    # Returns current_command_version <=> other_version
+    #
+    # @example
+    #   lib.compare_version_to(2, 41, 0) #=> 1
+    #   lib.compare_version_to(2, 42, 0) #=> 0
+    #   lib.compare_version_to(2, 43, 0) #=> -1
+    #
+    # @param other_version [Array<Integer>] the other version to compare to
+    # @return [Integer] -1 if this version is less than other_version, 0 if equal, or 1 if greater than
+    #
+    # @deprecated Use {Git.git_version} with {Git::Version} comparison operators instead,
+    #   e.g. `Git.git_version <=> Git::Version.new(2, 41, 0)`
+    #
+    def compare_version_to(*other_version)
+      Git::Deprecation.warn(
+        'Git::Lib#compare_version_to is deprecated and will be removed in 6.0. ' \
+        'Use Git.git_version with Git::Version comparison operators instead, ' \
+        'e.g. Git.git_version <=> Git::Version.new(2, 41, 0)'
+      )
+      git_version.to_a <=> other_version
+    end
+
+    # @deprecated Use {Git::MINIMUM_GIT_VERSION} constant instead, which returns a {Git::Version}
+    #   (not an Array). For the legacy array shape, call: `Git::MINIMUM_GIT_VERSION.to_a.first(2)`
+    #
+    def required_command_version
+      Git::Deprecation.warn(
+        'Git::Lib#required_command_version is deprecated and will be removed in 6.0. ' \
+        'Use the Git::MINIMUM_GIT_VERSION constant instead, which returns a Git::Version ' \
+        '(not an Array). For the legacy array shape, call: Git::MINIMUM_GIT_VERSION.to_a.first(2)'
+      )
+      Git::MINIMUM_GIT_VERSION.to_a.first(2)
+    end
+
+    # @deprecated For a boolean check, use `Git.git_version >= Git::MINIMUM_GIT_VERSION`.
+    #   For enforcement, no action is needed: {Git::Commands::Base#call} automatically
+    #   invokes `validate_version!`, which raises {Git::VersionError} on failure.
+    #
+    def meets_required_version?
+      Git::Deprecation.warn(
+        'Git::Lib#meets_required_version? is deprecated and will be removed in 6.0. ' \
+        'For a boolean check, use: Git.git_version >= Git::MINIMUM_GIT_VERSION. ' \
+        'For enforcement, no action is needed: Git::Commands::Base#call automatically ' \
+        'invokes validate_version!, which raises Git::VersionError on failure.'
+      )
+      git_version >= Git::MINIMUM_GIT_VERSION
+    end
+
+    # @deprecated Version validation is now handled automatically by
+    #   {Git::Commands::Base#validate_version!}, which raises {Git::VersionError} on failure.
+    #   Callers wanting the old warn-and-continue behavior must implement it themselves
+    #   using: `Git.git_version >= Git::MINIMUM_GIT_VERSION`.
+    #
+    def self.warn_if_old_command(_lib) # rubocop:disable Metrics/MethodLength, Naming/PredicateMethod
+      Git::Deprecation.warn(
+        'Git::Lib.warn_if_old_command is deprecated and will be removed in 6.0. ' \
+        'Version validation is now handled automatically by Git::Commands::Base#validate_version!, ' \
+        'which RAISES Git::VersionError on failure (the old method only printed a warning ' \
+        'once per process and continued). Callers wanting the old warn-and-continue behavior ' \
+        'must implement it themselves using: Git.git_version >= Git::MINIMUM_GIT_VERSION.'
+      )
+
+      return true if @version_checked
+
+      @version_checked = true
+      git_version = Git.git_version
+      unless git_version >= Git::MINIMUM_GIT_VERSION
+        warn "The git gem requires git #{Git::MINIMUM_GIT_VERSION} or later, " \
+             "but only found #{git_version}. You should probably upgrade."
       end
+      true
     end
 
-    PULL_OPTION_MAP = [
-      { keys: [:allow_unrelated_histories], flag: '--allow-unrelated-histories', type: :boolean }
+    COMMAND_CAPTURING_ARG_DEFAULTS = {
+      in: nil,
+      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
+      env: {},
+      raise_on_failure: true
+    }.freeze
+
+    STATIC_GLOBAL_OPTS = %w[
+      -c core.quotePath=true
+      -c core.editor=false
+      -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
 
-    def pull(remote = nil, branch = nil, opts = {})
-      raise ArgumentError, 'You must specify a remote if a branch is specified' if remote.nil? && !branch.nil?
+    # Runs a git command and returns the result
+    #
+    # By default, raises {Git::FailedError} if the command exits with a non-zero
+    # status. Pass `raise_on_failure: false` to suppress this behavior.
+    #
+    # @overload command_capturing(*args, **options_hash)
+    #   Runs a git command and returns the result
+    #
+    #   Args should exclude the 'git' command itself and global options.
+    #   Remember to splat the arguments if given as an array.
+    #
+    #   @example Run git log
+    #     result = command_capturing('log', '--pretty=oneline')
+    #     result.stdout #=> "abc123 First commit\ndef456 Second commit\n"
+    #
+    #   @example Using an array of arguments
+    #     args = ['log', '--pretty=oneline']
+    #     result = command_capturing(*args)
+    #
+    #   @example Suppress raising on failure
+    #     result = command_capturing('show', 'nonexistent', raise_on_failure: false)
+    #     result.status.success? #=> false
+    #
+    #   @param args [Array<String>] the command and its arguments
+    #
+    #   @param options_hash [Hash] the options to pass to the command
+    #
+    # @option options_hash [IO, nil] :in the IO object to use as stdin for the command, or nil to
+    #   inherit the parent process stdin. Must be a real IO object with a file descriptor.
+    #
+    # @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, nil] :normalize (true) normalize the output encoding to UTF-8
+    #
+    # @option options_hash [Boolean, nil] :chomp (true) remove trailing newlines from the output
+    #
+    # @option options_hash [Boolean, nil] :merge (false) merge stdout and stderr into a single output
+    #
+    # @option options_hash [String, nil] :chdir the directory to run the command in
+    #
+    # @option options_hash [Hash] :env additional environment variable overrides for this command
+    #
+    # @option options_hash [Boolean, nil] :raise_on_failure (true) whether to raise on non-zero exit
+    #
+    # @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.
+    #
+    #   If timeout is zero, the timeout will not be enforced.
+    #
+    #   If the command times out, it is killed via a `SIGKILL` signal and `Git::TimeoutError` is raised.
+    #
+    #   If the command does not respond to SIGKILL, it will hang this method.
+    #
+    # @note Individual command classes (under {Git::Commands}) can selectively
+    #   expose `:timeout` and `:env` to their callers by declaring them as
+    #   execution options in their Arguments DSL definition and forwarding
+    #   them to this method. See {Git::Commands::Clone#call} for an example
+    #   of a command that exposes `:timeout`.
+    #
+    # @see Git::CommandLine::Capturing#run
+    #
+    # @see #command_line_capturing
+    #
+    # @return [Git::CommandLineResult] the result of the command
+    #
+    # @raise [ArgumentError] if an unknown option is passed
+    #
+    # @raise [Git::FailedError] if the command failed (when raise_on_failure is true)
+    #
+    # @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
+    #   contain the result of the command including the exit status, stdout, and
+    #   stderr.
+    #
+    def command_capturing(*, **options_hash)
+      options_hash = COMMAND_CAPTURING_ARG_DEFAULTS.merge(options_hash)
+      options_hash[:timeout] ||= Git.config.timeout
+
+      extra_options = options_hash.keys - COMMAND_CAPTURING_ARG_DEFAULTS.keys
+      raise ArgumentError, "Unknown options: #{extra_options.join(', ')}" if extra_options.any?
+
+      env_overrides = options_hash.delete(:env)
+      raise_on_failure = options_hash.delete(:raise_on_failure)
+      command_line_capturing.run(*, raise_on_failure: raise_on_failure, env: env_overrides, **options_hash)
+    end
+
+    COMMAND_STREAMING_ARG_DEFAULTS = {
+      in: nil,
+      out: nil,
+      err: nil,
+      chdir: nil,
+      timeout: nil,
+      env: {},
+      raise_on_failure: true
+    }.freeze
 
-      ArgsBuilder.validate!(opts, PULL_OPTION_MAP)
+    # Runs a git command using the streaming (non-capturing) execution path
+    #
+    # Unlike {#command_capturing}, stdout is NOT buffered in memory. It is
+    # written only to the IO object provided via the `out:` option. Stderr is
+    # captured internally via a StringIO for error diagnostics.
+    #
+    # Use this entry point when you want to stream large output (e.g. blob
+    # content from cat-file) without creating memory pressure.
+    #
+    # @overload command_streaming(*args, **options_hash)
+    #
+    #   @param args [Array<String>] the git command and its arguments
+    #
+    #   @param options_hash [Hash] the options to pass to the command
+    #
+    # @option options_hash [IO, nil] :in stdin IO object
+    #
+    # @option options_hash [#write, nil] :out destination for streamed stdout
+    #
+    # @option options_hash [#write, nil] :err an optional additional destination to receive stderr output
+    #   in real time. Stderr is always captured internally; when `err:` is supplied, writes are teed
+    #   to both the internal buffer and this destination. `result.stderr` always reflects the internal capture.
+    #
+    # @option options_hash [String, nil] :chdir the directory to run the command in
+    #
+    # @option options_hash [Hash] :env additional environment variable overrides for this command
+    #
+    # @option options_hash [Boolean, nil] :raise_on_failure (true) whether to raise on non-zero exit
+    #
+    # @option options_hash [Numeric, nil] :timeout the maximum seconds to wait for the command
+    #
+    #   If nil, the global timeout from {Git::Config} is used.
+    #
+    # @return [Git::CommandLineResult] the result of the command
+    #
+    #   `result.stdout` will always be `''` — stdout was streamed to `out:`.
+    #   `result.stderr` contains any stderr output captured for diagnostics.
+    #
+    # @raise [ArgumentError] if an unknown option is passed
+    #
+    # @raise [Git::FailedError] if the command failed (when raise_on_failure is true)
+    #
+    # @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
+    #
+    # @see Git::CommandLine::Streaming#run
+    #
+    # @see #command_line_streaming
+    #
+    def command_streaming(*, **options_hash)
+      options_hash = COMMAND_STREAMING_ARG_DEFAULTS.merge(options_hash)
+      options_hash[:timeout] ||= Git.config.timeout
 
-      flags = build_args(opts, PULL_OPTION_MAP)
-      positional_args = [remote, branch].compact
+      extra_options = options_hash.keys - COMMAND_STREAMING_ARG_DEFAULTS.keys
+      raise ArgumentError, "Unknown options: #{extra_options.join(', ')}" if extra_options.any?
 
-      command('pull', *flags, *positional_args)
+      env_overrides = options_hash.delete(:env)
+      raise_on_failure = options_hash.delete(:raise_on_failure)
+      command_line_streaming.run(*, raise_on_failure: raise_on_failure, env: env_overrides, **options_hash)
     end
 
-    def tag_sha(tag_name)
-      head = File.join(@git_dir, 'refs', 'tags', tag_name)
-      return File.read(head).chomp if File.exist?(head)
-
-      begin
-        command('show-ref', '--tags', '-s', tag_name)
-      rescue Git::FailedError => e
-        raise unless e.result.status.exitstatus == 1 && e.result.stderr == ''
-
-        ''
-      end
-    end
+    private
 
-    def repack
-      command('repack', '-a', '-d')
+    def migrate_clean_legacy_options(opts)
+      opts = deprecate_clean_option(opts, :ff, ':ff option is deprecated. Use force: 2 instead.')
+      deprecate_clean_option(opts, :force_force, ':force_force option is deprecated. Use force: 2 instead.')
     end
 
-    def gc
-      command('gc', '--prune', '--aggressive', '--auto')
-    end
-
-    FSCK_OPTION_MAP = [
-      { flag: '--no-progress', type: :static },
-      { keys: [:unreachable],       flag: '--unreachable',       type: :boolean },
-      { keys: [:strict],            flag: '--strict',            type: :boolean },
-      { keys: [:connectivity_only], flag: '--connectivity-only', type: :boolean },
-      { keys: [:root],              flag: '--root',              type: :boolean },
-      { keys: [:tags],              flag: '--tags',              type: :boolean },
-      { keys: [:cache],             flag: '--cache',             type: :boolean },
-      { keys: [:no_reflogs],        flag: '--no-reflogs',        type: :boolean },
-      { keys: [:lost_found],        flag: '--lost-found',        type: :boolean },
-      { keys: [:dangling],          flag: '--dangling',          type: :boolean_negatable },
-      { keys: [:full],              flag: '--full',              type: :boolean_negatable },
-      { keys: [:name_objects],      flag: '--name-objects',      type: :boolean_negatable },
-      { keys: [:references],        flag: '--references',        type: :boolean_negatable }
-    ].freeze
+    def deprecate_clean_option(opts, key, message)
+      return opts unless opts.key?(key)
 
-    def fsck(*objects, **opts)
-      args = ArgsBuilder.build(opts, FSCK_OPTION_MAP)
-      args.concat(objects) unless objects.empty?
-      # fsck returns non-zero exit status when issues are found:
-      # 1 = errors found, 2 = missing objects, 4 = warnings
-      # We still want to parse the output in these cases
-      output = begin
-        command('fsck', *args)
-      rescue Git::FailedError => e
-        raise unless [1, 2, 4].include?(e.result.status.exitstatus)
-
-        e.result.stdout
-      end
-      parse_fsck_output(output)
-    end
+      opts = opts.dup
+      deprecated_value = opts.delete(key)
+      validate_deprecated_clean_option_value!(key, deprecated_value)
 
-    READ_TREE_OPTION_MAP = [
-      { keys: [:prefix], flag: '--prefix', type: :valued_equals }
-    ].freeze
+      Git::Deprecation.warn(message)
+      return opts unless deprecated_value
 
-    def read_tree(treeish, opts = {})
-      ArgsBuilder.validate!(opts, READ_TREE_OPTION_MAP)
-      flags = build_args(opts, READ_TREE_OPTION_MAP)
-      command('read-tree', *flags, treeish)
+      opts[:force] = merge_clean_force_option(opts[:force], force_specified: force_option_specified?(opts))
+      opts
     end
 
-    def write_tree
-      command('write-tree')
+    def force_option_specified?(opts)
+      opts.key?(:force) && !opts[:force].nil?
     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}"
-      ArgsBuilder.validate!(opts, COMMIT_TREE_OPTION_MAP)
-
-      flags = build_args(opts, COMMIT_TREE_OPTION_MAP)
-      command('commit-tree', tree, *flags)
-    end
+    def validate_deprecated_clean_option_value!(key, value)
+      return if value.nil? || value == true || value == false
 
-    def update_ref(ref, commit)
-      command('update-ref', ref, commit)
+      raise ArgumentError, "#{key} option only accepts true, false, or nil"
     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 merge_clean_force_option(existing_force, force_specified: false)
+      return 2 unless force_specified
 
-    def checkout_index(opts = {})
-      ArgsBuilder.validate!(opts, CHECKOUT_INDEX_OPTION_MAP)
-      args = build_args(opts, CHECKOUT_INDEX_OPTION_MAP)
+      normalized_force = normalize_clean_force_option(existing_force)
 
-      if (path = opts[:path_limiter]) && path.is_a?(String)
-        args.push('--', path)
+      case normalized_force
+      when Integer then merge_integer_clean_force_option(normalized_force)
+      when false
+        2
+      else
+        normalized_force
       end
-
-      command('checkout-index', *args)
     end
 
-    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 = {})
-      ArgsBuilder.validate!(opts, ARCHIVE_OPTION_MAP)
-      file ||= temp_file_name
-      format, gzip = parse_archive_format_options(opts)
-
-      args = build_args(opts, ARCHIVE_OPTION_MAP)
-      args.unshift("--format=#{format}")
-      args << sha
-      args.push('--', opts[:path]) if opts[:path]
-
-      File.open(file, 'wb') { |f| command('archive', *args, out: f) }
-      apply_gzip(file) if gzip
+    def merge_integer_clean_force_option(normalized_force)
+      return normalized_force if normalized_force < 1
 
-      file
+      [normalized_force, 2].max
     end
 
-    # returns the current version of git, as an Array of Fixnums.
-    def current_command_version
-      output = command('version')
-      version = output[/\d+(\.\d+)+/]
-      version_parts = version.split('.').collect(&:to_i)
-      version_parts.fill(0, version_parts.length...3)
+    def normalize_clean_force_option(value)
+      case value
+      when true then 1
+      else value
+      end
     end
 
-    # Returns current_command_version <=> other_version
+    # Build a result hash from clone options for Git::Base.new
     #
-    # @example
-    #   lib.current_command_version #=> [2, 42, 0]
+    # Parses the clone directory from the git command's stderr output, which
+    # contains either:
+    #   Cloning into '<directory>'...
+    #   Cloning into bare repository '<directory>'...
     #
-    #   lib.compare_version_to(2, 41, 0) #=> 1
-    #   lib.compare_version_to(2, 42, 0) #=> 0
-    #   lib.compare_version_to(2, 43, 0) #=> -1
+    # @param command_line_result [Git::CommandLineResult] the result of the git clone command
     #
-    # @param other_version [Array<Object>] the other version to compare to
-    # @return [Integer] -1 if this version is less than other_version, 0 if equal, or 1 if greater than
+    # @param opts [Hash] execution context options (:log, :git_ssh)
     #
-    def compare_version_to(*other_version)
-      current_command_version <=> other_version
+    # @return [Hash] result hash with directory, log, and git_ssh keys
+    #
+    def build_clone_result(command_line_result, opts)
+      clone_dir, bare = parse_clone_stderr(command_line_result.stderr)
+      result = bare ? { repository: clone_dir } : { working_directory: clone_dir }
+      result[:log] = opts[:log] if opts[:log]
+      result[:git_ssh] = opts[:git_ssh] if opts.key?(:git_ssh)
+      result
     end
 
-    def required_command_version
-      [2, 28]
-    end
+    # Parse the clone directory and bare status from git clone's stderr output
+    #
+    # Git outputs the directory in an unencoded way (no `core.quotePath` or
+    # similar escaping applies to clone's stderr message). The message format
+    # is always:
+    #
+    #   Cloning into '<directory>'...
+    #   Cloning into bare repository '<directory>'...
+    #
+    # Because the directory name is not escaped, a name containing the
+    # literal sequence `'...` (single-quote followed by three dots) would
+    # be ambiguous. In practice this is extremely unlikely.
+    #
+    # @param stderr [String] stderr output from git clone
+    #
+    # @return [Array(String, Boolean)] the clone directory and whether it's a bare repository
+    #
+    # @raise [Git::UnexpectedResultError] if the stderr output cannot be parsed
+    #
+    def parse_clone_stderr(stderr)
+      match = stderr.match(/Cloning into (?:(bare repository) )?'(.+)'\.\.\./)
+      raise Git::UnexpectedResultError, "Unable to determine clone directory from: #{stderr}" unless match
 
-    def meets_required_version?
-      (current_command_version <=> required_command_version) >= 0
+      [match[2], !match[1].nil?]
     end
 
-    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
+    # Prefixes clone result path values with the chdir directory.
+    #
+    # Mutates the given result hash in place, updating any :working_directory
+    # and :repository entries to be rooted under the provided +chdir+ directory.
+    # If +chdir+ is nil, the hash is left unchanged.
+    #
+    # @param result [Hash] clone result hash containing path information
+    # @param chdir [String, nil] directory under which the repository was cloned
+    # @return [nil]
+    #
+    def prefix_clone_result_paths!(result, chdir)
+      return unless chdir
 
-      @version_checked = true
-      unless lib.meets_required_version?
-        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."
+      %i[working_directory repository].each do |key|
+        result[key] = File.join(chdir, result[key]) if result.key?(key)
       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
+    # Handles the deprecated :path option for Git::Lib#clone.
+    #
+    # If opts contains :path, emits a deprecation warning and migrates the
+    # value to :chdir (unless :chdir is already set). Mutates opts in place.
+    #
+    # @param opts [Hash] clone options, possibly containing :path
+    # @return [nil]
+    #
+    def deprecate_clone_path_option!(opts)
+      return unless opts.key?(:path)
 
-    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
+      Git::Deprecation.warn('The :path option for Git::Lib#clone is deprecated, use :chdir instead')
+      path = opts.delete(:path)
+      opts[:chdir] ||= path
+    end
 
-    FSCK_OBJECT_PATTERN = /\A(dangling|missing|unreachable) (\w+) ([0-9a-f]{40})(?: \((.+)\))?\z/
-    FSCK_WARNING_PATTERN = /\Awarning in (\w+) ([0-9a-f]{40}): (.+)\z/
-    FSCK_ROOT_PATTERN = /\Aroot ([0-9a-f]{40})\z/
-    FSCK_TAGGED_PATTERN = /\Atagged (\w+) ([0-9a-f]{40}) \((.+)\) in ([0-9a-f]{40})\z/
+    def deprecate_clone_recursive_option!(opts)
+      return unless opts.key?(:recursive)
 
-    private_constant :FSCK_OBJECT_PATTERN, :FSCK_WARNING_PATTERN, :FSCK_ROOT_PATTERN, :FSCK_TAGGED_PATTERN
+      Git::Deprecation.warn('The :recursive option for Git::Lib#clone is deprecated, use :recurse_submodules instead')
+      opts[:recurse_submodules] = opts.delete(:recursive)
+    end
 
-    private
+    def deprecate_clone_remote_option!(opts)
+      return unless opts.key?(:remote)
 
-    def parse_fsck_output(output)
-      result = { dangling: [], missing: [], unreachable: [], warnings: [], root: [], tagged: [] }
-      output.each_line { |line| parse_fsck_line(line.strip, result) }
-      Git::FsckResult.new(**result)
+      Git::Deprecation.warn('The :remote option for Git::Lib#clone is deprecated, use :origin instead')
+      opts[:origin] = opts.delete(:remote)
     end
 
-    def parse_fsck_line(line, result)
-      parse_fsck_object_line(line, result) ||
-        parse_fsck_warning_line(line, result) ||
-        parse_fsck_root_line(line, result) ||
-        parse_fsck_tagged_line(line, result)
+    def deprecate_clone_options!(opts)
+      deprecate_clone_path_option!(opts)
+      deprecate_clone_recursive_option!(opts)
+      deprecate_clone_remote_option!(opts)
     end
 
-    def parse_fsck_object_line(line, result)
-      return unless (match = FSCK_OBJECT_PATTERN.match(line))
+    def deprecate_commit_add_all_option!(opts)
+      return unless opts.key?(:add_all)
 
-      result[match[1].to_sym] << Git::FsckObject.new(type: match[2].to_sym, sha: match[3], name: match[4])
+      Git::Deprecation.warn('The :add_all option for Git::Lib#commit is deprecated, use :all instead')
+      opts[:all] = opts.delete(:add_all)
     end
 
-    def parse_fsck_warning_line(line, result)
-      return unless (match = FSCK_WARNING_PATTERN.match(line))
-
-      result[:warnings] << Git::FsckObject.new(type: match[1].to_sym, sha: match[2], message: match[3])
+    # Extracts execution context options from clone options.
+    #
+    # @param opts [Hash] clone options
+    # @return [Hash] hash with :log and :git_ssh keys if present
+    #
+    def extract_clone_execution_context_opts(opts)
+      result = {}
+      result[:log] = opts.delete(:log) if opts[:log]
+      result[:git_ssh] = opts.delete(:git_ssh) if opts.key?(:git_ssh)
+      result
     end
 
-    def parse_fsck_root_line(line, result)
-      return unless (match = FSCK_ROOT_PATTERN.match(line))
+    # Translate legacy merge option names to new interface
+    #
+    # @param opts [Hash] options with possibly legacy keys
+    # @return [Hash] options with new keys
+    #
+    def translate_merge_options(opts)
+      result = opts.dup
+
+      # :message => 'msg' becomes :m => 'msg' (git merge uses -m, not --message)
+      result[:m] = result.delete(:message) if result.key?(:message)
 
-      result[:root] << Git::FsckObject.new(type: :commit, sha: match[1])
+      result
     end
 
-    def parse_fsck_tagged_line(line, result)
-      return unless (match = FSCK_TAGGED_PATTERN.match(line))
+    # Extract name-status data from --raw output lines
+    #
+    # Raw lines have the format:
+    #   :old_mode new_mode old_sha new_sha status\tpath
+    # or for renames/copies:
+    #   :old_mode new_mode old_sha new_sha Rxx\told_path\tnew_path
+    #
+    # @param output [String] raw diff output
+    #
+    # @return [Hash] mapping of file paths to status tokens
+    #
+    def extract_name_status_from_raw(output)
+      output.split("\n").each_with_object({}) do |line, memo|
+        next unless line.start_with?(':')
 
-      result[:tagged] << Git::FsckObject.new(type: match[1].to_sym, sha: match[2], name: match[3])
+        parts = line[1..].split(/\s+/, 5)
+        status_and_paths = parts[4].split("\t")
+        status = status_and_paths[0]
+        path = status_and_paths.length > 2 ? status_and_paths[2] : status_and_paths[1]
+        memo[unescape_quoted_path(path)] = status
+      end
     end
 
-    def parse_diff_path_status(args)
-      command_lines('diff', *args).each_with_object({}) do |line, memo|
-        status, path = split_status_line(line)
-        memo[path] = status
-      end
+    # Extract only the patch text from combined numstat + shortstat + patch output
+    #
+    # When {Git::Commands::Diff} is called with `patch: true, numstat: true, shortstat: true`,
+    # the output contains numstat, shortstat, and patch sections. This method extracts
+    # only the patch portion (starting at "diff --git").
+    #
+    # @param output [String] combined command output
+    #
+    # @return [String] only the patch text
+    #
+    def extract_patch_text(output)
+      match = output.match(/^diff --git /m)
+      match ? output[match.begin(0)..] : output
     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
+    # Extract only the numstat lines from combined numstat + shortstat output
+    #
+    # When {Git::Commands::Diff} is called with `numstat: true, shortstat: true`,
+    # the output contains numstat lines followed by a shortstat summary line. This method
+    # filters out the shortstat line and empty lines, returning only the numstat lines.
+    #
+    # @param output [String] combined command output
+    #
+    # @return [Array<String>] only the numstat lines
+    #
+    def extract_numstat_lines(output)
+      output.split("\n").reject { |l| l.empty? || l.match?(/^\s*\d+\s+files?\s+changed/) }
     end
 
     def build_args(opts, option_map)
       Git::ArgsBuilder.new(opts, option_map).build
     end
 
+    def validate_tag_options!(opts)
+      needs_message = %i[a annotate s sign u local_user].any? { |k| opts[k] }
+      has_message = opts[:m] || opts[:message]
+
+      return unless needs_message && !has_message
+
+      raise ArgumentError, 'Cannot create an annotated or signed tag without a message.'
+    end
+
+    def delete_tag(name)
+      result = Git::Commands::Tag::Delete.new(self).call(name)
+      raise Git::FailedError, result if result.status.exitstatus.positive?
+
+      result.stdout
+    end
+
+    def create_tag(name, target, opts)
+      Git::Commands::Tag::Create.new(self).call(name, target, **opts).stdout
+    end
+
     def initialize_from_base(base_object)
       @git_dir = base_object.repo.to_s
       @git_index_file = base_object.index&.to_s
@@ -1798,15 +2479,6 @@ module Git
       @git_ssh = base_hash.key?(:git_ssh) ? base_hash[:git_ssh] : :use_global_config
     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[:git_ssh] = opts[:git_ssh] if opts.key?(:git_ssh)
-      base_opts
-    end
-
     def process_commit_headers(data)
       headers = { 'parent' => [] } # Pre-initialize for multiple parents
       each_cat_file_header(data) do |key, value|
@@ -1819,44 +2491,8 @@ module Git
       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)
+      Git::Commands::RevParse.new(self).call(branch_name, verify: true, quiet: true)
       :active
     rescue Git::FailedError => e
       # An exit status of 1 with empty stderr from `rev-parse --verify`
@@ -1866,23 +2502,14 @@ module Git
       :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"
+    def normalize_grep_opts(opts)
+      opts = opts.dup
+      opts[:pathspec] = opts.delete(:path_limiter) if opts.key?(:path_limiter)
+      opts
     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
+    def parse_grep_output(output)
+      Git::Parsers::Grep.parse(output)
     end
 
     def parse_diff_stats_output(lines)
@@ -1907,6 +2534,18 @@ module Git
       parts
     end
 
+    def parse_raw_diff_output(stdout)
+      stdout.split("\n").each_with_object({}) do |line, memo|
+        info, file = split_status_line(line)
+        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
+        }
+      end
+    end
+
     def build_final_stats_hash(file_stats)
       {
         total: build_total_stats(file_stats),
@@ -1952,45 +2591,48 @@ module Git
       [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
+    # Convert a StashInfo to the legacy [index, message] format
+    #
+    # The legacy format strips the "WIP on <branch>:" or "On <branch>:" prefix
+    # from the message and returns only the suffix.
+    #
+    # @param info [Git::StashInfo] the stash info object
+    # @return [Array(Integer, String)] `[index, message]` pair with prefix stripped
+    #
+    # @api private
+    #
+    def stash_info_to_legacy(info, index = info.index)
+      full_message = info.message
       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
+    # Streams the staged content of a file at a given index stage to an IO object
+    #
+    # Uses the streaming execution path so content is written directly to `out_io`
+    # without being buffered in memory.
+    #
+    # @api private
     #
     # @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 stage [Integer] the index stage to read (e.g., `1` ancestor, `2` ours, `3` theirs)
+    #
+    # @param out_io [IO] the `IO` object to stream the staged content into
+    #
+    # @return [IO] `out_io`, as passed in
     #
-    # @param out_io [IO] the IO object to write the staged content to
+    # @raise [Git::FailedError] if the object does not exist or git exits non-zero
     #
-    # @return [IO] the IO object that was written to
+    # @raise [Git::TimeoutError] if the command exceeds the configured timeout
     #
     def write_staged_content(path, stage, out_io)
-      command('show', ":#{stage}:#{path}", out: out_io)
+      Git::Commands::Show.new(self).call(":#{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
@@ -2006,15 +2648,22 @@ module Git
       [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)
+    def validate_push_args!(remote, branch, opts)
+      assert_valid_opts(opts, PUSH_ALLOWED_OPTS)
+      raise ArgumentError, 'remote is required if branch is specified' if !remote && branch
+    end
+
+    def push_refs(remote, branch, opts)
+      positionals = [remote, branch].compact
+      Git::Commands::Push.new(self).call(*positionals, **opts.except(:tags))
+    end
+
+    def push_tags_separately?(opts)
+      opts[:tags] && !opts[:mirror]
+    end
 
-      # 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
+    def push_tags(remote, opts)
+      Git::Commands::Push.new(self).call(*[remote].compact, **opts)
     end
 
     def temp_file_name
@@ -2036,16 +2685,6 @@ module Git
       Zlib::GzipWriter.open(file) { |gz| gz.write(file_content) }
     end
 
-    def command_lines(cmd, *opts, chdir: nil)
-      cmd_op = command(cmd, *opts, chdir: chdir)
-      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
-
     # Returns a hash of environment variable overrides for git commands
     #
     # This method builds a hash of environment variables that control git's behavior,
@@ -2086,6 +2725,7 @@ module Git
         'GIT_WORK_TREE' => @git_work_dir,
         'GIT_INDEX_FILE' => @git_index_file,
         'GIT_SSH' => resolved_git_ssh,
+        'GIT_EDITOR' => 'true', # Use a no-op editor so Git skips interactive editing but continues
         'LC_ALL' => 'en_US.UTF-8'
       }.merge(additional_overrides)
     end
@@ -2113,154 +2753,103 @@ module Git
       end
     end
 
-    def command_line
-      @command_line ||=
-        Git::CommandLine.new(env_overrides, Git::Base.config.binary_path, global_opts, @logger)
-    end
-
-    # Returns a command line instance without GIT_INDEX_FILE for worktree commands
+    # Returns the {Git::CommandLine::Capturing} instance used for capturing execution
     #
-    # Git worktrees manage their own index files and setting GIT_INDEX_FILE
-    # causes corruption of both the main worktree and new worktree indexes.
+    # Memoized factory for the capturing execution path.  Instantiates
+    # {Git::CommandLine::Capturing} with the current environment, binary path,
+    # global options, and logger.
     #
-    # @return [Git::CommandLine]
-    # @api private
+    # @return [Git::CommandLine::Capturing]
+    #
+    # @see Git::CommandLine::Capturing#run
     #
-    def worktree_command_line
-      @worktree_command_line ||=
-        Git::CommandLine.new(env_overrides('GIT_INDEX_FILE' => nil), Git::Base.config.binary_path, global_opts,
-                             @logger)
+    def command_line_capturing
+      @command_line_capturing ||=
+        Git::CommandLine::Capturing.new(env_overrides, Git::Base.config.binary_path, global_opts, @logger)
     end
 
-    # @overload worktree_command(*args, **options_hash)
-    #   Runs a git worktree command and returns the output
-    #
-    #   This method is similar to #command but uses a command line instance
-    #   that excludes GIT_INDEX_FILE from the environment to prevent index corruption.
-    #
-    #   @param args [Array<String>] the command arguments
-    #   @param options_hash [Hash] the options to pass to the command
+    # Returns the {Git::CommandLine::Streaming} instance used for streaming execution
     #
-    #   @return [String] the command's stdout
+    # Memoized factory for the streaming execution path.  Instantiates
+    # {Git::CommandLine::Streaming} with the current environment, binary path,
+    # global options, and logger.
     #
-    # @see #command
+    # @return [Git::CommandLine::Streaming]
     #
-    # @api private
+    # @see Git::CommandLine::Streaming#run
     #
-    def worktree_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 = worktree_command_line.run(*, **options_hash)
-      result.stdout
+    def command_line_streaming
+      @command_line_streaming ||=
+        Git::CommandLine::Streaming.new(env_overrides, Git::Base.config.binary_path, global_opts, @logger)
     end
 
-    # Runs a git command and returns the output
-    #
-    # 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.
-    #
-    # For example, to run `git log --pretty=oneline`, you would create the array
-    # `args = ['log', '--pretty=oneline']` and call `command(*args)`.
-    #
-    # @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.
-    #
-    #   If timeout is zero, the timeout will not be enforced.
-    #
-    #   If the command times out, it is killed via a `SIGKILL` signal and `Git::TimeoutError` is raised.
-    #
-    #   If the command does not respond to SIGKILL, it will hang this method.
-    #
-    # @see Git::CommandLine#run
-    #
-    # @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
-    #   contain the result of the command including the exit status, stdout, and
-    #   stderr.
-    #
-    # @api private
+    # Validates the :count option for log commands.
     #
-    def command(*, **options_hash)
-      options_hash = COMMAND_ARG_DEFAULTS.merge(options_hash)
-      options_hash[:timeout] ||= Git.config.timeout
+    def validate_log_count_option!(opts)
+      return unless opts[:count] && !opts[:count].is_a?(Integer)
 
-      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
+      raise ArgumentError, "The log count option must be an Integer but was #{opts[:count].inspect}"
     end
 
-    # Takes the diff command line output (as Array) and parse it into a Hash
+    # Builds the positional revision range argument(s) from opts for Git::Commands::Log
     #
-    # @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 = [])
-      # update index before diffing to avoid spurious diffs
-      command('status')
-      command_lines(diff_command, *opts).each_with_object({}) do |line, memo|
-        info, file = split_status_line(line)
-        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
-        }
+    # @param opts [Hash]
+    # @return [Array<String>] zero or one element array with the revision range expression
+    def log_revision_range_args(opts)
+      if opts[:between]
+        ["#{opts[:between][0]}..#{opts[:between][1]}"]
+      elsif opts[:object].is_a?(String)
+        [opts[:object]]
+      else
+        []
       end
     end
 
-    # Returns an array holding the common options for the log commands
+    # Builds the common keyword options for Git::Commands::Log from opts
     #
-    # @param [Hash] opts the given options
-    # @return [Array] the set of common options that the log command will use
-    def log_common_options(opts)
-      if opts[:count] && !opts[:count].is_a?(Integer)
-        raise ArgumentError, "The log count option must be an Integer but was #{opts[:count].inspect}"
+    # @param opts [Hash]
+    # @param extra [Hash] additional options to merge in (caller-specific)
+    # @return [Hash] keyword arguments for Git::Commands::Log#call
+    def log_base_call_options(opts, extra = {})
+      {
+        all: opts[:all],
+        cherry: opts[:cherry],
+        since: opts[:since],
+        until: opts[:until],
+        grep: opts[:grep],
+        author: opts[:author],
+        max_count: opts[:count],
+        path: opts[:path_limiter] ? Array(opts[:path_limiter]) : nil
+      }.merge(extra).compact
+    end
+
+    def run_log_command(revision_range_args, call_opts)
+      log_or_empty_on_unborn do
+        result = Git::Commands::Log.new(self).call(
+          *revision_range_args,
+          no_color: true, pretty: 'raw',
+          **call_opts
+        )
+        process_commit_log_data(result.stdout.split("\n"))
       end
-
-      build_args(opts, LOG_OPTION_MAP)
     end
 
-    # Retrurns an array holding path options for the log commands
-    #
-    # @param [Hash] opts the given options
-    # @return [Array] the set of path options that the log command will use
-    def log_path_options(opts)
-      arr_opts = []
+    def log_or_empty_on_unborn
+      yield
+    rescue Git::FailedError => e
+      raise unless e.result.status.exitstatus == 128 &&
+                   e.result.stderr =~ /does not have any commits yet/
+
+      []
+    end
 
-      arr_opts << opts[:object] if opts[:object].is_a? String
-      if opts[:path_limiter]
-        arr_opts << '--'
-        arr_opts += Array(opts[:path_limiter])
+    def normalize_commit_tree_opts(opts, tree)
+      opts.dup.tap do |actual_opts|
+        actual_opts[:p] = actual_opts.delete(:parents) if actual_opts.key?(:parents)
+        actual_opts[:p] = actual_opts.delete(:parent) if actual_opts.key?(:parent)
+        actual_opts[:m] = actual_opts.delete(:message) if actual_opts.key?(:message)
+        actual_opts[:m] = "commit tree #{tree}" if actual_opts[:m].nil?
       end
-      arr_opts
     end
   end
 end