git 5.0.0.beta.3 → 5.0.0.beta.5

data/lib/git.rb

@@ -1,29 +1,54 @@
 # frozen_string_literal: true
 
-require 'active_support'
 require 'active_support/deprecation'
 
-require 'git/deprecation'
-require 'git/version'
-
+# Define Git::Deprecation before requiring the rest of the library to ensure that
+# any deprecation warnings emitted during the loading of the library are properly
+# configured according to the GIT_DEPRECATION_BEHAVIOR environment variable.
+#
 module Git
-  # Minimum git version required by this gem
+  # The deprecation instance used to emit deprecation warnings for the Git gem
   #
-  # Commands and features may require newer versions, but this is the absolute
-  # minimum supported version for the gem as a whole.
+  # @api public
+  Deprecation = ActiveSupport::Deprecation.new('6.0.0', 'Git')
+
+  # Configure a deprecation instance from a GIT_DEPRECATION_BEHAVIOR value
   #
-  # @return [Git::Version]
+  # @param deprecation [ActiveSupport::Deprecation] the deprecation instance to configure
   #
-  # @api public
+  # @param behavior [String, nil] the desired behavior name (e.g. `'silence'`); when
+  #   `nil` the deprecation instance is left unchanged
   #
-  MINIMUM_GIT_VERSION = Version.parse('2.28.0')
+  # @return [void]
+  #
+  # @raise [ArgumentError] if `behavior` is not one of the keys of
+  #   `ActiveSupport::Deprecation::DEFAULT_BEHAVIORS`
+  #
+  # @api private
+  #
+  def self.configure_deprecation_behavior(deprecation, behavior)
+    return if behavior.nil?
+
+    behavior = behavior.strip
+    allowed_behaviors = ActiveSupport::Deprecation::DEFAULT_BEHAVIORS.keys.map(&:to_s)
+
+    unless allowed_behaviors.include?(behavior)
+      raise ArgumentError,
+            "Invalid GIT_DEPRECATION_BEHAVIOR=#{behavior.inspect}; " \
+            "expected one of: #{allowed_behaviors.join(', ')}"
+    end
+
+    deprecation.behavior = behavior.to_sym
+  end
+  private_class_method :configure_deprecation_behavior
+
+  configure_deprecation_behavior(Deprecation, ENV.fetch('GIT_DEPRECATION_BEHAVIOR', nil))
 end
 
 require 'git/author'
 require 'git/branch'
 require 'git/branch_info'
 require 'git/branches'
-require 'git/command_line_result'
 require 'git/command_line'
 require 'process_executer'
 require 'git/config'
@@ -61,6 +86,7 @@ require 'git/tag_delete_failure'
 require 'git/tag_delete_result'
 require 'git/tag_info'
 require 'git/url'
+require 'git/version'
 require 'git/worktree'
 require 'git/worktrees'
 
@@ -69,216 +95,178 @@ require 'git/worktrees'
 # open a bare repository, initialize a new repo or clone an
 # existing remote repository.
 #
-# @author Scott Chacon (mailto:schacon@gmail.com)
-#
 module Git
   extend Git::Configuring
+  extend Git::Repository::Factories
 
-  # @deprecated Mixing in the `Git` module is deprecated and will be removed in v6.0.0.
-  #   Use `Git.config_get(name)`, `Git.config_set(name, value)`, or `Git.config_list` instead.
-  def config(name = nil, value = nil)
-    Git::Deprecation.warn(
-      'Git#config is deprecated and will be removed in v6.0.0. ' \
-      'Use Git.config_get(name), Git.config_set(name, value), or Git.config_list instead.'
-    )
-    Git.__send__(:run_config_utility, name, value, global: false)
-  end
-
-  # Configures the gem by yielding {Git::Config.instance} to the block
-  #
-  # @example Set the global git binary path
-  #   Git.configure { |c| c.binary_path = '/usr/local/bin/git' }
-  #
-  # @yield [config] yields the singleton config object
+  # Minimum git version required by this gem
   #
-  # @yieldparam config [Git::Config] the singleton config object
+  # Commands and features may require newer versions, but this is the absolute
+  # minimum supported version for the gem as a whole.
   #
-  # @yieldreturn [void]
+  # @return [Git::Version]
   #
-  # @return [void]
+  # @api public
   #
-  def self.configure
-    yield Git::Config.instance
-    nil
-  end
+  MINIMUM_GIT_VERSION = Version.parse('2.28.0')
 
-  # Returns the process-wide {Git::Config} singleton
+  # Compatibility shim for code that monkeypatches the `Git::Base` class from
+  # versions prior to 5.0.0.
   #
-  # @example Read the configured binary path
-  #   Git.config.binary_path  #=> "git"
+  # `Git::Base` is a module included in {Git::Repository}, so any instance
+  # methods added to `Git::Base` are automatically available on
+  # {Git::Repository} instances. A deprecation warning is emitted for each
+  # method added, encouraging migration to {Git::Repository}.
   #
-  # @return [Git::Config] the singleton config object
+  # @example Monkeypatching Git::Base (deprecated)
+  #   module Git::Base
+  #     def my_helper = "hello"
+  #   end
+  #   Git.open('.').my_helper  # => "hello"
   #
-  def self.config
-    Git::Config.instance
-  end
+  # @deprecated Define instance methods on {Git::Repository} instead.
+  #
+  # @api public
+  Base = Module.new do
+    # Emit a deprecation warning each time a method is defined in Git::Base so
+    # that authors of monkeypatches are nudged toward Git::Repository.
+    def self.method_added(method_name)
+      Git::Deprecation.warn(
+        'Monkeypatching Git::Base is deprecated and will be removed in v6.0.0. ' \
+        "Define #{method_name} in Git::Repository instead."
+      )
+      super
+    end
 
-  # @deprecated Mixing in the `Git` module is deprecated and will be removed in v6.0.0.
-  #   Use `Git.config_get(name, global: true)`, `Git.config_set(name, value, global: true)`, or
-  #   `Git.config_list(global: true)` instead.
-  def global_config(name = nil, value = nil)
-    Git::Deprecation.warn(
-      'Git#global_config is deprecated and will be removed in v6.0.0. ' \
-      'Use Git.config_get(name, global: true), Git.config_set(name, value, global: true), ' \
-      'or Git.config_list(global: true) instead.'
-    )
-    Git.global_config(name, value)
+    # Raise a clear error when legacy code calls Git::Base.new directly.
+    def self.new(...)
+      raise NoMethodError,
+            'Git::Base.new is not supported. Use Git.open, Git.clone, or Git.init instead.'
+    end
   end
 
-  # Open a bare repository
-  #
-  # Opens a bare repository located in the `git_dir` directory.
-  # Since there is no working copy, you can not checkout or commit
-  # but you can do most read operations.
-  #
-  # @see https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbarerepositoryabarerepository
-  #   What is a bare repository?
-  #
-  # @example Open a bare repository and retrieve the first commit SHA
-  #   repository = Git.bare('ruby-git.git')
-  #   puts repository.log[0].sha #=> "64c6fa011d3287bab9158049c85f3e85718854a0"
-  #
-  # @param [Pathname] git_dir The path to the bare repository directory
-  #   containing an initialized Git repository. If a relative path is given, it
-  #   is converted to an absolute path using
-  #   [File.expand_path](https://www.rubydoc.info/stdlib/core/File.expand_path).
-  #
-  # @param [Hash] options The options for this command (see list of valid
-  #   options below)
-  #
-  # @option options [String, nil] :git_ssh An optional custom SSH command
+  Repository.include(Base)
+
+  # Intercept the first lookup of the deprecated `Git::CommandLineResult` constant
   #
-  #   - If not specified, uses the global config (Git.configure { |c| c.git_ssh = ... }).
-  #   - If nil, disables SSH for this instance.
-  #   - If a non-empty string, uses that value for this instance.
+  # When `name` is `:CommandLineResult`, caches and returns {Git::CommandLine::Result}
+  # after emitting a deprecation warning. Calls `super` for any other unknown constant,
+  # preserving normal Ruby `NameError` behavior.
   #
-  # @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.
+  # @param name [Symbol] the name of the missing constant
   #
-  # @return [Git::Repository] an object that can execute git commands in the context
-  #   of the bare repository.
+  # @return [Class] the resolved constant value
   #
-  def self.bare(git_dir, options = {})
-    Git::Repository.bare(git_dir, options)
+  # @api private
+  def self.const_missing(name)
+    return super unless name == :CommandLineResult
+
+    # Cache the constant first so subsequent accesses are zero-cost even if
+    # the deprecation behavior raises (e.g. in the test suite).
+    const_set(:CommandLineResult, Git::CommandLine::Result)
+    Git::Deprecation.warn(
+      'Git::CommandLineResult is deprecated and will be removed in v6.0.0. ' \
+      'Use Git::CommandLine::Result instead.'
+    )
+    Git::CommandLine::Result
   end
 
-  # Clone a repository into an empty or newly created directory
+  # Gets or sets local git configuration options
   #
-  # @see https://git-scm.com/docs/git-clone git clone
-  # @see https://git-scm.com/docs/git-clone#_git_urls_a_id_urls_a GIT URLs
+  # @overload config(name, value)
+  #   Set the value for the git named configuration option
   #
-  # @param repository_url [URI, Pathname] The (possibly remote) repository url to clone
-  #   from. See [GIT URLS](https://git-scm.com/docs/git-clone#_git_urls_a_id_urls_a)
-  #   for more information.
-  #
-  # @param directory [Pathname, nil] The directory to clone into
+  #   @param name [String] the name of the git configuration option
   #
-  #   If `directory` is a relative path it is relative to the `:chdir` option if
-  #   given. If `:chdir` is not given, `directory` is relative to the current
-  #   working directory.
+  #   @param value [String, Boolean] the value to set for the git configuration option
   #
-  #   If `nil`, `directory` will be set to the basename of the last component of
-  #   the path from the `repository_url`. For example, for the URL:
-  #   `https://github.com/org/repo.git`, `directory` will be set to `repo`.
+  #   @return [Git::CommandLine::Result] the result of the git configuration command
   #
-  #   If the last component of the path is `.git`, the next-to-last component of
-  #   the path is used. For example, for the URL `/Users/me/foo/.git`, `directory`
-  #   will be set to `foo`.
-  #
-  # @param [Hash] options The options for this command (see list of valid
-  #   options below)
+  # @overload config(name)
+  #   Get the value for the git named configuration option
   #
-  # @option options [Boolean] :bare Make a bare Git repository. See
-  #   [what is a bare repository?](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbarerepositoryabarerepository).
+  #   @param name [String] the name of the git configuration option
   #
-  # @option options [String] :branch The name of a branch or tag to checkout
-  #   instead of the default branch.
+  #   @return [String] the value of the git configuration option
   #
-  # @option options [Array, String] :config A list of configuration options to
-  #  set on the newly created repository.
+  # @overload config()
+  #   List all git configuration options
   #
-  # @option options [Integer] :depth Create a shallow clone with a history
-  #   truncated to the specified number of commits.
+  #   @return [Hash{String => String}] a hash of all git configuration options
   #
-  # @option options [String] :filter Request that the server send a partial
-  #   clone according to the given filter
+  # @deprecated Mixing in the `Git` module is deprecated and will be removed in v6.0.0.
+  #   Use `Git.config_get(name)`, `Git.config_set(name, value)`, or `Git.config_list` instead.
   #
-  # @option options [Boolean, nil] :single_branch Control whether the clone
-  #   limits fetch refspecs to a single branch.
-  #   - If nil (default), no flag is passed and the Git default is used.
-  #   - If true, `--single-branch` is passed to limit the refspec to the
-  #     checkout branch.
-  #   - If false, `--no-single-branch` is passed to broaden the refspec (useful
-  #     for shallow clones that should include all branches).
+  def config(name = nil, value = nil)
+    Git::Deprecation.warn(
+      'Git#config is deprecated and will be removed in v6.0.0. ' \
+      'Use Git.config_get(name), Git.config_set(name, value), or Git.config_list instead.'
+    )
+    Git.__send__(:legacy_config_set_get_list, name, value, global: false)
+  end
+
+  # Configures the gem by yielding {Git::Config.instance} to the block
   #
-  # @option options [String, nil] :git_ssh An optional custom SSH command
+  # @example Set the global git binary path
+  #   Git.configure { |c| c.binary_path = '/usr/local/bin/git' }
   #
-  #   - If not specified, uses the global config (Git.configure { |c| c.git_ssh = ... }).
-  #   - If nil, disables SSH for this instance.
-  #   - If a non-empty string, uses that value for this instance.
+  # @return [void]
   #
-  # @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.
+  # @yield [config] yields the singleton config object
   #
-  # @option options [Boolean] :mirror Set up a mirror of the source repository.
+  # @yieldparam config [Git::Config] the singleton config object
   #
-  # @option options [String] :origin Use the value instead `origin` to track
-  #   the upstream repository.
+  # @yieldreturn [void]
   #
-  # @option options [Pathname] :chdir Run `git clone` from within this directory.
+  def self.configure
+    yield Git::Config.instance
+    nil
+  end
+
+  # Returns the process-wide {Git::Config} singleton
   #
-  #   The `directory` parameter (or the repository basename when `directory` is nil)
-  #   is resolved relative to `:chdir`, just as if you had `cd`'d into it before
-  #   running `git clone`. The returned path is the join of `:chdir` and the
-  #   cloned directory path.
+  # @example Read the configured binary path
+  #   Git.config.binary_path  #=> "git"
   #
-  # @option options [Pathname] :path Deprecated — use `:chdir` instead.
+  # @return [Git::Config] the singleton config object
   #
-  # @option options [Boolean] :recursive After the clone is created, initialize
-  #   all submodules within, using their default settings.
+  def self.config
+    Git::Config.instance
+  end
+
+  # Gets or sets global git configuration options
   #
-  # @example Clone into the default directory `ruby-git`
-  #   git = Git.clone('https://github.com/ruby-git/ruby-git.git')
+  # @overload global_config(name, value)
+  #   Set the value for the git named configuration option
   #
-  # @example Clone and then checkout the `development` branch
-  #   git = Git.clone('https://github.com/ruby-git/ruby-git.git', branch: 'development')
+  #   @param name [String] the name of the git configuration option
   #
-  # @example Clone into a different directory `my-ruby-git`
-  #   git = Git.clone('https://github.com/ruby-git/ruby-git.git', 'my-ruby-git')
+  #   @param value [String, Boolean] the value to set for the git configuration option
   #
-  # @example Clone into a specific parent directory
-  #   git = Git.clone('https://github.com/ruby-git/ruby-git.git', chdir: '/path/to/projects')
-  #   # clones into /path/to/projects/ruby-git
+  #   @return [Git::CommandLine::Result] the result of the git configuration command
   #
-  # @example Create a bare repository in the directory `ruby-git.git`
-  #   git = Git.clone('https://github.com/ruby-git/ruby-git.git', bare: true)
+  # @overload global_config(name)
+  #   Get the value for the git named configuration option
   #
-  # @example Clone a repository and set a single config option
-  #   git = Git.clone(
-  #     'https://github.com/ruby-git/ruby-git.git',
-  #     config: 'submodule.recurse=true'
-  #   )
+  #   @param name [String] the name of the git configuration option
   #
-  # @example Clone a repository and set multiple config options
-  #   git = Git.clone(
-  #     'https://github.com/ruby-git/ruby-git.git',
-  #     config: ['user.name=John Doe', 'user.email=john@doe.com']
-  #   )
+  #   @return [String] the value of the git configuration option
   #
-  # @example Clone using a specific SSH key
-  #   git = Git.clone(
-  #     'git@github.com:ruby-git/ruby-git.git',
-  #     'local-dir',
-  #     git_ssh: 'ssh -i /path/to/private_key'
-  #   )
+  # @overload global_config()
+  #   List all git configuration options
   #
-  # @return [Git::Repository] an object that can execute git commands in the context
-  #   of the cloned local working copy or cloned repository.
+  #   @return [Hash{String => String}] a hash of all git configuration options
   #
-  def self.clone(repository_url, directory = nil, options = {})
-    Git::Repository.clone(repository_url, directory, options)
+  # @deprecated Mixing in the `Git` module is deprecated and will be removed in v6.0.0.
+  #   Use `Git.config_get(name, global: true)`, `Git.config_set(name, value, global: true)`, or
+  #   `Git.config_list(global: true)` instead.
+  def global_config(name = nil, value = nil)
+    Git::Deprecation.warn(
+      'Git#global_config is deprecated and will be removed in v6.0.0. ' \
+      'Use Git.config_get(name, global: true), Git.config_set(name, value, global: true), ' \
+      'or Git.config_list(global: true) instead.'
+    )
+    Git.__send__(:legacy_config_set_get_list, name, value, global: true)
   end
 
   # Returns the name of the default branch of the given repository
@@ -301,15 +289,16 @@ module Git
   # @example with the logging option
   #   logger = Logger.new(STDOUT, level: Logger::INFO)
   #   Git.default_branch('.', log: logger) # => 'master'
-  #   I, [2022-04-13T16:01:33.221596 #18415]  INFO -- : git '-c' 'core.quotePath=true'
-  #     '-c' 'color.ui=false' ls-remote '--symref' '--' '.' 'HEAD'  2>&1
+  #   # Logs the executed git command to STDOUT, for example:
+  #   #   I, [2022-04-13T16:01:33.221596 #18415]  INFO -- : git '-c' 'core.quotePath=true'
+  #   #     '-c' 'color.ui=false' ls-remote '--symref' '--' '.' 'HEAD'  2>&1
   #
   # @param repository [URI, Pathname, String] The (possibly remote) repository to get the default branch name for
   #
   #   See [GIT URLS](https://git-scm.com/docs/git-clone#_git_urls_a_id_urls_a)
   #   for more information.
   #
-  # @param [Hash] options The options for this command (see list of valid
+  # @param options [Hash] The options for this command (see list of valid
   #   options below)
   #
   # @option options [Logger] :log A logger to use for Git operations.  Git
@@ -324,94 +313,64 @@ module Git
     Git::Parsers::LsRemote.parse_default_branch(output)
   end
 
-  # Export the current HEAD (or a branch, if <tt>options[:branch]</tt>
-  # is specified) into the +name+ directory, then remove all traces of git from the
-  # directory.
+  # Clone a repository into `directory` then remove its `.git` directory
   #
-  # See +clone+ for options.  Does not obey the <tt>:remote</tt> option,
-  # since the .git info will be deleted anyway; always uses the default
-  # remote, 'origin.'
-  def self.export(repository, name, options = {})
-    options.delete(:remote)
-    repo = clone(repository, name, { depth: 1 }.merge(options))
-    repo.checkout("origin/#{options[:branch]}") if options[:branch]
-    FileUtils.rm_r File.join(repo.dir.to_s, '.git')
-  end
-
-  # Same as g.config, but forces it to be at the global level
-  #
-  # g.config('user.name', 'Scott Chacon') # sets value
-  # g.config('user.email', 'email@email.com')  # sets value
-  # g.config('user.name')  # returns 'Scott Chacon'
-  # g.config # returns whole config hash
-  def self.global_config(name = nil, value = nil)
-    run_config_utility(name, value, global: true)
-  end
-
-  # Create an empty Git repository or reinitialize an existing Git repository
+  # Exports the current HEAD (or the specific branch given in <tt>options[:branch]</tt>)
+  # into the given `directory`. It then removes all traces of git from the directory.
   #
-  # @param [Pathname] directory If the `:bare` option is NOT given or is not
-  #   `true`, the repository will be created in `"#{directory}/.git"`.
-  #   Otherwise, the repository is created in `"#{directory}"`.
+  # Takes the same options as {Git.clone} except that `:remote` is silently ignored
+  # and `:depth` defaults to 1.
   #
-  #   All directories along the path to `directory` are created if they do not exist.
+  # @param repository_url [String, URI, Pathname] the repository to export from
   #
-  #   A relative path is referenced from the current working directory of the process
-  #   and converted to an absolute path using
-  #   [File.expand_path](https://www.rubydoc.info/stdlib/core/File.expand_path).
-  #
-  # @param [Hash] options The options for this command (see list of valid
-  #   options below)
+  # @param directory [String, Pathname, nil] the directory to export into; defaults to the
+  #   repository basename
   #
-  # @option options [Boolean] :bare Instead of creating a repository at
-  #   `"#{directory}/.git"`, create a bare repository at `"#{directory}"`.
-  #   See [what is a bare repository?](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbarerepositoryabarerepository).
+  # @param options [Hash] options forwarded to {Git.clone} (`:remote` is ignored;
+  #   `:depth` defaults to 1)
   #
-  # @option options [String] :initial_branch Use the specified name for the
-  #   initial branch in the newly created repository.
+  # @option options [String] :branch the branch or tag to export instead of HEAD
   #
-  # @option options [Pathname] :repository the path to put the newly initialized
-  #   Git repository. The default for non-bare repository is `"#{directory}/.git"`.
-  #
-  #   A relative path is referenced from the current working directory of the process
-  #   and converted to an absolute path using
-  #   [File.expand_path](https://www.rubydoc.info/stdlib/core/File.expand_path).
-  #
-  # @option options [Pathname] :separate_git_dir Alias for `:repository`.
-  #
-  # @option options [String, nil] :git_ssh An optional custom SSH command
+  # @return [void]
   #
-  #   - If not specified, uses the global config (Git.configure { |c| c.git_ssh = ... }).
-  #   - If nil, disables SSH for this instance.
-  #   - If a non-empty string, uses that value for this instance.
+  def self.export(repository_url, directory = nil, options = {})
+    options.delete(:remote)
+    repo = clone(repository_url, directory, { depth: 1 }.merge(options))
+    repo.checkout("origin/#{options[:branch]}") if options[:branch]
+    FileUtils.rm_r File.join(repo.dir.to_s, '.git')
+  end
+
+  # Get or set a git global configuration value
   #
-  # @option options [String, :use_global_config] :binary_path path to the git
-  #   binary; defaults to `Git::Config.instance.binary_path` when not specified.
-  #   Raises `ArgumentError` if set to `nil`.
+  # @example Set a value
+  #   Git.global_config('user.name', 'Scott Chacon')
   #
-  # @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.
+  # @example Get a value
+  #   Git.global_config('user.name')  # => 'Scott Chacon'
   #
-  # @return [Git::Repository] an object that can execute git commands in the context
-  #   of the newly initialized repository
+  # @example List all global config entries
+  #   Git.global_config  # => { 'user.name' => 'Scott Chacon', ... }
   #
-  # @example Initialize a repository in the current directory
-  #   git = Git.init
+  # @param name [String, nil] the config key to get or set; omit to list all
   #
-  # @example Initialize a repository in some other directory
-  #   git = Git.init '~/code/ruby-git'
+  # @param value [Object, nil] the value to set; omit to get or list
   #
-  # @example Initialize a bare repository
-  #   git = Git.init '~/code/ruby-git.git', bare: true
+  # @return [String, Hash, Git::CommandLine::Result] the config value, all entries,
+  #   or the result of the set command
   #
-  # @example Initialize a repository in a non-default location (outside of the working copy)
-  #   git = Git.init '~/code/ruby-git', repository: '~/code/ruby-git.git'
+  # @deprecated Use {Git.config_get}, {Git.config_set}, or {Git.config_list} instead.
   #
-  # @see https://git-scm.com/docs/git-init git init
+  #   - `Git.global_config('user.name')` → `Git.config_get('user.name', global: true)`
+  #   - `Git.global_config('user.name', 'Bob')` → `Git.config_set('user.name', 'Bob', global: true)`
+  #   - `Git.global_config` → `Git.config_list(global: true)`
   #
-  def self.init(directory = '.', options = {})
-    Git::Repository.init(directory, options)
+  def self.global_config(name = nil, value = nil)
+    Git::Deprecation.warn(
+      'Git.global_config is deprecated and will be removed in v6.0.0. ' \
+      'Use Git.config_get(name, global: true), Git.config_set(name, value, global: true), ' \
+      'or Git.config_list(global: true) instead.'
+    )
+    legacy_config_set_get_list(name, value, global: true)
   end
 
   # Option keys accepted by {.ls_remote}
@@ -429,84 +388,129 @@ module Git
   ].freeze
   private_constant :LS_REMOTE_ALLOWED_OPTS
 
-  # returns a Hash containing information about the references
-  # of the target repository
+  # Displays references available in a remote repository along with the associated commit IDs
   #
-  # options
-  #   :refs
+  # @example From a remote repository given its URL
+  #   references = Git.ls_remote('https://github.com/user/repo.git')
   #
-  # @param [String|NilClass] location the target repository location or nil for '.'
-  # @return [{String=>Hash}] the available references of the target repo.
-  def self.ls_remote(location = nil, options = {})
-    options = options.dup
-    log = options.delete(:log)
-    unknown = options.keys - LS_REMOTE_ALLOWED_OPTS
-    raise ArgumentError, "Unknown options: #{unknown.join(', ')}" unless unknown.empty?
-
-    context = Git::ExecutionContext::Global.new(logger: log)
-    repository = location || '.'
-    output_lines = Git::Commands::LsRemote.new(context).call(repository, **options).stdout.split("\n")
-    Git::Parsers::LsRemote.parse_output(output_lines)
-  end
-
-  # Open a an existing Git working directory
+  # @example From the default remote of the current repository
+  #   references = Git.ls_remote
   #
-  # Git.open will most likely be the most common way to create
-  # a git reference, referring to an existing working directory.
+  # @example From a specific remote of the current repository
+  #   references = Git.ls_remote('origin')
   #
-  # If not provided in the options, the library will assume
-  # the repository and index are in the default places (`.git/`, `.git/index`).
+  # @param repository [String, nil] the target repository location or the name of a remote
   #
-  # @example Open the Git working directory in the current directory
-  #   git = Git.open
+  #   Defaults to `'.'` (the current directory). Passing `nil` explicitly is
+  #   deprecated and will be removed in v6.0.0; pass `'.'` or omit the argument.
   #
-  # @example Open a Git working directory in some other directory
-  #   git = Git.open('~/Projects/ruby-git')
+  # @param options [Hash] the options to pass to the git command
   #
-  # @example Use a logger to see what is going on
-  #   logger = Logger.new(STDOUT)
-  #   git = Git.open('~/Projects/ruby-git', log: logger)
+  # @option options [Boolean, nil] :branches (nil) limit output to refs under `refs/heads/`
   #
-  # @example Open a working copy whose repository is in a non-standard directory
-  #   git = Git.open('~/Projects/ruby-git', repository: '~/Project/ruby-git.git')
+  #   Alias: `:b`
   #
-  # @param [Pathname] working_dir the path to the working directory to use
-  #   for git commands.
+  # @option options [Boolean, nil] :heads (nil) limit output to refs under `refs/heads/`
   #
-  #   A relative path is referenced from the current working directory of the process
-  #   and converted to an absolute path using
-  #   [File.expand_path](https://www.rubydoc.info/stdlib/core/File.expand_path).
+  #   Deprecated: use `:branches` instead. Kept for backward compatibility with
+  #   older git versions where `--heads` is the only supported flag.
   #
-  # @param [Hash] options The options for this command (see list of valid
-  #   options below)
+  #   Alias: `:h`
   #
-  # @option options [Pathname] :repository used to specify a non-standard path to
-  #   the repository directory.  The default is `"#{working_dir}/.git"`.
+  # @option options [Boolean, nil] :tags (nil) limit output to refs under `refs/tags/`
   #
-  # @option options [Pathname] :index used to specify a non-standard path to an
-  #   index file.  The default is `"#{working_dir}/.git/index"`
+  #   Alias: `:t`
   #
-  # @option options [String, nil] :git_ssh An optional custom SSH command
+  # @option options [Boolean, nil] :refs (nil) exclude peeled tags and pseudorefs
+  #   like `HEAD` from the output
   #
-  #   - If not specified, uses the global config (Git.configure { |c| c.git_ssh = ... }).
-  #   - If nil, disables SSH for this instance.
-  #   - If a non-empty string, uses that value for this instance.
+  # @option options [String] :upload_pack (nil) full path to `git-upload-pack` on the
+  #   remote host
   #
-  # @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.
+  #   Useful when accessing repositories via SSH where the daemon does not use the
+  #   PATH configured by the user.
+  #
+  # @option options [Boolean, nil] :quiet (nil) do not print the remote URL to stderr
+  #
+  #   Alias: `:q`
+  #
+  # @option options [Boolean, nil] :exit_code (nil) exit with status `2` when no
+  #   matching refs are found in the remote repository
+  #
+  #   Without this option, the command exits `0` whenever it successfully
+  #   communicates with the remote, even if no refs match.
   #
-  # @return [Git::Repository] an object that can execute git commands in the context
-  #   of the opened working copy
+  # @option options [String] :sort (nil) sort output by the given key
   #
-  def self.open(working_dir, options = {})
-    Git::Repository.open(working_dir, options)
+  #   Prefix `-` for descending order. Supports `"version:refname"` or `"v:refname"`.
+  #   See `git for-each-ref` for sort key documentation.
+  #
+  # @option options [String, Array<String>] :server_option (nil) transmit a string to
+  #   the server when communicating using protocol version 2
+  #
+  #   The string must not contain NUL or LF characters. Repeatable by passing an
+  #   Array. Alias: `:o`
+  #
+  # @option options [Numeric] :timeout (nil) execution timeout in seconds
+  #
+  # @option options [Logger] :log (nil) a logger to use for Git operations
+  #
+  #   Git commands are logged at the `:info` level. Additional logging is done at
+  #   the `:debug` level.
+  #
+  # @return [Hash{String => Hash}] the available references of the target repo
+  #
+  def self.ls_remote(repository = '.', options = {})
+    repository = normalize_ls_remote_repository(repository)
+    options = options.dup
+    log = options.delete(:log)
+    unknown = options.keys - LS_REMOTE_ALLOWED_OPTS
+    raise ArgumentError, "Unknown options: #{unknown.join(', ')}" unless unknown.empty?
+
+    context = Git::ExecutionContext::Global.new(logger: log)
+    output_lines = Git::Commands::LsRemote.new(context).call(repository, **options).stdout.split("\n")
+    Git::Parsers::LsRemote.parse_output(output_lines)
   end
 
+  # Normalize the repository argument for {.ls_remote}
+  #
+  # Returns the repository unchanged unless it is nil, in which case a
+  # deprecation warning is emitted and `'.'` is returned.
+  #
+  # @param repository [String, nil] the repository argument passed by the caller
+  #
+  # @return [String] the normalized repository value (`'.'` when nil was given)
+  #
+  # @api private
+  #
+  def self.normalize_ls_remote_repository(repository)
+    return repository unless repository.nil?
+
+    Git::Deprecation.warn(
+      'Passing nil as the repository to Git.ls_remote is deprecated and will ' \
+      "be removed in v6.0.0. Pass '.' explicitly or omit the argument instead."
+    )
+
+    '.'
+  end
+  private_class_method :normalize_ls_remote_repository
+
   # Thread-safe cache for git versions, keyed by binary path.
   @git_version_cache_mutex = Mutex.new
   @git_version_cache = {}
 
+  # Return the cached git version for the given binary path
+  #
+  # If it isn't already known, compute it using the given block.
+  #
+  # @param binary_path [String] the path to the git binary
+  #
+  # @return [Git::Version] the git version
+  #
+  # @yield [] compute the git version if it is not cached
+  #
+  # @yieldreturn [Git::Version] the computed git version
+  #
   # @api private
   def self.cached_git_version(binary_path, &block)
     @git_version_cache_mutex.synchronize do
@@ -514,6 +518,10 @@ module Git
     end
   end
 
+  # Clear the cached git version for all binary paths
+  #
+  # @return [void]
+  #
   # @api private
   def self.clear_git_version_cache
     @git_version_cache_mutex.synchronize do
@@ -545,35 +553,135 @@ module Git
     cached_git_version(path) { run_git_version(path) }
   end
 
+  # Return the version of the git binary
+  #
+  # @param path [String] the path to the git binary
+  #
+  # @return [Git::Version] the parsed git version
+  #
+  # @raise [Git::UnexpectedResultError] if the version output cannot be parsed
+  #
+  # @raise [Git::FailedError] if the git binary exits with a non-zero status
+  #
+  # @raise [Git::Error] if the binary is not found or fails to launch
+  #
   # @api private
+  #
   def self.run_git_version(path)
     output = Git::Commands::Version.new(Git::ExecutionContext::Global.new(binary_path: path)).call.stdout
     Git::Version.parse(output)
   end
   private_class_method :run_git_version
 
+  # Get or set a git config value
+  #
+  # @overload legacy_config_set_get_list(name, value, global:)
+  #
+  #   Set the value of a git configuration option
+  #
+  #   @param name [String] the name of the git configuration value to set
+  #
+  #   @param value [String, Boolean] the value to set
+  #
+  #   @param global [Boolean] true to use the global git configuration, false for the
+  #     local repo config
+  #
+  #   @return [Git::CommandLine::Result] the result of the git config command
+  #
+  # @overload legacy_config_set_get_list(name, global:)
+  #
+  #   Get the value of a git configuration option
+  #
+  #   @param name [String] the name of the git configuration value to get
+  #
+  #   @param global [Boolean] true to use the global git configuration, false for the
+  #     local repo config
+  #
+  #   @return [String] the value of the git configuration option
+  #
+  # @overload legacy_config_set_get_list(global:)
+  #
+  #   Get all git configuration options
+  #
+  #   @param global [Boolean] true to use the global git configuration, false for the
+  #     local repo config
+  #
+  #   @return [Hash{String => String}] all git configuration options
+  #
+  # @raise [Git::FailedError] if the git config command fails
+  #
   # @api private
-  def self.run_config_utility(name, value, global:)
-    context = Git::ExecutionContext::Global.new
-    options = global ? { global: true } : {}
-
-    return Git::Commands::ConfigOptionSyntax::Set.new(context).call(name, value, **options) if !name.nil? && !value.nil?
-    return run_config_get(context, name, options) if name
+  #
+  def self.legacy_config_set_get_list(name, value, global:)
+    if !name.nil? && !value.nil?
+      legacy_config_set(name, value, global:)
+    elsif !name.nil?
+      legacy_config_get(name, global:)
+    else
+      legacy_config_list(global:)
+    end
+  end
+  private_class_method :legacy_config_set_get_list
 
-    output = Git::Commands::ConfigOptionSyntax::List.new(context).call(**options).stdout
-    parse_config_list(output.split("\n"))
+  # Set the value of a git configuration option
+  #
+  # @param name [String] the name of the git configuration value to set
+  #
+  # @param value [String, Boolean] the value to set
+  #
+  # @param global [Boolean] whether to use the global git configuration
+  #
+  # @api private
+  #
+  def self.legacy_config_set(name, value, global:)
+    options = global ? { global: true } : {}
+    Git::Commands::ConfigOptionSyntax::Set.new(execution_context).call(name, value, **options)
   end
-  private_class_method :run_config_utility
+  private_class_method :legacy_config_set
 
-  def self.run_config_get(context, name, options)
-    result = Git::Commands::ConfigOptionSyntax::Get.new(context).call(name, **options)
+  # Get the value of a git configuration option
+  #
+  # @param name [String] the name of the git configuration option
+  #
+  # @param global [Boolean] whether to use the global git configuration
+  #
+  # @return [String] the value of the git configuration option
+  #
+  # @api private
+  #
+  def self.legacy_config_get(name, global:)
+    options = global ? { global: true } : {}
+    result = Git::Commands::ConfigOptionSyntax::Get.new(execution_context).call(name, **options)
     raise Git::FailedError, result if result.status.exitstatus != 0
 
     result.stdout
   end
-  private_class_method :run_config_get
+  private_class_method :legacy_config_get
+
+  # Get a list of all git configuration options
+  #
+  # @param global [Boolean] true to use the global git configuration, false for the
+  #     local repo config
+  #
+  # @return [Hash{String => String}] all git configuration options
+  #
+  # @api private
+  #
+  def self.legacy_config_list(global:)
+    options = global ? { global: true } : {}
+    output = Git::Commands::ConfigOptionSyntax::List.new(execution_context).call(**options).stdout
+    parse_config_list(output.split("\n"))
+  end
+  private_class_method :legacy_config_list
 
+  # Parse the output of `git config --list` into a hash
+  #
+  # @param lines [Array<String>] the lines of output from `git config --list`
+  #
+  # @return [Hash{String => String}] the parsed git configuration options
+  #
   # @api private
+  #
   def self.parse_config_list(lines)
     lines.each_with_object({}) do |line, hsh|
       key, value = line.split('=', 2)
@@ -600,10 +708,23 @@ module Git
   # The +:local+, +:worktree+, and +:blob+ scopes require an active git
   # repository and are therefore not valid at the Git module level.
   #
+  # @param options_to_check [Hash{Symbol => Object}] the scope options to check
+  #
+  #   If any of the options listed in +REPOSITORY_SPECIFIC_SCOPES+ are present and
+  #   truthy, an +ArgumentError+ will be raised.
+  #
+  # @option options_to_check [Object] :local truthy value requests local scope
+  #
+  # @option options_to_check [Object] :worktree truthy value requests worktree scope
+  #
+  # @option options_to_check [Object] :blob truthy value requests blob scope
+  #
+  # @raise [ArgumentError] if a repository-specific scope is requested
+  #
   # @api private
   #
-  def self.assert_valid_scope!(**opts)
-    invalid = REPOSITORY_SPECIFIC_SCOPES.select { |s| opts[s] }
+  def self.assert_valid_scope!(**options_to_check)
+    invalid = REPOSITORY_SPECIFIC_SCOPES.select { |s| options_to_check[s] }
     return if invalid.empty?
 
     raise ArgumentError, "#{invalid.join(', ')} scope requires a repository"