git 4.4.3 → 5.0.0.beta.1

data/lib/git/base.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require 'logger'
+require 'pathname'
+require 'git/repository/path_resolver'
 
 module Git
   # The main public interface for interacting with Git commands
@@ -14,22 +16,27 @@ module Git
   class Base
     # (see Git.bare)
     def self.bare(git_dir, options = {})
-      normalize_paths(options, default_repository: git_dir, bare: true)
-      new(options)
+      paths = Git::Repository::PathResolver.resolve_paths(repository: git_dir, bare: true)
+      new(options.merge(paths))
     end
 
     # (see Git.clone)
     def self.clone(repository_url, directory, options = {})
       lib_options = {}
       lib_options[:git_ssh] = options[:git_ssh] if options.key?(:git_ssh)
-      new_options = LibImpl.new(lib_options, options[:log]).clone(repository_url, directory, options)
-      normalize_paths(new_options, bare: options[:bare] || options[:mirror])
-      new(new_options)
+      clone_result = Git::Lib.new(lib_options, options[:log]).clone(repository_url, directory, options)
+      bare = options[:bare] || options[:mirror]
+      paths = Git::Repository::PathResolver.resolve_paths(
+        working_directory: clone_result[:working_directory],
+        repository: clone_result[:repository],
+        bare: bare
+      )
+      new(options.merge(paths))
     end
 
     # (see Git.default_branch)
     def self.repository_default_branch(repository, options = {})
-      LibImpl.new(nil, options[:log]).repository_default_branch(repository)
+      Git::Lib.new(nil, options[:log]).repository_default_branch(repository)
     end
 
     # Returns (and initialize if needed) a Git::Config instance
@@ -39,96 +46,32 @@ module Git
       @config ||= Config.new
     end
 
+    # @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 self.binary_version(binary_path)
-      parse_version_string(execute_git_version(binary_path))
-    end
-
-    private_class_method def self.execute_git_version(binary_path)
-      bootstrap_command_line(binary_path).run('version', merge: true).stdout
-    rescue Git::CommandLineError => e
-      raise "Failed to get git version: #{e.result.status}\n#{e.result.stdout}"
-    rescue Errno::ENOENT, ProcessExecuter::SpawnError
-      raise "Failed to get git version: #{binary_path} not found"
-    end
-
-    private_class_method def self.parse_version_string(raw_string)
-      version_match = raw_string.match(/\d+(\.\d+)+/)
-      return [0, 0, 0] unless version_match
-
-      version_parts = version_match[0].split('.').map(&:to_i)
-      version_parts.fill(0, version_parts.length...3)
-    end
-
-    # (see Git.init)
-    def self.init(directory = '.', options = {})
-      normalize_paths(options, default_working_directory: directory, default_repository: directory,
-                               bare: options[:bare])
-
-      init_options = {
-        bare: options[:bare],
-        initial_branch: options[:initial_branch]
-      }
-
-      directory = options[:bare] ? options[:repository] : options[:working_directory]
-      FileUtils.mkdir_p(directory)
-
-      # TODO: this dance seems awkward: this creates a Git::Lib so we can call
-      #   init so we can create a new Git::Base which in turn (ultimately)
-      #   creates another/different Git::Lib.
-      #
-      # TODO: maybe refactor so this Git::Bare.init does this:
-      #   self.new(opts).init(init_opts) and move all/some of this code into
-      #   Git::Bare#init. This way the init method can be called on any
-      #   repository you have a Git::Base instance for.  This would not
-      #   change the existing interface (other than adding to it).
-      #
-      LibImpl.new(options).init(init_options)
-
-      new(options)
-    end
-
-    def self.root_of_worktree(working_dir)
-      raise ArgumentError, "'#{working_dir}' does not exist" unless Dir.exist?(working_dir)
-
-      execute_rev_parse_toplevel(working_dir)
-    end
-
-    private_class_method def self.execute_rev_parse_toplevel(working_dir)
-      bootstrap_command_line(Git::Base.config.binary_path).run(
-        'rev-parse', '--show-toplevel', chdir: File.expand_path(working_dir), merge: true, chomp: true
-      ).stdout
-    rescue Git::CommandLineError
-      raise ArgumentError, "'#{working_dir}' is not in a git working tree"
-    rescue Errno::ENOENT, ProcessExecuter::SpawnError
-      raise ArgumentError, 'Failed to find the root of the worktree: git binary not found'
+      Git::Deprecation.warn(
+        'Git::Base.binary_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.git_version(binary_path).to_a
     end
 
-    # A command line for the git commands that run before a repository is known
+    # Find the root of the working tree that contains `working_dir`
     #
-    # `Open3` is deliberately not used here. Windows has no fork, so
-    # `Process.spawn` implements a redirect of the child's stdin by redirecting
-    # the *parent's* stdin and restoring it afterward, which replaces the
-    # process's stdin handle. That leaves a console REPL such as irb or pry
-    # unable to read input for the rest of the session. `Git::CommandLine`
-    # redirects only stdout and stderr, so stdin is never disturbed.
+    # Delegates to {Git::Repository::PathResolver.root_of_worktree}, using the
+    # global config for `binary_path` and `git_ssh`.
     #
-    # @see https://github.com/ruby-git/ruby-git/issues/840 issue 840
+    # @param working_dir [String] a path inside the working tree
     #
-    # @param binary_path [String] the path to the git binary to run
+    # @return [String] the absolute path to the root of the working tree
     #
-    # @return [Git::CommandLine] a command line that runs `binary_path` with
-    #   `-c core.quotePath=true -c color.ui=false`
+    # @raise [ArgumentError] if `working_dir` does not exist or is not inside a
+    #   git working tree
     #
-    #   Those are the options the `Open3` calls this replaced passed, kept as they were
-    #   so these two commands behave exactly as before. Neither `git version` nor
-    #   `git rev-parse --show-toplevel` emits colored output, so the remaining `color.*`
-    #   settings in {Git::Lib}'s `STATIC_GLOBAL_OPTS` are not needed here.
-    #
-    # @api private
-    #
-    private_class_method def self.bootstrap_command_line(binary_path)
-      Git::CommandLine.new({}, binary_path, ['-c', 'core.quotePath=true', '-c', 'color.ui=false'],
-                           Logger.new(nil))
+    def self.root_of_worktree(working_dir)
+      Git::Repository::PathResolver.root_of_worktree(working_dir)
     end
 
     # (see Git.open)
@@ -137,9 +80,13 @@ module Git
 
       working_dir = root_of_worktree(working_dir) unless options[:repository]
 
-      normalize_paths(options, default_working_directory: working_dir)
+      paths = Git::Repository::PathResolver.resolve_paths(
+        working_directory: working_dir,
+        repository: options[:repository],
+        index: options[:index]
+      )
 
-      new(options)
+      new(options.merge(paths))
     end
 
     # Create an object that executes Git commands in the context of a working
@@ -148,51 +95,100 @@ module Git
     # @param [Hash] options The options for this command (see list of valid
     #   options below)
     #
-    # @option options [Pathname] :working_dir the path to the root of the working
-    #   directory.  Should be `nil` if executing commands on a bare repository.
+    # @option options [Pathname] :working_directory the path to the root of the working
+    #   directory or `nil` if executing commands on a bare repository
     #
     # @option options [Pathname] :repository used to specify a non-standard path to
-    #   the repository directory.  The default is `"#{working_dir}/.git"`.
+    #   the repository directory
+    #
+    #   The default is `"<working_directory>/.git"`.
     #
     # @option options [Pathname] :index used to specify a non-standard path to an
-    #   index file.  The default is `"#{working_dir}/.git/index"`
+    #   index file
     #
-    # @option options [Logger] :log A logger to use for Git operations.  Git
-    #   commands are logged at the `:info` level.  Additional logging is done
+    #   The default is `"<working_directory>/.git/index"`
+    #
+    # @option options [Logger] :log A logger to use for Git operations
+    #
+    #   Git commands are logged at the `:info` level.  Additional logging is done
     #   at the `:debug` level.
     #
-    # @option options [String, nil] :git_ssh Path to a custom SSH executable or script.
+    # @option options [String, nil] :git_ssh Path to a custom SSH executable or script
+    #
     #   Controls how SSH is configured for this {Git::Base} instance:
     #   - If this option is not provided, the global Git::Base.config.git_ssh setting is used.
     #   - If this option is explicitly set to nil, SSH is disabled for this instance.
     #   - If this option is a non-empty String, that value is used as the SSH command for
     #     this instance, overriding the global Git::Base.config.git_ssh setting.
     #
-    # @return [Git::Base] an object that can execute git commands in the context
-    #   of the opened working copy or bare repository
+    # @option options [String, :use_global_config] :binary_path Path to the git binary
+    #
+    #   Controls which git binary is used for commands routed through
+    #   {Git::ExecutionContext} (i.e., commands already migrated to
+    #   +Git::Commands::*+ classes). Commands still delegating through +Git::Lib+
+    #   continue to use the global `Git::Base.config.binary_path` setting.
+    #
+    #   This limitation will be resolved when the architectural migration to
+    #   +Git::Repository+ is complete.
+    #
+    #   - If this option is not provided, the global Git::Base.config.binary_path setting is used.
+    #   - If this option is a String, that value is used as the git binary path for
+    #     migrated commands, overriding the global Git::Base.config.binary_path setting.
+    #   - Passing `nil` raises ArgumentError — there is no "unset the binary" semantic.
+    #
+    # @return [Git::Base] an object that can execute git commands on a working copy or
+    #   bare repository
+    #
+    # @raise [ArgumentError] if `binary_path` is `nil`
     #
     def initialize(options = {})
-      options = default_paths(options)
       setup_logger(options[:log])
       @git_ssh = options.key?(:git_ssh) ? options[:git_ssh] : :use_global_config
+      if options.key?(:binary_path)
+        raise ArgumentError, 'binary_path must not be nil' if options[:binary_path].nil?
+
+        @binary_path = options[:binary_path]
+      else
+        @binary_path = :use_global_config
+      end
       initialize_components(options)
     end
 
-    # Update the index from the current worktree to prepare the for the next commit
+    # Update the index from the current worktree to prepare for the next commit
     #
-    # @example
-    #   lib.add('path/to/file')
-    #   lib.add(['path/to/file1','path/to/file2'])
-    #   lib.add(all: true)
+    # @overload add(paths = '.', **options)
+    #
+    #   @example Stage all changed files
+    #     git.add
+    #
+    #   @example Stage a specific file
+    #     git.add('path/to/file.rb')
     #
-    # @param [String, Array<String>] paths a file or files to be added to the repository (relative to the worktree root)
-    # @param [Hash] options
+    #   @example Stage multiple files
+    #     git.add(['path/to/file1.rb', 'path/to/file2.rb'])
     #
-    # @option options [Boolean] :all Add, modify, and remove index entries to match the worktree
-    # @option options [Boolean] :force Allow adding otherwise ignored files
+    #   @example Stage all changes including deletions
+    #     git.add(all: true)
     #
-    def add(paths = '.', **options)
-      lib.add(paths, options)
+    #   @param paths [String, Array<String>] a file or files to add (relative to
+    #     the worktree root); defaults to `'.'` (all files)
+    #
+    #   @param options [Hash] options for the add command
+    #
+    #   @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] git's stdout from the add
+    #
+    #   @raise [ArgumentError] if unsupported options are provided
+    #
+    #   @raise [Git::FailedError] if git exits with a non-zero exit status
+    #
+    def add(paths = '.', **)
+      facade_repository.add(paths, **)
     end
 
     # adds a new remote to this repository
@@ -206,9 +202,7 @@ module Git
     #   :fetch => true
     #   :track => <branch_name>
     def add_remote(name, url, opts = {})
-      url = url.repo.to_s if url.is_a?(Git::Base)
-      lib.remote_add(name, url, opts)
-      Git::Remote.new(self, name)
+      facade_repository.add_remote(name, url, opts)
     end
 
     # changes current working directory for a block
@@ -220,42 +214,46 @@ module Git
     #    @git.add
     #    @git.commit('message')
     #  end
-    def chdir # :yields: the Git::Path
+    def chdir # :yields: the working directory Pathname
       Dir.chdir(dir.to_s) do
-        yield dir.to_s
+        yield dir
       end
     end
 
     # g.config('user.name', 'Scott Chacon') # sets value
     # g.config('user.email', 'email@email.com')  # sets value
-    # g.config('user.email', 'email@email.com', file: 'path/to/custom/config)  # sets value in file
+    # g.config('user.email', 'email@email.com', file: 'path/to/custom/config')  # sets value in file
     # g.config('user.name')  # returns 'Scott Chacon'
     # g.config # returns whole config hash
     def config(name = nil, value = nil, options = {})
-      if name && value
-        # set value
-        lib.config_set(name, value, options)
-      elsif name
-        # return value
-        lib.config_get(name)
-      else
-        # return hash
-        lib.config_list
-      end
+      facade_repository.config(name, value, options)
     end
 
-    # returns a reference to the working directory
-    #  @git.dir.path
-    #  @git.dir.writeable?
+    # Returns a reference to the working directory
+    #
+    # @example
+    #   @git.dir.to_s
+    #   @git.dir.writable?
+    #
+    # @return [Pathname] the working directory path
+    #
     def dir
       @working_directory
     end
 
-    # returns reference to the git index file
+    # Returns a reference to the git index file
+    #
+    # @return [Pathname] the index file path
+    #
     attr_reader :index
 
-    # returns reference to the git repository directory
-    #  @git.dir.path
+    # Returns a reference to the git repository directory
+    #
+    # @example
+    #   @git.repo.to_s
+    #
+    # @return [Pathname] the repository directory path
+    #
     def repo
       @repository
     end
@@ -270,43 +268,46 @@ module Git
                .sum { |file| File.stat(file).size.to_i }
     end
 
-    def set_index(index_file, check = nil, must_exist: nil)
+    private
+
+    def deprecate_check_argument(check, must_exist)
       unless check.nil?
         Git::Deprecation.warn(
           'The "check" argument is deprecated and will be removed in a future version. ' \
           'Use "must_exist:" instead.'
         )
       end
-
       # default is true
-      must_exist = must_exist.nil? && check.nil? ? true : must_exist | check
-
-      @lib = nil
-      @index = Git::Index.new(index_file.to_s, must_exist:)
+      must_exist.nil? && check.nil? ? true : must_exist | check
     end
 
-    def set_working(work_dir, check = nil, must_exist: nil)
-      unless check.nil?
-        Git::Deprecation.warn(
-          'The "check" argument is deprecated and will be removed in a future version. ' \
-          'Use "must_exist:" instead.'
-        )
+    def validate_path(path, must_exist)
+      Pathname.new(File.expand_path(path.to_s)).tap do |expanded_path|
+        raise ArgumentError, "path does not exist: #{expanded_path}" if must_exist && !expanded_path.exist?
       end
+    end
 
-      # default is true
-      must_exist = must_exist.nil? && check.nil? ? true : must_exist | check
+    public
 
+    def set_index(index_file, check = nil, must_exist: nil)
+      must_exist = deprecate_check_argument(check, must_exist)
       @lib = nil
-      @working_directory = Git::WorkingDirectory.new(work_dir.to_s, must_exist:)
+      @facade_repository = nil
+      @index = validate_path(index_file, must_exist)
+    end
+
+    def set_working(work_dir, check = nil, must_exist: nil)
+      must_exist = deprecate_check_argument(check, must_exist)
+      @lib = nil
+      @facade_repository = nil
+      @working_directory = validate_path(work_dir, must_exist)
     end
 
     # returns +true+ if the branch exists locally
     def local_branch?(branch)
-      branch_names = branches.local.map(&:name)
-      branch_names.include?(branch)
+      facade_repository.local_branch?(branch)
     end
 
-    # @deprecated Use {#local_branch?} instead
     def is_local_branch?(branch) # rubocop:disable Naming/PredicatePrefix
       Git::Deprecation.warn(
         'Git::Base#is_local_branch? is deprecated and will be removed in a future version. ' \
@@ -317,11 +318,9 @@ module Git
 
     # returns +true+ if the branch exists remotely
     def remote_branch?(branch)
-      branch_names = branches.remote.map(&:name)
-      branch_names.include?(branch)
+      facade_repository.remote_branch?(branch)
     end
 
-    # @deprecated Use {#remote_branch?} instead
     def is_remote_branch?(branch) # rubocop:disable Naming/PredicatePrefix
       Git::Deprecation.warn(
         'Git::Base#is_remote_branch? is deprecated and will be removed in a future version. ' \
@@ -332,11 +331,9 @@ module Git
 
     # returns +true+ if the branch exists
     def branch?(branch)
-      branch_names = branches.map(&:name)
-      branch_names.include?(branch)
+      facade_repository.branch?(branch)
     end
 
-    # @deprecated Use {#branch?} instead
     def is_branch?(branch) # rubocop:disable Naming/PredicatePrefix
       Git::Deprecation.warn(
         'Git::Base#is_branch? is deprecated and will be removed in a future version. ' \
@@ -349,10 +346,20 @@ module Git
     # actual 'git' forked system calls.  At some point I hope to replace the Git::Lib
     # class with one that uses native methods or libgit C bindings
     def lib
-      @lib ||= LibImpl.new(self, @logger)
+      @lib ||= Git::Lib.new(self, @logger)
+    end
+
+    # Returns the {Git::Repository} facade for this repository
+    #
+    # @return [Git::Repository]
+    # @api private
+    def facade_repository
+      @facade_repository ||= Git::Repository.new(
+        execution_context: Git::ExecutionContext::Repository.from_base(self, logger: @logger)
+      )
     end
 
-    # Returns the per-instance git_ssh configuration value.
+    # Returns the per-instance git_ssh configuration value
     #
     # This may be:
     # * a [String] path when an explicit git_ssh command has been configured
@@ -363,6 +370,16 @@ module Git
     # @api private
     attr_reader :git_ssh
 
+    # Returns the per-instance git binary path configuration value
+    #
+    # This may be:
+    # * a [String] path when an explicit binary path has been configured
+    # * the Symbol `:use_global_config` when this instance is using the global config
+    #
+    # @return [String, Symbol] the binary_path configuration value for this instance
+    # @api private
+    attr_reader :binary_path
+
     # Run a grep for 'string' on the HEAD of the git repository
     #
     # @example Limit grep's scope by calling grep() from a specific object:
@@ -381,9 +398,9 @@ module Git
     #   of paths to limit the search to or nil for no limit
     # @param opts [Hash] options to pass to the underlying `git grep` command
     #
-    # @option opts [Boolean] :ignore_case (false) ignore case when matching
-    # @option opts [Boolean] :invert_match (false) select non-matching lines
-    # @option opts [Boolean] :extended_regexp (false) use extended regular expressions
+    # @option opts [Boolean, nil] :ignore_case (nil) ignore case when matching
+    # @option opts [Boolean, nil] :invert_match (nil) select non-matching lines
+    # @option opts [Boolean, nil] :extended_regexp (nil) use extended regular expressions
     # @option opts [String] :object (HEAD) the object to search from
     #
     # @return [Hash<String, Array>] a hash of arrays
@@ -396,30 +413,38 @@ module Git
     #   ```
     #
     def grep(string, path_limiter = nil, opts = {})
-      object('HEAD').grep(string, path_limiter, opts)
+      opts = opts.merge(object: facade_repository.rev_parse('HEAD')) unless opts.key?(:object)
+      facade_repository.grep(string, path_limiter, opts)
     end
 
     # List the files in the worktree that are ignored by git
-    # @return [Array<String>] the list of ignored files relative to teh root of the worktree
+    # @return [Array<String>] the list of ignored files relative to the root of the worktree
     #
     def ignored_files
-      lib.ignored_files
+      facade_repository.ignored_files
     end
 
     # removes file(s) from the git repository
     def rm(path = '.', opts = {})
-      lib.rm(path, opts)
+      facade_repository.rm(path, opts)
     end
 
     alias remove rm
 
     # resets the working directory to the provided commitish
     def reset(commitish = nil, opts = {})
-      lib.reset(commitish, opts)
+      facade_repository.reset(commitish, **opts)
     end
 
     # resets the working directory to the commitish with '--hard'
+    #
+    # @deprecated Use {#reset} with `hard: true` instead.
+    #
     def reset_hard(commitish = nil, opts = {})
+      Git::Deprecation.warn(
+        'Git::Base#reset_hard is deprecated and will be removed in a future version. ' \
+        'Use Git::Base#reset(commitish, hard: true) instead.'
+      )
       opts = { hard: true }.merge(opts)
       lib.reset(commitish, opts)
     end
@@ -432,7 +457,7 @@ module Git
     #  :ff
     #
     def clean(opts = {})
-      lib.clean(opts)
+      facade_repository.clean(opts)
     end
 
     #  returns the most recent tag that is reachable from a commit
@@ -461,7 +486,7 @@ module Git
     #   :no_edit
     #
     def revert(commitish = nil, opts = {})
-      lib.revert(commitish, opts)
+      facade_repository.revert(commitish, **opts)
     end
 
     # commits all pending changes in the index file to the git repository
@@ -473,69 +498,71 @@ module Git
     #   :author
     #
     def commit(message, opts = {})
-      lib.commit(message, opts)
+      facade_repository.commit(message, **opts)
     end
 
     # commits all pending changes in the index file to the git repository,
     # but automatically adds all modified files without having to explicitly
     # calling @git.add() on them.
     def commit_all(message, opts = {})
-      opts = { add_all: true }.merge(opts)
-      lib.commit(message, opts)
+      facade_repository.commit_all(message, **opts)
     end
 
     # checks out a branch as the new git working directory
     def checkout(*, **)
-      lib.checkout(*, **)
+      facade_repository.checkout(*, **)
     end
 
     # checks out an old version of a file
     def checkout_file(version, file)
-      lib.checkout_file(version, file)
+      facade_repository.checkout_file(version, file)
     end
 
     # fetches changes from a remote branch - this does not modify the working directory,
     # it just gets the changes from the remote if there are any
     def fetch(remote = 'origin', opts = {})
-      if remote.is_a?(Hash)
-        opts = remote
-        remote = nil
-      end
-      lib.fetch(remote, opts)
+      facade_repository.fetch(remote, opts)
     end
 
     # Push changes to a remote repository
     #
     # @overload push(remote = nil, branch = nil, options = {})
+    #
     #   @param remote [String] the remote repository to push to
+    #
     #   @param branch [String] the branch to push
+    #
     #   @param options [Hash] options to pass to the push command
     #
-    #   @option opts [Boolean] :mirror (false) Push all refs under refs/heads/, refs/tags/ and refs/remotes/
-    #   @option opts [Boolean] :delete (false) Delete refs that don't exist on the remote
-    #   @option opts [Boolean] :force (false) Force updates
-    #   @option opts [Boolean] :tags (false) Push all refs under refs/tags/
-    #   @option opts [Array, String] :push_options (nil) Push options to transmit
+    #   @option options [Boolean, nil] :mirror (nil) push all refs under refs/heads/, refs/tags/ and refs/remotes/
+    #
+    #   @option options [Boolean, nil] :delete (nil) delete refs that don't exist on the remote
+    #
+    #   @option options [Boolean, nil] :force (nil) force updates
+    #
+    #   @option options [Boolean, nil] :tags (nil) push all refs under refs/tags/
     #
-    #   @return [Void]
+    #   @option options [String, Array<String>] :push_option (nil) push options to transmit
+    #
+    #   @return [String] the stdout output from the push command
     #
     #   @raise [Git::FailedError] if the push fails
     #   @raise [ArgumentError] if a branch is given without a remote
     #
     def push(*, **)
-      lib.push(*, **)
+      facade_repository.push(*, **)
     end
 
     # merges one or more branches into the current working branch
     #
     # you can specify more than one branch to merge by passing an array of branches
     def merge(branch, message = 'merge', opts = {})
-      lib.merge(branch, message, opts)
+      facade_repository.merge(branch, message, opts)
     end
 
     # iterates over the files which are unmerged
-    def each_conflict(&) # :yields: file, your_version, their_version
-      lib.conflicts(&)
+    def each_conflict(&)
+      facade_repository.each_conflict(&)
     end
 
     # Pulls the given branch from the given remote into the current branch
@@ -544,7 +571,7 @@ module Git
     # @param branch [String] the branch to pull from
     # @param opts [Hash] options to pass to the pull command
     #
-    # @option opts [Boolean] :allow_unrelated_histories (false) Merges histories of
+    # @option opts [Boolean, nil] :allow_unrelated_histories (nil) merges histories of
     #   two projects that started their lives independently
     # @example pulls from origin/master
     #   @git.pull
@@ -553,17 +580,17 @@ module Git
     # @example pulls from upstream/develop
     #   @git.pull('upstream', 'develop')
     #
-    # @return [Void]
+    # @return [String] the stdout output from the pull command
     #
     # @raise [Git::FailedError] if the pull fails
     # @raise [ArgumentError] if a branch is given without a remote
     def pull(remote = nil, branch = nil, opts = {})
-      lib.pull(remote, branch, opts)
+      facade_repository.pull(remote, branch, opts)
     end
 
     # returns an array of Git:Remote objects
     def remotes
-      lib.remotes.map { |r| Git::Remote.new(self, r) }
+      facade_repository.remotes
     end
 
     # sets the url for a remote
@@ -572,9 +599,7 @@ module Git
     #  @git.set_remote_url('scotts_git', 'git://repo.or.cz/rubygit.git')
     #
     def set_remote_url(name, url)
-      url = url.repo.to_s if url.is_a?(Git::Base)
-      lib.remote_set_url(name, url)
-      Git::Remote.new(self, name)
+      facade_repository.set_remote_url(name, url)
     end
 
     # Configures which branches are fetched for a remote
@@ -606,24 +631,19 @@ module Git
     # the underlying git command fails
     #
     def remote_set_branches(name, *branches, add: false)
-      branch_list = branches.flatten
-      raise ArgumentError, 'branches are required' if branch_list.empty?
-
-      lib.remote_set_branches(name, branch_list, add: add)
-
-      nil
+      facade_repository.remote_set_branches(name, *branches, add: add)
     end
 
     # removes a remote from this repository
     #
     # @git.remove_remote('scott_git')
     def remove_remote(name)
-      lib.remote_remove(name)
+      facade_repository.remove_remote(name)
     end
 
-    # returns an array of all Git::Tag objects for this repository
+    # returns an array of all Git::Object::Tag objects for this repository
     def tags
-      lib.tags.map { |r| tag(r) }
+      facade_repository.tags
     end
 
     # Create a new git tag
@@ -634,29 +654,53 @@ module Git
     #   repo.add_tag('tag_name', {:options => 'here'})
     #
     # @param [String] name The name of the tag to add
-    # @param [Hash] options Opstions to pass to `git tag`.
+    # @param [Hash] options Options to pass to `git tag`.
     #   See [git-tag](https://git-scm.com/docs/git-tag) for more details.
-    # @option options [boolean] :annotate Make an unsigned, annotated tag object
-    # @option options [boolean] :a An alias for the `:annotate` option
-    # @option options [boolean] :d Delete existing tag with the given names.
-    # @option options [boolean] :f Replace an existing tag with the given name (instead of failing)
+    # @option options [Boolean, nil] :annotate (nil) make an unsigned, annotated tag object
+    # @option options [Boolean, nil] :a (nil) an alias for the `:annotate` option
+    # @option options [Boolean, nil] :d (nil) delete existing tag with the given name —
+    #   deprecated; use {#delete_tag} instead (alias: `:delete`)
+    # @option options [Boolean, nil] :delete (nil) delete existing tag with the given name —
+    #   deprecated; use {#delete_tag} instead (alias: `:d`)
+    # @option options [Boolean, nil] :f (nil) replace an existing tag with the given name (instead of failing)
     # @option options [String] :message Use the given tag message
     # @option options [String] :m An alias for the `:message` option
-    # @option options [boolean] :s Make a GPG-signed tag.
+    # @option options [Boolean, nil] :s (nil) make a GPG-signed tag
     #
     def add_tag(name, *options)
-      lib.tag(name, *options)
-      tag(name)
+      facade_repository.add_tag(name, *options)
     end
 
     # deletes a tag
     def delete_tag(name)
-      lib.tag(name, { d: true })
+      facade_repository.delete_tag(name)
     end
 
-    # creates an archive file of the given tree-ish
+    # Creates an archive of the given tree-ish and writes it to a file
+    #
+    # @api public
+    #
+    # @param treeish [String] the commit, tag, branch, or tree to archive
+    #
+    # @param file [String, nil] destination file path; a temp file is created
+    #   if `nil`
+    #
+    # @param opts [Hash] archive options (see {Git::Repository::ObjectOperations#archive})
+    #
+    # @return [String] the path to the written archive file
+    #
+    # @raise [ArgumentError] if unsupported options are provided
+    #
+    # @raise [ArgumentError] if `file` is an existing directory
+    #
+    # @raise [Git::FailedError] if git exits with a non-zero exit status
+    #
+    # @example Archive HEAD to a zip file
+    #   git.archive('HEAD', '/tmp/release.zip', format: 'zip')
+    #   #=> "/tmp/release.zip"
+    #
     def archive(treeish, file = nil, opts = {})
-      object(treeish).archive(file, opts)
+      facade_repository.archive(treeish, file, opts)
     end
 
     # repacks the repository
@@ -679,14 +723,14 @@ module Git
     #     references in the refs namespace, and all reflogs.
     #   @param [Hash] options options to pass to the underlying `git fsck` command
     #
-    #   @option options [Boolean] :unreachable print unreachable objects
-    #   @option options [Boolean] :strict enable strict checking
-    #   @option options [Boolean] :connectivity_only check only connectivity (faster)
-    #   @option options [Boolean] :root report root nodes
-    #   @option options [Boolean] :tags report tags
-    #   @option options [Boolean] :cache consider objects in the index
-    #   @option options [Boolean] :no_reflogs do not consider reflogs
-    #   @option options [Boolean] :lost_found write dangling objects to .git/lost-found
+    #   @option options [Boolean, nil] :unreachable (nil) print unreachable objects
+    #   @option options [Boolean, nil] :strict (nil) enable strict checking
+    #   @option options [Boolean, nil] :connectivity_only (nil) check only connectivity (faster)
+    #   @option options [Boolean, nil] :root (nil) report root nodes
+    #   @option options [Boolean, nil] :tags (nil) report tags
+    #   @option options [Boolean, nil] :cache (nil) consider objects in the index
+    #   @option options [Boolean, nil] :no_reflogs (nil) do not consider reflogs
+    #   @option options [Boolean, nil] :lost_found (nil) write dangling objects to .git/lost-found
     #     (note: this modifies the repository by creating files)
     #   @option options [Boolean, nil] :dangling print dangling objects (true/false/nil for default)
     #   @option options [Boolean, nil] :full check objects in alternate pools (true/false/nil for default)
@@ -697,10 +741,10 @@ module Git
     #
     #   @example Check repository integrity
     #     result = git.fsck
-    #     result.dangling.each { |obj| puts "#{obj.type}: #{obj.sha}" }
+    #     result.dangling.each { |obj| puts "#{obj.type}: #{obj.oid}" }
     #
     #   @example Check with strict mode and suppress dangling output
-    #     result = git.fsck(strict: true, dangling: false)
+    #     result = git.fsck(strict: true, no_dangling: true)
     #
     #   @example Check if repository has any issues
     #     result = git.fsck
@@ -708,14 +752,16 @@ module Git
     #
     #   @example List root commits
     #     result = git.fsck(root: true)
-    #     result.root.each { |obj| puts obj.sha }
+    #     result.root.each { |obj| puts obj.oid }
     #
     #   @example Check specific objects
     #     result = git.fsck('abc1234', 'def5678')
     #
-    def fsck(*objects, **opts) # rubocop:disable Style/ArgumentsForwarding
-      lib.fsck(*objects, **opts) # rubocop:disable Style/ArgumentsForwarding
+    # rubocop:disable Style/ArgumentsForwarding
+    def fsck(*objects, **opts)
+      facade_repository.fsck(*objects, **opts)
     end
+    # rubocop:enable Style/ArgumentsForwarding
 
     def apply(file)
       return unless File.exist?(file)
@@ -733,7 +779,7 @@ 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)
-      lib.show(objectish, path)
+      facade_repository.show(objectish, path)
     end
 
     ## LOWER LEVEL INDEX OPERATIONS ##
@@ -762,7 +808,7 @@ module Git
     end
 
     def checkout_index(opts = {})
-      lib.checkout_index(opts)
+      facade_repository.checkout_index(opts)
     end
 
     def read_tree(treeish, opts = {})
@@ -770,23 +816,22 @@ module Git
     end
 
     def write_tree
-      lib.write_tree
+      facade_repository.write_tree
     end
 
     def write_and_commit_tree(opts = {})
-      tree = write_tree
-      commit_tree(tree, opts)
+      Git::Object::Commit.new(self, facade_repository.write_and_commit_tree(**opts))
     end
 
     def update_ref(branch, commit)
-      branch(branch).update_ref(commit)
+      facade_repository.update_ref(branch, commit)
     end
 
     def ls_files(location = nil)
-      lib.ls_files(location)
+      facade_repository.ls_files(location)
     end
 
-    def with_working(work_dir) # :yields: the Git::WorkingDirectory
+    def with_working(work_dir) # :yields: the working directory Pathname
       return_value = false
       old_working = @working_directory
       set_working(work_dir)
@@ -814,29 +859,58 @@ module Git
     #   git.rev_parse('v2.4:/doc/index.html')
     #
     def rev_parse(objectish)
-      lib.rev_parse(objectish)
+      facade_repository.rev_parse(objectish)
     end
 
     # For backwards compatibility
     alias revparse rev_parse
 
-    def ls_tree(objectish, opts = {})
-      lib.ls_tree(objectish, opts)
+    # Returns the number of entries in a git tree object
+    #
+    # @example Count recursive entries in the HEAD tree
+    #   git.tree_depth('HEAD^{tree}') #=> 42
+    #
+    # @param objectish [String] the tree-ish object to recurse into
+    #
+    # @return [Integer] the number of entries in the recursive tree listing
+    #
+    # @raise [Git::FailedError] when git exits with a non-zero exit status
+    #
+    # @see Git::Repository::ObjectOperations#tree_depth
+    #
+    def tree_depth(objectish)
+      facade_repository.tree_depth(objectish)
     end
 
-    # Returns the contents of a git object
+    # Lists the objects in a git tree object
     #
-    # Uses `git cat-file -p` to pretty-print the contents of the given object.
+    # @example List all top-level objects
+    #   git.ls_tree('HEAD')
+    #   # => { 'blob' => { 'README.md' => { mode: '100644', sha: '...' } }, ... }
     #
-    # @param objectish [String] a SHA, branch name, tag, or other revision reference
-    #   to the git object
+    # @param objectish [String] the tree-ish object to list
     #
-    # @return [String] the contents of the object
+    # @param opts [Hash] additional options
     #
-    # @see https://git-scm.com/docs/git-cat-file git-cat-file
+    # @option opts [Boolean, nil] :recursive (nil) recurse into subtrees
     #
+    # @option opts [String, Array<String>] :path (nil) limit the listing to
+    #   the given path or array of paths
+    #
+    # @return [Hash<String, Hash<String, Hash>>] a three-level Hash keyed by
+    #   object type (`'blob'`, `'tree'`, `'commit'`), then by filename, then
+    #   holding `:mode` and `:sha` values
+    #
+    # @raise [ArgumentError] when unsupported options are provided
+    #
+    # @raise [Git::FailedError] when git exits with a non-zero exit status
+    #
+    def ls_tree(objectish, opts = {})
+      facade_repository.ls_tree(objectish, opts)
+    end
+
     def cat_file(objectish)
-      lib.cat_file_contents(objectish)
+      lib.cat_file(objectish)
     end
 
     # The name of the branch HEAD refers to or 'HEAD' if detached
@@ -848,59 +922,84 @@ module Git
     # @return [String] the name of the branch HEAD refers to or 'HEAD' if detached
     #
     def current_branch
-      lib.branch_current
+      facade_repository.current_branch
     end
 
     # @return [Git::Branch] an object for branch_name
     def branch(branch_name = current_branch)
-      Git::Branch.new(self, branch_name)
+      facade_repository.branch(branch_name)
     end
 
     # @return [Git::Branches] a collection of all the branches in the repository.
     #   Each branch is represented as a {Git::Branch}.
     def branches
-      Git::Branches.new(self)
+      facade_repository.branches
     end
 
-    # returns a Git::Worktree object for dir, commitish
+    # Returns a {Git::Worktree} object for the given path and optional commitish
+    #
+    # @example Create a worktree object for an existing path
+    #   worktree = repo.worktree('/path/to/worktree')
+    #
+    # @param dir [String] filesystem path of the worktree
+    #
+    # @param commitish [String, nil] branch, tag, or commit to check out
+    #
+    # @return [Git::Worktree] worktree object for the given path
+    #
     def worktree(dir, commitish = nil)
-      Git::Worktree.new(self, dir, commitish)
+      facade_repository.worktree(dir, commitish)
     end
 
-    # returns a Git::worktrees object of all the Git::Worktrees
-    # objects for this repo
+    # Returns a {Git::Worktrees} collection of all worktrees in the repository
+    #
+    # @example List paths for all worktrees
+    #   repo.worktrees.each { |wt| puts wt.dir }
+    #
+    # @return [Git::Worktrees] all linked and main worktrees
+    #
+    # @raise [Git::FailedError] if git exits with a non-zero exit status
+    #
     def worktrees
-      Git::Worktrees.new(self)
+      facade_repository.worktrees
     end
 
     # @return [Git::Object::Commit] a commit object
     def commit_tree(tree = nil, opts = {})
-      Git::Object::Commit.new(self, lib.commit_tree(tree, opts))
+      Git::Object::Commit.new(self, facade_repository.commit_tree(tree, **opts))
     end
 
     # @return [Git::Diff] a Git::Diff object
     def diff(objectish = 'HEAD', obj2 = nil)
-      Git::Diff.new(self, objectish, obj2)
+      facade_repository.diff(objectish, obj2)
     end
 
     # @return [Git::Object] a Git object
     def gblob(objectish)
-      Git::Object.new(self, objectish, 'blob')
+      facade_repository.gblob(objectish)
     end
 
     # @return [Git::Object] a Git object
     def gcommit(objectish)
-      Git::Object.new(self, objectish, 'commit')
+      facade_repository.gcommit(objectish)
     end
 
     # @return [Git::Object] a Git object
     def gtree(objectish)
-      Git::Object.new(self, objectish, 'tree')
+      facade_repository.gtree(objectish)
     end
 
     # @return [Git::Log] a log with the specified number of commits
     def log(count = 30)
-      Git::Log.new(self, count)
+      facade_repository.log(count)
+    end
+
+    # Return commits that are within the given revision range
+    #
+    # @param opts [Hash] options for the log query
+    # @return [Array<Hash>] the parsed raw log output for each commit
+    def full_log_commits(opts = {})
+      facade_repository.full_log_commits(opts)
     end
 
     # returns a Git::Object of the appropriate type
@@ -914,22 +1013,22 @@ module Git
     #
     # @return [Git::Object] an instance of the appropriate type of Git::Object
     def object(objectish)
-      Git::Object.new(self, objectish)
+      facade_repository.object(objectish)
     end
 
     # @return [Git::Remote] a remote of the specified name
     def remote(remote_name = 'origin')
-      Git::Remote.new(self, remote_name)
+      facade_repository.remote(remote_name)
     end
 
     # @return [Git::Status] a status object
     def status
-      Git::Status.new(self)
+      facade_repository.status
     end
 
     # @return [Git::Object::Tag] a tag object
     def tag(tag_name)
-      Git::Object::Tag.new(self, tag_name)
+      facade_repository.tag(tag_name)
     end
 
     # Find as good common ancestors as possible for a merge
@@ -937,204 +1036,169 @@ module Git
     #
     # @return [Array<Git::Object::Commit>] a collection of common ancestors
     def merge_base(*)
-      shas = lib.merge_base(*)
-      shas.map { |sha| gcommit(sha) }
+      facade_repository.merge_base(*).map { |sha| gcommit(sha) }
     end
 
-    # Returns a Git::Diff::Stats object for accessing diff statistics.
+    # Returns the full unified diff patch text between two commits
     #
-    # @param objectish [String] The first commit or object to compare. Defaults to 'HEAD'.
-    # @param obj2 [String, nil] The second commit or object to compare.
-    # @param opts [Hash] Options to filter the diff.
-    # @option opts [String, Pathname, Array<String, Pathname>] :path_limiter Limit stats to specified path(s).
-    # @return [Git::DiffStats]
-    def diff_stats(objectish = 'HEAD', obj2 = nil, opts = {})
-      Git::DiffStats.new(self, objectish, obj2, opts[:path_limiter])
-    end
-
-    # Returns a Git::Diff::PathStatus object for accessing the name-status report.
+    # @example Get the patch for the most recent commit
+    #   repo.diff_full #=> "diff --git a/lib/foo.rb b/lib/foo.rb\n..."
     #
-    # @param objectish [String] The first commit or object to compare. Defaults to 'HEAD'.
-    # @param obj2 [String, nil] The second commit or object to compare.
-    # @param opts [Hash] Options to filter the diff.
-    # @option opts [String, Pathname, Array<String, Pathname>] :path_limiter Limit status to specified path(s).
-    # @option opts [String, Pathname, Array<String, Pathname>] :path (deprecated) Legacy alias for :path_limiter.
-    # @return [Git::DiffPathStatus]
-    def diff_path_status(objectish = 'HEAD', obj2 = nil, opts = {})
-      path_limiter = if opts.key?(:path_limiter)
-                       opts[:path_limiter]
-                     elsif opts.key?(:path)
-                       Git::Deprecation.warn(
-                         'Git::Base#diff_path_status :path option is deprecated. Use :path_limiter instead.'
-                       )
-                       opts[:path]
-                     end
-
-      Git::DiffPathStatus.new(self, objectish, obj2, path_limiter)
-    end
-
-    # Provided for backwards compatibility
-    alias diff_name_status diff_path_status
-
-    private
-
-    # Sets default paths in the options hash for direct `Git::Base.new` calls
+    # @param obj1 [String] the first commit or object to compare; defaults to
+    #   `'HEAD'`
     #
-    # Factory methods like `Git.open` pre-populate these options by calling
-    # `normalize_paths`, making this a fallback. It avoids mutating the
-    # original options hash by returning a new one.
+    # @param obj2 [String, nil] the second commit or object to compare
     #
-    # @param options [Hash] the original options hash
-    # @return [Hash] a new options hash with defaults applied
-    def default_paths(options)
-      return options unless (working_dir = options[:working_directory])
-
-      options.dup.tap do |opts|
-        opts[:repository] ||= File.join(working_dir, '.git')
-        opts[:index] ||= File.join(opts[:repository], 'index')
-      end
-    end
-
-    # Initializes the logger from the provided options
-    # @param log_option [Logger, nil] The logger instance from options.
-    def setup_logger(log_option)
-      @logger = log_option || Logger.new(nil)
-      @logger.info('Starting Git')
-    end
-
-    # Initializes the core git objects based on the provided options
-    # @param options [Hash] The processed options hash.
-    def initialize_components(options)
-      @working_directory = Git::WorkingDirectory.new(options[:working_directory]) if options[:working_directory]
-      @repository = Git::Repository.new(options[:repository]) if options[:repository]
-      @index = Git::Index.new(options[:index], must_exist: false) if options[:index]
-    end
-
-    # Normalize options before they are sent to Git::Base.new
+    #   When `nil`, the comparison is against the index or working tree.
     #
-    # Updates the options parameter by setting appropriate values for the following keys:
-    #   * options[:working_directory]
-    #   * options[:repository]
-    #   * options[:index]
+    # @param opts [Hash] options to filter the diff
     #
-    # All three values will be set to absolute paths. An exception is that
-    # :working_directory will be set to nil if bare is true.
+    # @option opts [String, Pathname, Array<String, Pathname>, nil] :path_limiter (nil)
+    #   limit the diff to the given path(s)
     #
-    private_class_method def self.normalize_paths(
-      options, default_working_directory: nil, default_repository: nil, bare: false
-    )
-      normalize_working_directory(options, default: default_working_directory, bare: bare)
-      normalize_repository(options, default: default_repository, bare: bare)
-      normalize_index(options)
-    end
-
-    # Normalize options[:working_directory]
+    # @return [String] the unified diff patch output
     #
-    # If working with a bare repository, set to `nil`.
-    # Otherwise, set to the first non-nil value of:
-    #   1. `options[:working_directory]`,
-    #   2. the `default` parameter, or
-    #   3. the current working directory
+    # @note Unknown option keys are silently ignored for backward compatibility;
+    #   only `:path_limiter` is forwarded to the underlying command.
     #
-    # Finally, if options[:working_directory] is a relative path, convert it to an absoluite
-    # path relative to the current directory.
+    # @raise [Git::FailedError] if git exits outside the allowed range (exit code > 1)
     #
-    private_class_method def self.normalize_working_directory(options, default:, bare: false)
-      working_directory =
-        if bare
-          nil
-        else
-          File.expand_path(options[:working_directory] || default || Dir.pwd)
-        end
-
-      options[:working_directory] = working_directory
+    # @see Git::Repository::Diffing#diff_full
+    #
+    def diff_full(obj1 = 'HEAD', obj2 = nil, opts = {})
+      facade_repository.diff_full(obj1, obj2, opts.slice(:path_limiter))
     end
 
-    # Normalize options[:repository]
+    # Returns a lazy {Git::DiffStats} object for accessing diff statistics
     #
-    # If working with a bare repository, set to the first non-nil value out of:
-    #   1. `options[:repository]`
-    #   2. the `default` parameter
-    #   3. the current working directory
+    # Compares (1) two commits, (2) a commit against the working tree, or (3) the
+    # index against the working tree and constructs a lazy {Git::DiffStats} that
+    # computes per-file insertion and deletion counts on demand when its accessor
+    # methods are called.
     #
-    # Otherwise, set to the first non-nil value of:
-    #   1. `options[:repository]`
-    #   2. `.git`
+    # **Comparing two commits**
     #
-    # Next, if options[:repository] refers to a *file* and not a *directory*, set
-    # options[:repository] to the contents of that file.  This is the case when
-    # working with a submodule or a secondary working tree (created with git worktree
-    # add). In these cases the repository is actually contained/nested within the
-    # parent's repository directory.
+    # When both objectish and obj2 are provided, the comparison is between those two
+    # refs (commits, tags, branches, etc.).
     #
-    # Finally, if options[:repository] is a relative path, convert it to an absolute
-    # path relative to:
-    #   1. the current directory if working with a bare repository or
-    #   2. the working directory if NOT working with a bare repository
+    # **Comparing a commit against the working tree**
     #
-    private_class_method def self.normalize_repository(options, default:, bare: false)
-      initial_path = initial_repository_path(options, default: default, bare: bare)
-      final_path = resolve_gitdir_if_present(initial_path, options[:working_directory])
-      options[:repository] = final_path
-    end
-
-    # Determines the initial, potential path to the repository directory
+    # When only objectish is provided (and isn't nil), the comparison is between
+    # objectish and the working tree; the stats reflect all changes since objectish.
     #
-    # This path is considered 'initial' because it is not guaranteed to be the
-    # final repository location. For features like submodules or worktrees,
-    # this path may point to a text file containing a `gitdir:` pointer to the
-    # actual repository directory elsewhere. This initial path must be
-    # subsequently resolved.
+    # **Comparing the index against the working tree**
     #
-    # @api private
+    # When objectish is explicitly `nil` then obj2 must be omitted or `nil`. In this
+    # case, the comparison is between the index and the working tree; the stats reflect
+    # unstaged changes.
     #
-    # @param options [Hash] The options hash, checked for `[:repository]`.
+    # @example Get working tree stats since HEAD
+    #   repo.diff_stats.insertions #=> 3
     #
-    # @param default [String] A fallback path if `options[:repository]` is not set.
+    # @example Compare two specific commits
+    #   repo.diff_stats('abc1234', 'def5678')
     #
-    # @param bare [Boolean] Whether the repository is bare, which changes path resolution.
+    # @example Get unstaged stats (index vs. working tree)
+    #   repo.diff_stats(nil).insertions
     #
-    # @return [String] The initial, absolute path to the `.git` directory or file.
+    # @example Limit stats to a sub-path
+    #   repo.diff_stats('HEAD~1', 'HEAD', path_limiter: 'lib/')
     #
-    private_class_method def self.initial_repository_path(options, default:, bare:)
-      if bare
-        File.expand_path(options[:repository] || default || Dir.pwd)
-      else
-        File.expand_path(options[:repository] || '.git', options[:working_directory])
-      end
+    # @param objectish [String, nil] the first commit or object to compare; defaults to
+    #   `'HEAD'`; pass `nil` to compare the index against the working tree
+    #
+    # @param obj2 [String, nil] the second commit or object to compare
+    #
+    # @param opts [Hash] options to filter the diff
+    #
+    # @option opts [String, Pathname, Array<String, Pathname>, nil] :path_limiter (nil)
+    #   limit the stats to the given path(s)
+    #
+    # @return [Git::DiffStats] a lazy stats object for the comparison
+    #
+    # @note Unknown option keys are silently ignored for backward compatibility;
+    #   only `:path_limiter` is forwarded to the underlying command.
+    #
+    # @raise [ArgumentError] if `objectish` or `obj2` starts with `"-"`
+    #
+    # @raise [ArgumentError] if `objectish` is `nil` but `obj2` is not
+    #
+    # @see Git::Repository::Diffing#diff_stats
+    #
+    def diff_stats(objectish = 'HEAD', obj2 = nil, opts = {})
+      facade_repository.diff_stats(objectish, obj2, opts.slice(:path_limiter))
     end
 
-    # Resolves the path to the actual repository if it's a `gitdir:` pointer file.
+    # Returns the file path status between two commits
     #
-    # If `path` points to a file (common in submodules and worktrees), this
-    # method reads the `gitdir:` path from it and returns the real repository
-    # path. Otherwise, it returns the original path.
+    # @example Get all changed files between HEAD and the previous commit
+    #   repo.diff_path_status.to_h #=> { "README.md" => "M", "lib/foo.rb" => "A" }
     #
-    # @api private
+    # @param objectish [String] the first commit or object to compare; defaults to
+    #   `'HEAD'`
+    #
+    # @param obj2 [String, nil] the second commit or object to compare
     #
-    # @param path [String] The initial path to the repository, which may be a pointer file.
+    # @param opts [Hash] options to filter the diff
     #
-    # @param working_dir [String] The working directory, used as a base to resolve the path.
+    # @option opts [String, Pathname, Array<String, Pathname>, nil] :path_limiter (nil)
+    #   limit the status report to specified path(s)
     #
-    # @return [String] The final, resolved absolute path to the repository directory.
+    # @option opts [String, Pathname, Array<String, Pathname>, nil] :path (nil)
+    #   deprecated; use `:path_limiter` instead
     #
-    private_class_method def self.resolve_gitdir_if_present(path, working_dir)
-      return path unless File.file?(path)
+    # @return [Git::DiffPathStatus] the name-status report for the comparison
+    #
+    # @raise [ArgumentError] if `objectish` or `obj2` starts with `"-"`
+    #
+    # @raise [Git::FailedError] if git exits outside the allowed range (exit code > 1)
+    #
+    # @see Git::Repository::Diffing#diff_path_status
+    #
+    def diff_path_status(objectish = 'HEAD', obj2 = nil, opts = {})
+      facade_repository.diff_path_status(objectish, obj2, opts.slice(:path_limiter, :path))
+    end
 
-      # The file contains `gitdir: <path>`, so we read the file,
-      # extract the path part, and expand it.
-      gitdir_pointer = File.read(path).sub(/\Agitdir: /, '').strip
-      File.expand_path(gitdir_pointer, working_dir)
+    # Compares the index and the working directory
+    #
+    # @example List all files with unstaged changes
+    #   repo.diff_files #=> { "lib/foo.rb" => { mode_index: "100644", ... } }
+    #
+    # @return [Hash{String => Hash}] a hash keyed by file path; see
+    #   {Git::Repository::Diffing#diff_files} for the full key list
+    #
+    # @raise [Git::FailedError] if git exits outside the allowed range (exit code > 1)
+    #
+    # @see Git::Repository::Diffing#diff_files
+    #
+    def diff_files
+      facade_repository.diff_files
     end
 
-    # Normalize options[:index]
+    # Alias for {#diff_path_status}; provided for backward compatibility
+    #
+    # @return [Git::DiffPathStatus] the name-status report for the comparison
     #
-    # If options[:index] is a relative directory, convert it to an absolute
-    # directory relative to the repository directory
+    # @deprecated Use {#diff_path_status} instead
     #
-    private_class_method def self.normalize_index(options)
-      index = File.expand_path(options[:index] || 'index', options[:repository])
-      options[:index] = index
+    # @see #diff_path_status
+    alias diff_name_status diff_path_status
+
+    private
+
+    # Initializes the logger from the provided options
+    # @param log_option [Logger, nil] The logger instance from options.
+    def setup_logger(log_option)
+      @logger = log_option || Logger.new(nil)
+      @logger.info('Starting Git')
+    end
+
+    # Initializes the core git objects based on the provided options
+    # @param options [Hash] The processed options hash.
+    def initialize_components(options)
+      @working_directory = Pathname.new(options[:working_directory]) if options[:working_directory]
+      @repository = Pathname.new(options[:repository]) if options[:repository]
+      @index = Pathname.new(options[:index]) if options[:index]
     end
   end
 end