git 4.3.2 → 5.0.0.beta.2

data/lib/git.rb

@@ -3,36 +3,64 @@
 require 'active_support'
 require 'active_support/deprecation'
 
+require 'git/deprecation'
+require 'git/version'
+
 module Git
-  Deprecation = ActiveSupport::Deprecation.new('5.0.0', 'Git')
+  # Minimum git version required by this gem
+  #
+  # Commands and features may require newer versions, but this is the absolute
+  # minimum supported version for the gem as a whole.
+  #
+  # @return [Git::Version]
+  #
+  # @api public
+  #
+  MINIMUM_GIT_VERSION = Version.parse('2.28.0')
 end
 
 require 'git/author'
-require 'git/base'
 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'
+require 'git/config_entry_info'
+require 'git/parsers/config_entry'
+require 'git/configuring'
 require 'git/diff'
+require 'git/diff_file_numstat_info'
+require 'git/diff_file_patch_info'
+require 'git/diff_file_raw_info'
+require 'git/diff_info'
+require 'git/parsers/diff'
+require 'git/diff_result'
+require 'git/dirstat_info'
 require 'git/encoding_utils'
 require 'git/errors'
 require 'git/escaped_path'
+require 'git/execution_context'
+require 'git/execution_context/global'
+require 'git/file_ref'
 require 'git/fsck_object'
 require 'git/fsck_result'
-require 'git/index'
-require 'git/lib'
+require 'git/parsers/ls_remote'
+require 'git/version_constraint'
+require 'git/commands'
 require 'git/log'
 require 'git/object'
-require 'git/path'
 require 'git/remote'
 require 'git/repository'
 require 'git/status'
 require 'git/stash'
+require 'git/stash_info'
 require 'git/stashes'
+require 'git/tag_delete_failure'
+require 'git/tag_delete_result'
+require 'git/tag_info'
 require 'git/url'
-require 'git/version'
-require 'git/working_directory'
 require 'git/worktree'
 require 'git/worktrees'
 
@@ -43,35 +71,56 @@ require 'git/worktrees'
 #
 # @author Scott Chacon (mailto:schacon@gmail.com)
 #
-module Git # rubocop:disable Style/OneClassPerFile
-  # 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
+module Git
+  extend Git::Configuring
+
+  # @deprecated Mixing in the `Git` module is deprecated and will be removed in v6.0.0.
+  #   Use `Git.open(Dir.pwd).config(...)` instead.
   def config(name = nil, value = nil)
-    lib = Git::Lib.new
-    if name && value
-      # set value
-      lib.config_set(name, value)
-    elsif name
-      # return value
-      lib.config_get(name)
-    else
-      # return hash
-      lib.config_list
-    end
+    Git::Deprecation.warn(
+      'Git#config is deprecated and will be removed in v6.0.0. ' \
+      'Use Git.open(Dir.pwd).config(...) 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
+  #
+  # @yieldparam config [Git::Config] the singleton config object
+  #
+  # @yieldreturn [void]
+  #
+  # @return [void]
+  #
   def self.configure
-    yield Base.config
+    yield Git::Config.instance
+    nil
   end
 
+  # Returns the process-wide {Git::Config} singleton
+  #
+  # @example Read the configured binary path
+  #   Git.config.binary_path  #=> "git"
+  #
+  # @return [Git::Config] the singleton config object
+  #
   def self.config
-    Base.config
+    Git::Config.instance
   end
 
+  # @deprecated Mixing in the `Git` module is deprecated and will be removed in v6.0.0.
+  #   Use `Git.global_config(...)` instead.
   def global_config(name = nil, value = nil)
-    self.class.global_config(name, value)
+    Git::Deprecation.warn(
+      'Git#global_config is deprecated and will be removed in v6.0.0. ' \
+      'Use Git.global_config(...) instead.'
+    )
+    Git.global_config(name, value)
   end
 
   # Open a bare repository
@@ -105,11 +154,11 @@ module Git # rubocop:disable Style/OneClassPerFile
   #   are logged at the `:info` level.  Additional logging is done at the `:debug`
   #   level.
   #
-  # @return [Git::Base] an object that can execute git commands in the context
+  # @return [Git::Repository] an object that can execute git commands in the context
   #   of the bare repository.
   #
   def self.bare(git_dir, options = {})
-    Base.bare(git_dir, options)
+    Git::Repository.bare(git_dir, options)
   end
 
   # Clone a repository into an empty or newly created directory
@@ -123,9 +172,9 @@ module Git # rubocop:disable Style/OneClassPerFile
   #
   # @param directory [Pathname, nil] The directory to clone into
   #
-  #   If `directory` is a relative directory it is relative to the `path` option if
-  #   given. If `path` is not given, `directory` is relative to the current working
-  #   directory.
+  #   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.
   #
   #   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:
@@ -176,9 +225,14 @@ module Git # rubocop:disable Style/OneClassPerFile
   # @option options [String] :origin Use the value instead `origin` to track
   #   the upstream repository.
   #
-  # @option options [Pathname] :path The directory to clone into.  May be used
-  #   as an alternative to the `directory` parameter.  If specified, the
-  #   `path` option is used instead of the `directory` parameter.
+  # @option options [Pathname] :chdir Run `git clone` from within this directory.
+  #
+  #   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.
+  #
+  # @option options [Pathname] :path Deprecated — use `:chdir` instead.
   #
   # @option options [Boolean] :recursive After the clone is created, initialize
   #   all submodules within, using their default settings.
@@ -191,8 +245,10 @@ module Git # rubocop:disable Style/OneClassPerFile
   #
   # @example Clone into a different directory `my-ruby-git`
   #   git = Git.clone('https://github.com/ruby-git/ruby-git.git', 'my-ruby-git')
-  #   # or:
-  #   git = Git.clone('https://github.com/ruby-git/ruby-git.git', path: 'my-ruby-git')
+  #
+  # @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
   #
   # @example Create a bare repository in the directory `ruby-git.git`
   #   git = Git.clone('https://github.com/ruby-git/ruby-git.git', bare: true)
@@ -216,13 +272,11 @@ module Git # rubocop:disable Style/OneClassPerFile
   #     git_ssh: 'ssh -i /path/to/private_key'
   #   )
   #
-  # @return [Git::Base] an object that can execute git commands in the context
+  # @return [Git::Repository] an object that can execute git commands in the context
   #   of the cloned local working copy or cloned repository.
   #
   def self.clone(repository_url, directory = nil, options = {})
-    clone_to_options = options.slice(:bare, :mirror)
-    directory ||= Git::URL.clone_to(repository_url, **clone_to_options)
-    Base.clone(repository_url, directory, options)
+    Git::Repository.clone(repository_url, directory, options)
   end
 
   # Returns the name of the default branch of the given repository
@@ -263,7 +317,9 @@ module Git # rubocop:disable Style/OneClassPerFile
   # @return [String] the name of the default branch
   #
   def self.default_branch(repository, options = {})
-    Base.repository_default_branch(repository, options)
+    context = Git::ExecutionContext::Global.new(logger: options[:log])
+    output = Git::Commands::LsRemote.new(context).call(repository, 'HEAD', symref: true).stdout
+    Git::Parsers::LsRemote.parse_default_branch(output)
   end
 
   # Export the current HEAD (or a branch, if <tt>options[:branch]</tt>
@@ -287,17 +343,7 @@ module Git # rubocop:disable Style/OneClassPerFile
   # g.config('user.name')  # returns 'Scott Chacon'
   # g.config # returns whole config hash
   def self.global_config(name = nil, value = nil)
-    lib = Git::Lib.new(nil, nil)
-    if name && value
-      # set value
-      lib.global_config_set(name, value)
-    elsif name
-      # return value
-      lib.global_config_get(name)
-    else
-      # return hash
-      lib.global_config_list
-    end
+    run_config_utility(name, value, global: true)
   end
 
   # Create an empty Git repository or reinitialize an existing Git repository
@@ -329,17 +375,23 @@ module Git # rubocop:disable Style/OneClassPerFile
   #   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
   #
   #   - 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, :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`.
+  #
   # @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.
   #
-  # @return [Git::Base] an object that can execute git commands in the context
+  # @return [Git::Repository] an object that can execute git commands in the context
   #   of the newly initialized repository
   #
   # @example Initialize a repository in the current directory
@@ -357,9 +409,24 @@ module Git # rubocop:disable Style/OneClassPerFile
   # @see https://git-scm.com/docs/git-init git init
   #
   def self.init(directory = '.', options = {})
-    Base.init(directory, options)
+    Git::Repository.init(directory, options)
   end
 
+  # Option keys accepted by {.ls_remote}
+  #
+  # Parser-incompatible options such as `:get_url` and `:symref` are intentionally
+  # excluded because {Git::Parsers::LsRemote.parse_output} cannot handle the
+  # non-standard output formats those flags produce.
+  #
+  # @return [Array<Symbol>]
+  #
+  # @api private
+  #
+  LS_REMOTE_ALLOWED_OPTS = %i[
+    branches b heads h tags t refs upload_pack quiet q exit_code sort server_option o timeout
+  ].freeze
+  private_constant :LS_REMOTE_ALLOWED_OPTS
+
   # returns a Hash containing information about the references
   # of the target repository
   #
@@ -369,7 +436,15 @@ module Git # rubocop:disable Style/OneClassPerFile
   # @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 = {})
-    Git::Lib.new.ls_remote(location, 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
@@ -419,21 +494,145 @@ module Git # rubocop:disable Style/OneClassPerFile
   #   commands are logged at the `:info` level.  Additional logging is done
   #   at the `:debug` level.
   #
-  # @return [Git::Base] an object that can execute git commands in the context
+  # @return [Git::Repository] an object that can execute git commands in the context
   #   of the opened working copy
   #
   def self.open(working_dir, options = {})
-    Base.open(working_dir, options)
+    Git::Repository.open(working_dir, options)
+  end
+
+  # Thread-safe cache for git versions, keyed by binary path.
+  @git_version_cache_mutex = Mutex.new
+  @git_version_cache = {}
+
+  # @api private
+  def self.cached_git_version(binary_path, &block)
+    @git_version_cache_mutex.synchronize do
+      @git_version_cache[binary_path] ||= block.call
+    end
+  end
+
+  # @api private
+  def self.clear_git_version_cache
+    @git_version_cache_mutex.synchronize do
+      @git_version_cache.clear
+    end
+  end
+
+  # Return the version of a git binary as a {Git::Version}
+  #
+  # @example Default binary
+  #   Git.git_version #=> #<Git::Version 2.42.0>
+  #
+  # @example Explicit binary path
+  #   Git.git_version('/opt/homebrew/bin/git') #=> #<Git::Version 2.42.0>
+  #
+  # @param binary_path [String, nil] path to the git binary; defaults to
+  #   `Git::Config.instance.binary_path`
+  #
+  # @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
+  #
+  def self.git_version(binary_path = nil)
+    path = binary_path || Git::Config.instance.binary_path
+    cached_git_version(path) { run_git_version(path) }
+  end
+
+  # @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
+
+  # @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
+
+    output = Git::Commands::ConfigOptionSyntax::List.new(context).call(**options).stdout
+    parse_config_list(output.split("\n"))
+  end
+  private_class_method :run_config_utility
+
+  def self.run_config_get(context, name, options)
+    result = Git::Commands::ConfigOptionSyntax::Get.new(context).call(name, **options)
+    raise Git::FailedError, result if result.status.exitstatus != 0
+
+    result.stdout
+  end
+  private_class_method :run_config_get
+
+  # @api private
+  def self.parse_config_list(lines)
+    lines.each_with_object({}) do |line, hsh|
+      key, value = line.split('=', 2)
+      hsh[key] = value || ''
+    end
   end
+  private_class_method :parse_config_list
+
+  # @api private
+  def self.execution_context
+    Git::ExecutionContext::Global.new
+  end
+  private_class_method :execution_context
+
+  # Scopes that require an active repository and cannot be used at the Git module level
+  #
+  # @api private
+  #
+  REPOSITORY_SPECIFIC_SCOPES = %i[local worktree blob].freeze
+  private_constant :REPOSITORY_SPECIFIC_SCOPES
+
+  # Raises +ArgumentError+ when a repository-specific scope is requested.
+  #
+  # The +:local+, +:worktree+, and +:blob+ scopes require an active git
+  # repository and are therefore not valid at the Git module level.
+  #
+  # @api private
+  #
+  def self.assert_valid_scope!(**opts)
+    invalid = REPOSITORY_SPECIFIC_SCOPES.select { |s| opts[s] }
+    return if invalid.empty?
+
+    raise ArgumentError, "#{invalid.join(', ')} scope requires a repository"
+  end
+  private_class_method :assert_valid_scope!
 
   # Return the version of the git binary
   #
-  # @example
-  #  Git.binary_version # => [2, 46, 0]
+  # @example Basic usage
+  #   Git.binary_version  # => [2, 46, 0]
+  #
+  # @param binary_path [String, nil] path to the git binary; defaults to
+  #   `Git::Config.instance.binary_path`
   #
   # @return [Array<Integer>] the version of the git binary
   #
-  def self.binary_version(binary_path = Git::Base.config.binary_path)
-    Base.binary_version(binary_path)
+  # @deprecated Use {Git.git_version} instead, which returns a
+  #   {Git::Version} (not an Array)
+  #
+  #   For the legacy array shape, call: `Git.git_version.to_a`.
+  #   The optional binary_path argument is preserved:
+  #   `Git.git_version(binary_path)`.
+  #
+  def self.binary_version(binary_path = nil)
+    binary_path ||= Git::Config.instance.binary_path
+    Git::Deprecation.warn(
+      'Git.binary_version is deprecated and will be removed in 6.0. ' \
+      'Use Git.git_version instead, which returns a Git::Version ' \
+      '(not an Array). For the legacy array shape, call: Git.git_version.to_a. ' \
+      'The optional binary_path argument is preserved: Git.git_version(binary_path).'
+    )
+    git_version(binary_path).to_a
   end
 end

data/redesign/1_architecture_existing.md

@@ -1,6 +1,9 @@
 # Analysis of the Current Git Gem Architecture and Its Challenges
 
-This document provides an in-depth look at the current architecture of the `git` gem, outlining its primary components and the design challenges that have emerged over time. Understanding these challenges is the key motivation for the proposed architectural redesign.
+This document provides an in-depth look at the current architecture of the `git` gem,
+outlining its primary components and the design challenges that have emerged over
+time. Understanding these challenges is the key motivation for the proposed
+architectural redesign.
 
 - [1. Overview of the Current Architecture](#1-overview-of-the-current-architecture)
 - [2. Key Architectural Challenges](#2-key-architectural-challenges)
@@ -11,27 +14,43 @@ This document provides an in-depth look at the current architecture of the `git`
 
 ## 1. Overview of the Current Architecture
 
-The gem's current design is centered around three main classes: `Git`, `Git::Base`, and `Git::Lib`.
+The gem's current design is centered around three main classes: `Git`, `Git::Base`,
+and `Git::Lib`.
 
-- **`Git` (Top-Level Module)**: This module serves as the primary public entry point for creating repository objects. It contains class-level factory methods like `Git.open`, `Git.clone`, and `Git.init`. It also provides an interface for accessing global git configuration settings.
+- **`Git` (Top-Level Module)**: This module serves as the primary public entry point
+  for creating repository objects. It contains class-level factory methods like
+  `Git.open`, `Git.clone`, and `Git.init`. It also provides an interface for
+  accessing global git configuration settings.
 
-**`Git::Base`**: This is the main object that users interact with after creating or opening a repository. It holds the high-level public API for most git operations (e.g., `g.commit`, `g.add`, `g.status`). It is responsible for managing the repository's state, such as the paths to the working directory and the `.git` directory.
+- **`Git::Base`**: This is the main object that users interact with after creating or
+  opening a repository. It holds the high-level public API for most git operations
+  (e.g., `g.commit`, `g.add`, `g.status`). It is responsible for managing the
+  repository's state, such as the paths to the working directory and the `.git`
+  directory.
 
-**`Git::Lib`**: This class is intended to be the low-level wrapper around the `git` command-line tool. It contains the methods that build the specific command-line arguments and execute the `git` binary. In practice, it also contains a significant amount of logic for parsing the output of these commands.
+- **`Git::Lib`**: This class is intended to be the low-level wrapper around the `git`
+  command-line tool. It contains the methods that build the specific command-line
+  arguments and execute the `git` binary. In practice, it also contains a significant
+  amount of logic for parsing the output of these commands.
 
 ## 2. Key Architectural Challenges
 
-While this structure has been functional, several significant design challenges make the codebase difficult to maintain, test, and evolve.
+While this structure has been functional, several significant design challenges make
+the codebase difficult to maintain, test, and evolve.
 
 ### A. Unclear Separation of Concerns
 
-The responsibilities between Git::Base and Git::Lib are "muddy" and overlap significantly.
+The responsibilities between Git::Base and Git::Lib are "muddy" and overlap
+significantly.
 
 - `Git::Base` sometimes contains logic that feels like it should be lower-level.
 
-- `Git::Lib`, which should ideally only be concerned with command execution, is filled with high-level logic for parsing command output into specific Ruby objects (e.g., parsing log output, diff stats, and branch lists).
+- `Git::Lib`, which should ideally only be concerned with command execution, is
+  filled with high-level logic for parsing command output into specific Ruby objects
+  (e.g., parsing log output, diff stats, and branch lists).
 
-This blending of responsibilities makes it hard to determine where a specific piece of logic should reside, leading to an inconsistent and confusing internal structure.
+This blending of responsibilities makes it hard to determine where a specific piece
+of logic should reside, leading to an inconsistent and confusing internal structure.
 
 ### B. Circular Dependency
 
@@ -39,28 +58,45 @@ This is the most critical architectural flaw in the current design.
 
 - A `Git::Base` instance is created.
 
-- The first time a command is run, `Git::Base` lazily initializes a `Git::Lib` instance via its `.lib` accessor method.
+- The first time a command is run, `Git::Base` lazily initializes a `Git::Lib`
+  instance via its `.lib` accessor method.
 
-- The `Git::Lib` constructor is passed the `Git::Base` instance (`self`) so that it can read the repository's path configuration back from the object that is creating it.
+- The `Git::Lib` constructor is passed the `Git::Base` instance (`self`) so that it
+  can read the repository's path configuration back from the object that is creating
+  it.
 
-This creates a tight, circular coupling: `Git::Base` depends on `Git::Lib` to execute commands, but `Git::Lib` depends on `Git::Base` for its own configuration. This pattern makes the classes difficula to instantiate or test in isolation and creates a fragile system where changes in one class can have unexpected side effects in the other.
+This creates a tight, circular coupling: `Git::Base` depends on `Git::Lib` to execute
+commands, but `Git::Lib` depends on `Git::Base` for its own configuration. This
+pattern makes the classes difficult to instantiate or test in isolation and creates a
+fragile system where changes in one class can have unexpected side effects in the
+other.
 
 ### C. Undefined Public API Boundary
 
-The gem lacks a formally defined public interface. Because `Git::Base` exposes its internal `Git::Lib` instance via the public `g.lib` accessor, many users have come to rely on `Git::Lib` and its methods as if they were part of the public API.
+The gem lacks a formally defined public interface. Because `Git::Base` exposes its
+internal `Git::Lib` instance via the public `g.lib` accessor, many users have come to
+rely on `Git::Lib` and its methods as if they were part of the public API.
 
 This has two negative consequences:
 
-1. It prevents the gem's maintainers from refactoring or changing the internal implementation of `Git::Lib` without causing breaking changes for users.
+1. It prevents the gem's maintainers from refactoring or changing the internal
+   implementation of `Git::Lib` without causing breaking changes for users.
 
-2. It exposes complex, internal methods to users, creating a confusing and inconsistent user experience.
+2. It exposes complex, internal methods to users, creating a confusing and
+   inconsistent user experience.
 
 ### D. Slow and Brittle Test Suite
 
 The current testing strategy, built on `TestUnit`, suffers from two major issues:
 
-- **Over-reliance on Fixtures**: Most tests depend on having a complete, physical git repository on the filesystem to run against. Managing these fixtures is cumbersome.
+- **Over-reliance on Fixtures**: Most tests depend on having a complete, physical git
+  repository on the filesystem to run against. Managing these fixtures is cumbersome.
 
-- **Excessive Shelling Out**: Because the logic for command execution and output parsing are tightly coupled, nearly every test must shell out to the actual `git` command-line tool.
+- **Excessive Shelling Out**: Because the logic for command execution and output
+  parsing are tightly coupled, nearly every test must shell out to the actual `git`
+  command-line tool.
 
-This makes the test suite extremely slow, especially on non-UNIX platforms like Windows where process creation is more expensive. The slow feedback loop discourages frequent testing and makes development more difficult. The brittleness of filesystem-dependent tests also leads to flickering or unreliable test runs.
+This makes the test suite extremely slow, especially on non-UNIX platforms like
+Windows where process creation is more expensive. The slow feedback loop discourages
+frequent testing and makes development more difficult. The brittleness of
+filesystem-dependent tests also leads to flickering or unreliable test runs.