git 4.0.0 → 4.0.1

data/lib/git/base.rb

@@ -16,7 +16,7 @@ module Git
     # (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)
@@ -35,40 +35,48 @@ module Git
     #
     # @return [Git::Config] the current config instance.
     def self.config
-      @@config ||= Config.new
+      @config ||= Config.new
     end
 
     def self.binary_version(binary_path)
-      result = nil
-      status = nil
-
-      begin
-        result, status = Open3.capture2e(binary_path, "-c", "core.quotePath=true", "-c", "color.ui=false", "version")
-        result = result.chomp
-      rescue Errno::ENOENT
-        raise RuntimeError, "Failed to get git version: #{binary_path} not found"
-      end
+      result, status = execute_git_version(binary_path)
 
-      if status.success?
-        version = result[/\d+(\.\d+)+/]
-        version_parts = version.split('.').collect { |i| i.to_i }
-        version_parts.fill(0, version_parts.length...3)
-      else
-        raise RuntimeError, "Failed to get git version: #{status}\n#{result}"
-      end
+      raise "Failed to get git version: #{status}\n#{result}" unless status.success?
+
+      parse_version_string(result)
+    end
+
+    private_class_method def self.execute_git_version(binary_path)
+      Open3.capture2e(
+        binary_path,
+        '-c', 'core.quotePath=true',
+        '-c', 'color.ui=false',
+        'version'
+      )
+    rescue Errno::ENOENT
+      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)
@@ -82,24 +90,32 @@ module Git
       #
       Git::Lib.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)
 
-      begin
-        result, status = Open3.capture2e(Git::Base.config.binary_path, "-c", "core.quotePath=true", "-c", "color.ui=false", "rev-parse", "--show-toplevel", chdir: File.expand_path(working_dir))
-        result = result.chomp
-      rescue Errno::ENOENT
-        raise ArgumentError, "Failed to find the root of the worktree: git binary not found"
-      end
+      result, status = execute_rev_parse_toplevel(working_dir)
+      process_rev_parse_result(result, status, working_dir)
+    end
+
+    private_class_method def self.execute_rev_parse_toplevel(working_dir)
+      Open3.capture2e(
+        Git::Base.config.binary_path,
+        '-c', 'core.quotePath=true',
+        '-c', 'color.ui=false',
+        'rev-parse', '--show-toplevel',
+        chdir: File.expand_path(working_dir)
+      )
+    rescue Errno::ENOENT
+      raise ArgumentError, 'Failed to find the root of the worktree: git binary not found'
+    end
 
+    private_class_method def self.process_rev_parse_result(result, status, working_dir)
       raise ArgumentError, "'#{working_dir}' is not in a git working tree" unless status.success?
-      result
+
+      result.chomp
     end
 
     # (see Git.open)
@@ -110,7 +126,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
@@ -136,16 +152,9 @@ module Git
     #   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")
-
-      @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
+      options = default_paths(options)
+      setup_logger(options[:log])
+      initialize_components(options)
     end
 
     # Update the index from the current worktree to prepare the for the next commit
@@ -162,7 +171,7 @@ module Git
     # @option options [Boolean] :force Allow adding otherwise ignored files
     #
     def add(paths = '.', **options)
-      self.lib.add(paths, options)
+      lib.add(paths, options)
     end
 
     # adds a new remote to this repository
@@ -177,33 +186,10 @@ module Git
     #   :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)
+      lib.remote_add(name, url, opts)
       Git::Remote.new(self, name)
     end
 
-    # Create a new git tag
-    #
-    # @example
-    #   repo.add_tag('tag_name', object_reference)
-    #   repo.add_tag('tag_name', object_reference, {:options => 'here'})
-    #   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`.
-    #   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 [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.
-    #
-    def add_tag(name, *options)
-      self.lib.tag(name, *options)
-      self.tag(name)
-    end
-
     # changes current working directory for a block
     # to the git working directory
     #
@@ -219,11 +205,11 @@ module Git
       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
@@ -245,9 +231,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
@@ -257,43 +241,77 @@ 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
 
+    def is_local_branch?(branch) # rubocop:disable Naming/PredicatePrefix
+      Git.deprecation('Git::Base#is_local_branch? is deprecated. 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
 
+    def is_remote_branch?(branch) # rubocop:disable Naming/PredicatePrefix
+      Git.deprecated('Git::Base#is_remote_branch? is deprecated. 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
 
+    def is_branch?(branch) # rubocop:disable Naming/PredicatePrefix
+      Git.deprecated('Git::Base#is_branch? is deprecated. 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
@@ -333,32 +351,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
 
     # 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
     #
     def ignored_files
-      self.lib.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
@@ -369,7 +387,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
@@ -387,8 +405,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.
@@ -398,7 +416,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
@@ -410,25 +428,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,
@@ -438,7 +456,7 @@ module Git
         opts = remote
         remote = nil
       end
-      self.lib.fetch(remote, opts)
+      lib.fetch(remote, opts)
     end
 
     # Push changes to a remote repository
@@ -459,20 +477,20 @@ 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
@@ -495,12 +513,12 @@ module Git
     # @raise [Git::FailedError] if the pull fails
     # @raise [ArgumentError] if a branch is given without a remote
     def pull(remote = nil, branch = nil, opts = {})
-      self.lib.pull(remote, branch, 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
 
     # sets the url for a remote
@@ -510,7 +528,7 @@ module Git
     #
     def set_remote_url(name, url)
       url = url.repo.path if url.is_a?(Git::Base)
-      self.lib.remote_set_url(name, url)
+      lib.remote_set_url(name, url)
       Git::Remote.new(self, name)
     end
 
@@ -518,12 +536,12 @@ module Git
     #
     # @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
 
     # Create a new git tag
@@ -545,37 +563,37 @@ 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
 
     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
@@ -583,8 +601,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 ##
@@ -597,11 +615,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
@@ -609,19 +627,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 = {})
@@ -633,9 +651,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
@@ -649,13 +666,13 @@ 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
@@ -666,18 +683,18 @@ module Git
     #   git.rev_parse('v2.4:/doc/index.html')
     #
     def rev_parse(objectish)
-      self.lib.rev_parse(objectish)
+      lib.rev_parse(objectish)
     end
 
     # For backwards compatibility
     alias revparse rev_parse
 
     def ls_tree(objectish, opts = {})
-      self.lib.ls_tree(objectish, opts)
+      lib.ls_tree(objectish, opts)
     end
 
     def cat_file(objectish)
-      self.lib.cat_file(objectish)
+      lib.cat_file(objectish)
     end
 
     # The name of the branch HEAD refers to or 'HEAD' if detached
@@ -689,11 +706,11 @@ module Git
     # @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 = self.current_branch)
+    def branch(branch_name = current_branch)
       Git::Branch.new(self, branch_name)
     end
 
@@ -716,7 +733,7 @@ module Git
 
     # @return [Git::Object::Commit] a commit object
     def commit_tree(tree = nil, opts = {})
-      Git::Object::Commit.new(self, self.lib.commit_tree(tree, opts))
+      Git::Object::Commit.new(self, lib.commit_tree(tree, opts))
     end
 
     # @return [Git::Diff] a Git::Diff object
@@ -770,19 +787,19 @@ module Git
 
     # @return [Git::Object::Tag] a tag object
     def tag(tag_name)
-      Git::Object.new(self, tag_name, 'tag', true)
+      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(*args)
-      shas = self.lib.merge_base(*args)
+    def merge_base(*)
+      shas = lib.merge_base(*)
       shas.map { |sha| gcommit(sha) }
     end
 
-# Returns a Git::Diff::Stats object for accessing diff statistics.
+    # 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.
@@ -805,6 +822,38 @@ module Git
 
     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], 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:
@@ -868,18 +917,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]