git 1.19.1 → 4.4.5

data/lib/git/base.rb

@@ -1,53 +1,76 @@
-require 'git/base/factory'
+# frozen_string_literal: true
+
 require 'logger'
-require 'open3'
 
 module Git
-  # Git::Base is the main public interface for interacting with Git commands.
+  # The main public interface for interacting with Git commands
   #
   # Instead of creating a Git::Base directly, obtain a Git::Base instance by
   # calling one of the follow {Git} class methods: {Git.open}, {Git.init},
   # {Git.clone}, or {Git.bare}.
   #
+  # @api public
+  #
   class Base
-    include Git::Base::Factory
-
     # (see Git.bare)
     def self.bare(git_dir, options = {})
       normalize_paths(options, default_repository: git_dir, bare: true)
-      self.new(options)
+      new(options)
     end
 
     # (see Git.clone)
     def self.clone(repository_url, directory, options = {})
-      new_options = Git::Lib.new(nil, options[:log]).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)
     end
 
     # (see Git.default_branch)
     def self.repository_default_branch(repository, options = {})
-      Git::Lib.new(nil, options[:log]).repository_default_branch(repository)
+      LibImpl.new(nil, options[:log]).repository_default_branch(repository)
     end
 
     # Returns (and initialize if needed) a Git::Config instance
     #
     # @return [Git::Config] the current config instance.
     def self.config
-      @@config ||= Config.new
+      @config ||= Config.new
+    end
+
+    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])
+      normalize_paths(options, default_working_directory: directory, default_repository: directory,
+                               bare: options[:bare])
 
       init_options = {
-        :bare => options[:bare],
-        :initial_branch => options[:initial_branch]
+        bare: options[:bare],
+        initial_branch: options[:initial_branch]
       }
 
       directory = options[:bare] ? options[:repository] : options[:working_directory]
-      FileUtils.mkdir_p(directory) unless File.exist?(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)
@@ -59,21 +82,53 @@ module Git
       #   repository you have a Git::Base instance for.  This would not
       #   change the existing interface (other than adding to it).
       #
-      Git::Lib.new(options).init(init_options)
+      LibImpl.new(options).init(init_options)
 
-      self.new(options)
+      new(options)
     end
 
     def self.root_of_worktree(working_dir)
-      result = working_dir
-      status = nil
+      raise ArgumentError, "'#{working_dir}' does not exist" unless Dir.exist?(working_dir)
+
+      execute_rev_parse_toplevel(working_dir)
+    end
 
-      git_cmd = "#{Git::Base.config.binary_path} -c core.quotePath=true -c color.ui=false rev-parse --show-toplevel 2>&1"
-      result, status = Open3.capture2(git_cmd, chdir: File.expand_path(working_dir))
-      result = result.chomp
+    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'
+    end
 
-      raise ArgumentError, "'#{working_dir}' is not in a git working tree" unless status.success?
-      result
+    # A command line for the git commands that run before a repository is known
+    #
+    # `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.
+    #
+    # @see https://github.com/ruby-git/ruby-git/issues/840 issue 840
+    #
+    # @param binary_path [String] the path to the git binary to run
+    #
+    # @return [Git::CommandLine] a command line that runs `binary_path` with
+    #   `-c core.quotePath=true -c color.ui=false`
+    #
+    #   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))
     end
 
     # (see Git.open)
@@ -84,7 +139,7 @@ module Git
 
       normalize_paths(options, default_working_directory: working_dir)
 
-      self.new(options)
+      new(options)
     end
 
     # Create an object that executes Git commands in the context of a working
@@ -106,20 +161,54 @@ module 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.
+    #   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
     #
     def initialize(options = {})
-      if working_dir = options[:working_directory]
-        options[:repository] ||= File.join(working_dir, '.git')
-        options[:index] ||= File.join(options[:repository], 'index')
-      end
-      @logger = (options[:log] || Logger.new(nil))
-      @logger.info("Starting Git")
+      options = default_paths(options)
+      setup_logger(options[:log])
+      @git_ssh = options.key?(:git_ssh) ? options[:git_ssh] : :use_global_config
+      initialize_components(options)
+    end
 
-      @working_directory = options[:working_directory] ? Git::WorkingDirectory.new(options[:working_directory]) : nil
-      @repository = options[:repository] ? Git::Repository.new(options[:repository]) : nil
-      @index = options[:index] ? Git::Index.new(options[:index], false) : nil
+    # Update the index from the current worktree to prepare the for the next commit
+    #
+    # @example
+    #   lib.add('path/to/file')
+    #   lib.add(['path/to/file1','path/to/file2'])
+    #   lib.add(all: true)
+    #
+    # @param [String, Array<String>] paths a file or 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
+    #
+    def add(paths = '.', **options)
+      lib.add(paths, options)
+    end
+
+    # adds a new remote to this repository
+    # url can be a git url or a Git::Base object if it's a local reference
+    #
+    #  @git.add_remote('scotts_git', 'git://repo.or.cz/rubygit.git')
+    #  @git.fetch('scotts_git')
+    #  @git.merge('scotts_git/master')
+    #
+    # Options:
+    #   :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)
     end
 
     # changes current working directory for a block
@@ -132,16 +221,16 @@ module Git
     #    @git.commit('message')
     #  end
     def chdir # :yields: the Git::Path
-      Dir.chdir(dir.path) do
-        yield dir.path
+      Dir.chdir(dir.to_s) do
+        yield dir.to_s
       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.name')  # returns 'Scott Chacon'
-    #g.config # returns whole config hash
+    # 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.name')  # returns 'Scott Chacon'
+    # g.config # returns whole config hash
     def config(name = nil, value = nil, options = {})
       if name && value
         # set value
@@ -163,9 +252,7 @@ module Git
     end
 
     # returns reference to the git index file
-    def index
-      @index
-    end
+    attr_reader :index
 
     # returns reference to the git repository directory
     #  @git.dir.path
@@ -175,50 +262,107 @@ module Git
 
     # returns the repository size in bytes
     def repo_size
-      Dir.glob(File.join(repo.path, '**', '*'), File::FNM_DOTMATCH).reject do |f|
-        f.include?('..')
-      end.map do |f|
-        File.expand_path(f)
-      end.uniq.map do |f|
-        File.stat(f).size.to_i
-      end.reduce(:+)
+      all_files = Dir.glob(File.join(repo.path, '**', '*'), File::FNM_DOTMATCH)
+
+      all_files.reject { |file| file.include?('..') }
+               .map { |file| File.expand_path(file) }
+               .uniq
+               .sum { |file| File.stat(file).size.to_i }
     end
 
-    def set_index(index_file, check = true)
+    def set_index(index_file, 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.'
+        )
+      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, check)
+      @index = Git::Index.new(index_file.to_s, must_exist:)
     end
 
-    def set_working(work_dir, check = true)
+    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.'
+        )
+      end
+
+      # default is true
+      must_exist = must_exist.nil? && check.nil? ? true : must_exist | check
+
       @lib = nil
-      @working_directory = Git::WorkingDirectory.new(work_dir.to_s, check)
+      @working_directory = Git::WorkingDirectory.new(work_dir.to_s, must_exist:)
     end
 
     # returns +true+ if the branch exists locally
-    def is_local_branch?(branch)
-      branch_names = self.branches.local.map {|b| b.name}
+    def local_branch?(branch)
+      branch_names = branches.local.map(&:name)
       branch_names.include?(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. ' \
+        'Use Git::Base#local_branch? instead.'
+      )
+      local_branch?(branch)
+    end
+
     # returns +true+ if the branch exists remotely
-    def is_remote_branch?(branch)
-      branch_names = self.branches.remote.map {|b| b.name}
+    def remote_branch?(branch)
+      branch_names = branches.remote.map(&:name)
       branch_names.include?(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. ' \
+        'Use Git::Base#remote_branch? instead.'
+      )
+      remote_branch?(branch)
+    end
+
     # returns +true+ if the branch exists
-    def is_branch?(branch)
-      branch_names = self.branches.map {|b| b.name}
+    def branch?(branch)
+      branch_names = branches.map(&:name)
       branch_names.include?(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. ' \
+        'Use Git::Base#branch? instead.'
+      )
+      branch?(branch)
+    end
+
     # this is a convenience method for accessing the class that wraps all the
     # 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 ||= Git::Lib.new(self, @logger)
+      @lib ||= LibImpl.new(self, @logger)
     end
 
+    # Returns the per-instance git_ssh configuration value.
+    #
+    # This may be:
+    # * a [String] path when an explicit git_ssh command has been configured
+    # * the Symbol `:use_global_config` when this instance is using the global config
+    # * `nil` when SSH has been explicitly disabled for this instance
+    #
+    # @return [String, Symbol, nil] the git_ssh configuration value for this instance
+    # @api private
+    attr_reader :git_ssh
+
     # Run a grep for 'string' on the HEAD of the git repository
     #
     # @example Limit grep's scope by calling grep() from a specific object:
@@ -233,7 +377,8 @@ module Git
     #   end
     #
     # @param string [String] the string to search for
-    # @param path_limiter [String, Array] a path or array of paths to limit the search to or nil for no limit
+    # @param path_limiter [String, Pathname, Array<String, Pathname>] a path or array
+    #   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
@@ -251,48 +396,32 @@ module Git
     #   ```
     #
     def grep(string, path_limiter = nil, opts = {})
-      self.object('HEAD').grep(string, path_limiter, opts)
+      object('HEAD').grep(string, path_limiter, opts)
     end
 
-    # updates the repository index using the working directory content
-    #
-    # @example
-    #   git.add
-    #   git.add('path/to/file')
-    #   git.add(['path/to/file1','path/to/file2'])
-    #   git.add(:all => true)
-    #
-    # options:
-    #   :all => true
+    # 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
     #
-    # @param [String,Array] paths files paths to be added (optional, default='.')
-    # @param [Hash] options
-    # @option options [boolean] :all
-    #   Update the index not only where the working tree has a file matching
-    #   <pathspec> but also where the index already has an entry.
-    #   See [the --all option to git-add](https://git-scm.com/docs/git-add#Documentation/git-add.txt--A)
-    #   for more details.
-    #
-    def add(paths = '.', **options)
-      self.lib.add(paths, options)
+    def ignored_files
+      lib.ignored_files
     end
 
     # removes file(s) from the git repository
     def rm(path = '.', opts = {})
-      self.lib.rm(path, opts)
+      lib.rm(path, opts)
     end
 
     alias remove rm
 
     # resets the working directory to the provided commitish
     def reset(commitish = nil, opts = {})
-      self.lib.reset(commitish, opts)
+      lib.reset(commitish, opts)
     end
 
     # resets the working directory to the commitish with '--hard'
     def reset_hard(commitish = nil, opts = {})
-      opts = {:hard => true}.merge(opts)
-      self.lib.reset(commitish, opts)
+      opts = { hard: true }.merge(opts)
+      lib.reset(commitish, opts)
     end
 
     # cleans the working directory
@@ -303,7 +432,7 @@ module Git
     #  :ff
     #
     def clean(opts = {})
-      self.lib.clean(opts)
+      lib.clean(opts)
     end
 
     #  returns the most recent tag that is reachable from a commit
@@ -321,8 +450,8 @@ module Git
     #  :always
     #  :match
     #
-    def describe(committish=nil, opts={})
-      self.lib.describe(committish, opts)
+    def describe(committish = nil, opts = {})
+      lib.describe(committish, opts)
     end
 
     # reverts the working directory to the provided commitish.
@@ -332,7 +461,7 @@ module Git
     #   :no_edit
     #
     def revert(commitish = nil, opts = {})
-      self.lib.revert(commitish, opts)
+      lib.revert(commitish, opts)
     end
 
     # commits all pending changes in the index file to the git repository
@@ -344,25 +473,25 @@ module Git
     #   :author
     #
     def commit(message, opts = {})
-      self.lib.commit(message, opts)
+      lib.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)
-      self.lib.commit(message, opts)
+      opts = { add_all: true }.merge(opts)
+      lib.commit(message, opts)
     end
 
     # checks out a branch as the new git working directory
-    def checkout(*args, **options)
-      self.lib.checkout(*args, **options)
+    def checkout(*, **)
+      lib.checkout(*, **)
     end
 
     # checks out an old version of a file
     def checkout_file(version, file)
-      self.lib.checkout_file(version,file)
+      lib.checkout_file(version, file)
     end
 
     # fetches changes from a remote branch - this does not modify the working directory,
@@ -372,7 +501,7 @@ module Git
         opts = remote
         remote = nil
       end
-      self.lib.fetch(remote, opts)
+      lib.fetch(remote, opts)
     end
 
     # Push changes to a remote repository
@@ -393,77 +522,111 @@ module Git
     #   @raise [Git::FailedError] if the push fails
     #   @raise [ArgumentError] if a branch is given without a remote
     #
-    def push(*args, **options)
-      self.lib.push(*args, **options)
+    def push(*, **)
+      lib.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 = {})
-      self.lib.merge(branch, message, opts)
+      lib.merge(branch, message, opts)
     end
 
     # iterates over the files which are unmerged
-    def each_conflict(&block) # :yields: file, your_version, their_version
-      self.lib.conflicts(&block)
+    def each_conflict(&) # :yields: file, your_version, their_version
+      lib.conflicts(&)
     end
 
-    # pulls the given branch from the given remote into the current branch
+    # Pulls the given branch from the given remote into the current branch
+    #
+    # @param remote [String] the remote repository to pull from
+    # @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
+    #   two projects that started their lives independently
+    # @example pulls from origin/master
+    #   @git.pull
+    # @example pulls from upstream/master
+    #   @git.pull('upstream')
+    # @example pulls from upstream/develop
+    #   @git.pull('upstream', 'develop')
     #
-    #  @git.pull                          # pulls from origin/master
-    #  @git.pull('upstream')              # pulls from upstream/master
-    #  @git.pull('upstream', 'develope')  # pulls from upstream/develop
+    # @return [Void]
     #
-    def pull(remote = nil, branch = nil)
-      self.lib.pull(remote, branch)
+    # @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)
     end
 
     # returns an array of Git:Remote objects
     def remotes
-      self.lib.remotes.map { |r| Git::Remote.new(self, r) }
+      lib.remotes.map { |r| Git::Remote.new(self, r) }
     end
 
-    # adds a new remote to this repository
+    # sets the url for a remote
     # url can be a git url or a Git::Base object if it's a local reference
     #
-    #  @git.add_remote('scotts_git', 'git://repo.or.cz/rubygit.git')
-    #  @git.fetch('scotts_git')
-    #  @git.merge('scotts_git/master')
+    #  @git.set_remote_url('scotts_git', 'git://repo.or.cz/rubygit.git')
     #
-    # Options:
-    #   :fetch => true
-    #   :track => <branch_name>
-    def add_remote(name, url, opts = {})
-      url = url.repo.path if url.is_a?(Git::Base)
-      self.lib.remote_add(name, url, opts)
+    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)
     end
 
-    # sets the url for a remote
-    # url can be a git url or a Git::Base object if it's a local reference
+    # Configures which branches are fetched for a remote
     #
-    #  @git.set_remote_url('scotts_git', 'git://repo.or.cz/rubygit.git')
+    # Uses `git remote set-branches` to set or append fetch refspecs. When the `add:`
+    # option is not given, the `--add` option is not passed to the git command
     #
-    def set_remote_url(name, url)
-      url = url.repo.path if url.is_a?(Git::Base)
-      self.lib.remote_set_url(name, url)
-      Git::Remote.new(self, name)
+    # @example Replace fetched branches with a single glob pattern
+    #   git = Git.open('/path/to/repo')
+    #   # Only fetch branches matching "feature/*" from origin
+    #   git.remote_set_branches('origin', 'feature/*')
+    #
+    # @example Append a glob pattern to existing fetched branches
+    #   git = Git.open('/path/to/repo')
+    #   # Keep existing fetch refspecs and add all release branches
+    #   git.remote_set_branches('origin', 'release/*', add: true)
+    #
+    # @example Configure multiple explicit branches
+    #   git = Git.open('/path/to/repo')
+    #   git.remote_set_branches('origin', 'main', 'development', 'hotfix')
+    #
+    # @param name [String] the remote name (for example, "origin")
+    # @param branches [Array<String>] branch names or globs (for example, '*')
+    # @param add [Boolean] when true, append to existing refspecs instead of replacing them
+    #
+    # @return [nil]
+    #
+    # @raise [ArgumentError] if no branches are provided @raise [Git::FailedError] if
+    # 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
     end
 
     # removes a remote from this repository
     #
     # @git.remove_remote('scott_git')
     def remove_remote(name)
-      self.lib.remote_remove(name)
+      lib.remote_remove(name)
     end
 
     # returns an array of all Git::Tag objects for this repository
     def tags
-      self.lib.tags.map { |r| tag(r) }
+      lib.tags.map { |r| tag(r) }
     end
 
-    # Creates a new git tag (Git::Tag)
+    # Create a new git tag
     #
     # @example
     #   repo.add_tag('tag_name', object_reference)
@@ -482,37 +645,86 @@ module Git
     # @option options [boolean] :s Make a GPG-signed tag.
     #
     def add_tag(name, *options)
-      self.lib.tag(name, *options)
-      self.tag(name)
+      lib.tag(name, *options)
+      tag(name)
     end
 
     # deletes a tag
     def delete_tag(name)
-      self.lib.tag(name, {:d => true})
+      lib.tag(name, { d: true })
     end
 
     # creates an archive file of the given tree-ish
     def archive(treeish, file = nil, opts = {})
-      self.object(treeish).archive(file, opts)
+      object(treeish).archive(file, opts)
     end
 
     # repacks the repository
     def repack
-      self.lib.repack
+      lib.repack
     end
 
     def gc
-      self.lib.gc
+      lib.gc
+    end
+
+    # Verifies the connectivity and validity of objects in the database
+    #
+    # Runs `git fsck` to check repository integrity and identify dangling,
+    # missing, or unreachable objects.
+    #
+    # @overload fsck(objects = [], options = {})
+    #   @param objects [Array<String>] specific objects to treat as heads for unreachability trace.
+    #     If no objects are given, git fsck defaults to using the index file, all SHA-1
+    #     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
+    #     (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)
+    #   @option options [Boolean, nil] :name_objects name objects by refs (true/false/nil for default)
+    #   @option options [Boolean, nil] :references check refs database consistency (true/false/nil for default)
+    #
+    #   @return [Git::FsckResult] categorized objects flagged by fsck
+    #
+    #   @example Check repository integrity
+    #     result = git.fsck
+    #     result.dangling.each { |obj| puts "#{obj.type}: #{obj.sha}" }
+    #
+    #   @example Check with strict mode and suppress dangling output
+    #     result = git.fsck(strict: true, dangling: false)
+    #
+    #   @example Check if repository has any issues
+    #     result = git.fsck
+    #     puts "Repository is clean" if result.empty?
+    #
+    #   @example List root commits
+    #     result = git.fsck(root: true)
+    #     result.root.each { |obj| puts obj.sha }
+    #
+    #   @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
     end
 
     def apply(file)
-      if File.exist?(file)
-        self.lib.apply(file)
-      end
+      return unless File.exist?(file)
+
+      lib.apply(file)
     end
 
     def apply_mail(file)
-      self.lib.apply_mail(file) if File.exist?(file)
+      lib.apply_mail(file) if File.exist?(file)
     end
 
     # Shows objects
@@ -520,8 +732,8 @@ module Git
     # @param [String|NilClass] objectish the target object reference (nil == HEAD)
     # @param [String|NilClass] path the path of the file to be shown
     # @return [String] the object information
-    def show(objectish=nil, path=nil)
-      self.lib.show(objectish, path)
+    def show(objectish = nil, path = nil)
+      lib.show(objectish, path)
     end
 
     ## LOWER LEVEL INDEX OPERATIONS ##
@@ -534,11 +746,11 @@ module Git
       return_value
     end
 
-    def with_temp_index &blk
+    def with_temp_index(&)
       # Workaround for JRUBY, since they handle the TempFile path different.
       # MUST be improved to be safer and OS independent.
       if RUBY_PLATFORM == 'java'
-        temp_path = "/tmp/temp-index-#{(0...15).map{ ('a'..'z').to_a[rand(26)] }.join}"
+        temp_path = "/tmp/temp-index-#{(0...15).map { ('a'..'z').to_a[rand(26)] }.join}"
       else
         tempfile = Tempfile.new('temp-index')
         temp_path = tempfile.path
@@ -546,19 +758,19 @@ module Git
         tempfile.unlink
       end
 
-      with_index(temp_path, &blk)
+      with_index(temp_path, &)
     end
 
     def checkout_index(opts = {})
-      self.lib.checkout_index(opts)
+      lib.checkout_index(opts)
     end
 
     def read_tree(treeish, opts = {})
-      self.lib.read_tree(treeish, opts)
+      lib.read_tree(treeish, opts)
     end
 
     def write_tree
-      self.lib.write_tree
+      lib.write_tree
     end
 
     def write_and_commit_tree(opts = {})
@@ -570,9 +782,8 @@ module Git
       branch(branch).update_ref(commit)
     end
 
-
-    def ls_files(location=nil)
-      self.lib.ls_files(location)
+    def ls_files(location = nil)
+      lib.ls_files(location)
     end
 
     def with_working(work_dir) # :yields: the Git::WorkingDirectory
@@ -586,41 +797,219 @@ module Git
       return_value
     end
 
-    def with_temp_working &blk
-      tempfile = Tempfile.new("temp-workdir")
+    def with_temp_working(&)
+      tempfile = Tempfile.new('temp-workdir')
       temp_dir = tempfile.path
       tempfile.close
       tempfile.unlink
-      Dir.mkdir(temp_dir, 0700)
-      with_working(temp_dir, &blk)
+      Dir.mkdir(temp_dir, 0o700)
+      with_working(temp_dir, &)
     end
 
     # runs git rev-parse to convert the objectish to a full sha
     #
     # @example
-    #   git.revparse("HEAD^^")
-    #   git.revparse('v2.4^{tree}')
-    #   git.revparse('v2.4:/doc/index.html')
+    #   git.rev_parse("HEAD^^")
+    #   git.rev_parse('v2.4^{tree}')
+    #   git.rev_parse('v2.4:/doc/index.html')
     #
-    def revparse(objectish)
-      self.lib.revparse(objectish)
+    def rev_parse(objectish)
+      lib.rev_parse(objectish)
     end
 
-    def ls_tree(objectish)
-      self.lib.ls_tree(objectish)
+    # For backwards compatibility
+    alias revparse rev_parse
+
+    def ls_tree(objectish, opts = {})
+      lib.ls_tree(objectish, opts)
     end
 
+    # Returns the contents of a git object
+    #
+    # Uses `git cat-file -p` to pretty-print the contents of the given object.
+    #
+    # @param objectish [String] a SHA, branch name, tag, or other revision reference
+    #   to the git object
+    #
+    # @return [String] the contents of the object
+    #
+    # @see https://git-scm.com/docs/git-cat-file git-cat-file
+    #
     def cat_file(objectish)
-      self.lib.object_contents(objectish)
+      lib.cat_file_contents(objectish)
     end
 
-    # returns the name of the branch the working directory is currently on
+    # The name of the branch HEAD refers to or 'HEAD' if detached
+    #
+    # Returns one of the following:
+    #   * The branch name that HEAD refers to (even if it is an unborn branch)
+    #   * 'HEAD' if in a detached HEAD state
+    #
+    # @return [String] the name of the branch HEAD refers to or 'HEAD' if detached
+    #
     def current_branch
-      self.lib.branch_current
+      lib.branch_current
+    end
+
+    # @return [Git::Branch] an object for branch_name
+    def branch(branch_name = current_branch)
+      Git::Branch.new(self, 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)
+    end
+
+    # returns a Git::Worktree object for dir, commitish
+    def worktree(dir, commitish = nil)
+      Git::Worktree.new(self, dir, commitish)
+    end
+
+    # returns a Git::worktrees object of all the Git::Worktrees
+    # objects for this repo
+    def worktrees
+      Git::Worktrees.new(self)
+    end
+
+    # @return [Git::Object::Commit] a commit object
+    def commit_tree(tree = nil, opts = {})
+      Git::Object::Commit.new(self, lib.commit_tree(tree, opts))
+    end
+
+    # @return [Git::Diff] a Git::Diff object
+    def diff(objectish = 'HEAD', obj2 = nil)
+      Git::Diff.new(self, objectish, obj2)
+    end
+
+    # @return [Git::Object] a Git object
+    def gblob(objectish)
+      Git::Object.new(self, objectish, 'blob')
+    end
+
+    # @return [Git::Object] a Git object
+    def gcommit(objectish)
+      Git::Object.new(self, objectish, 'commit')
+    end
+
+    # @return [Git::Object] a Git object
+    def gtree(objectish)
+      Git::Object.new(self, objectish, 'tree')
+    end
+
+    # @return [Git::Log] a log with the specified number of commits
+    def log(count = 30)
+      Git::Log.new(self, count)
+    end
+
+    # returns a Git::Object of the appropriate type
+    # you can also call @git.gtree('tree'), but that's
+    # just for readability.  If you call @git.gtree('HEAD') it will
+    # still return a Git::Object::Commit object.
+    #
+    # object calls a method that will run a rev-parse
+    # on the objectish and determine the type of the object and return
+    # an appropriate object for that type
+    #
+    # @return [Git::Object] an instance of the appropriate type of Git::Object
+    def object(objectish)
+      Git::Object.new(self, objectish)
+    end
+
+    # @return [Git::Remote] a remote of the specified name
+    def remote(remote_name = 'origin')
+      Git::Remote.new(self, remote_name)
+    end
+
+    # @return [Git::Status] a status object
+    def status
+      Git::Status.new(self)
+    end
+
+    # @return [Git::Object::Tag] a tag object
+    def tag(tag_name)
+      Git::Object::Tag.new(self, tag_name)
+    end
+
+    # Find as good common ancestors as possible for a merge
+    # example: g.merge_base('master', 'some_branch', 'some_sha', octopus: true)
+    #
+    # @return [Array<Git::Object::Commit>] a collection of common ancestors
+    def merge_base(*)
+      shas = lib.merge_base(*)
+      shas.map { |sha| gcommit(sha) }
     end
 
+    # Returns a Git::Diff::Stats object for accessing diff statistics.
+    #
+    # @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.
+    #
+    # @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
+    #
+    # 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 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
     #
     # Updates the options parameter by setting appropriate values for the following keys:
@@ -684,18 +1073,58 @@ module Git
     #   2. the working directory if NOT working with a bare repository
     #
     private_class_method def self.normalize_repository(options, default:, bare: false)
-      repository =
-        if bare
-          File.expand_path(options[:repository] || default || Dir.pwd)
-        else
-          File.expand_path(options[:repository] || '.git', options[:working_directory])
-        end
+      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
 
-      if File.file?(repository)
-        repository = File.expand_path(File.open(repository).read[8..-1].strip, options[:working_directory])
+    # Determines the initial, potential path to the repository directory
+    #
+    # 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.
+    #
+    # @api private
+    #
+    # @param options [Hash] The options hash, checked for `[:repository]`.
+    #
+    # @param default [String] A fallback path if `options[:repository]` is not set.
+    #
+    # @param bare [Boolean] Whether the repository is bare, which changes path resolution.
+    #
+    # @return [String] The initial, absolute path to the `.git` directory or file.
+    #
+    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
+    end
+
+    # Resolves the path to the actual repository if it's a `gitdir:` pointer file.
+    #
+    # 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.
+    #
+    # @api private
+    #
+    # @param path [String] The initial path to the repository, which may be a pointer file.
+    #
+    # @param working_dir [String] The working directory, used as a base to resolve the path.
+    #
+    # @return [String] The final, resolved absolute path to the repository directory.
+    #
+    private_class_method def self.resolve_gitdir_if_present(path, working_dir)
+      return path unless File.file?(path)
 
-      options[:repository] = repository
+      # 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)
     end
 
     # Normalize options[:index]