git 4.4.5 → 5.0.0.beta.1

data/lib/git.rb

@@ -1,57 +1,63 @@
 # frozen_string_literal: true
 
+require 'active_support'
 require 'active_support/deprecation'
 
-# 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.
-#
+require 'git/version'
+
 module Git
-  # The deprecation instance used to emit deprecation warnings for the Git gem
-  #
-  # @api public
   Deprecation = ActiveSupport::Deprecation.new('5.0.0', 'Git')
 
-  if (behavior = ENV.fetch('GIT_DEPRECATION_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
+  # 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 'git/commands/init'
 require 'git/config'
 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/file_ref'
 require 'git/fsck_object'
 require 'git/fsck_result'
-require 'git/index'
+require 'git/version_constraint'
 require 'git/lib'
 require 'git/log'
 require 'git/object'
-require 'git/path'
 require 'git/remote'
 require 'git/repository'
+require 'git/base'
 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'
 
@@ -62,29 +68,13 @@ require 'git/worktrees'
 #
 # @author Scott Chacon (mailto:schacon@gmail.com)
 #
-module Git # rubocop:disable Style/OneClassPerFile
-  # Internal alias for Git::Lib, used by the gem itself after the public constant
-  # is deprecated. Code outside the gem should not reference this constant.
-  # @api private
-  LibImpl = remove_const(:Lib)
-
-  # @api private
-  def self.const_missing(name)
-    return super unless name == :Lib
-
-    Git::Deprecation.warn(
-      'Git::Lib is deprecated and will be removed in version 5.x. ' \
-      'Use the #lib accessor on the object returned by Git.init, Git.open, or Git.clone instead.'
-    )
-    const_set(:Lib, LibImpl)
-  end
-
+module Git
   # 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 config(name = nil, value = nil)
-    lib = LibImpl.new
+    lib = Git::Lib.new
     if name && value
       # set value
       lib.config_set(name, value)
@@ -158,9 +148,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:
@@ -211,9 +201,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.
@@ -226,8 +221,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)
@@ -255,8 +252,6 @@ module Git # rubocop:disable Style/OneClassPerFile
   #   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)
   end
 
@@ -308,22 +303,10 @@ module Git # rubocop:disable Style/OneClassPerFile
   # 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.'
-  #
-  # <tt>options[:branch]</tt> is the short name of the ref: a branch name such as
-  # 'main' or a tag name such as 'v1.0.0'. A full ref path such as
-  # 'refs/tags/v1.0.0' or a commit SHA is not accepted.
-  #
-  # Removing +.git+ is not atomic. If it fails, the exported files are complete and
-  # usable, but the directory keeps whatever part of +.git+ could not be deleted.
-  # Nothing is cleaned up, because the exported files are the deliverable and the
-  # leftover has to be removed by hand once the cause of the failure is fixed.
-  #
-  # @raise [SystemCallError] if the +.git+ directory cannot be removed. The exported
-  #   files are left in place, and the directory keeps whatever part of +.git+ could
-  #   not be deleted.
   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
 
@@ -334,7 +317,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 = LibImpl.new(nil, nil)
+    lib = Git::Lib.new(nil, nil)
     if name && value
       # set value
       lib.global_config_set(name, value)
@@ -376,6 +359,8 @@ 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 = ... }).
@@ -404,7 +389,30 @@ 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)
+    require_relative 'git/commands/init'
+
+    options = options.dup
+    options[:repository] ||= options.delete(:separate_git_dir)
+    init_opts = options.slice(:bare, :initial_branch)
+    init_opts[:separate_git_dir] = options[:repository] if options.key?(:repository)
+    Git::Commands::Init.new(Git::Lib.new(nil, options[:log])).call(directory, **init_opts)
+
+    open_initialized_repository(directory, options)
+  end
+
+  # Open the repository after initialization
+  #
+  # @param directory [String] the directory containing the repository
+  # @param options [Hash] the options hash
+  # @return [Git::Base] the opened repository
+  # @api private
+  #
+  private_class_method def self.open_initialized_repository(directory, options)
+    if options[:bare]
+      Git.bare(options[:repository] || directory, options.slice(:log, :git_ssh).compact)
+    else
+      Git.open(directory, options.slice(:log, :git_ssh, :index, :repository).compact)
+    end
   end
 
   # returns a Hash containing information about the references
@@ -416,7 +424,7 @@ 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 = {})
-    LibImpl.new.ls_remote(location, options)
+    Git::Lib.new.ls_remote(location, options)
   end
 
   # Open a an existing Git working directory
@@ -473,6 +481,37 @@ module Git # rubocop:disable Style/OneClassPerFile
     Base.open(working_dir, options)
   end
 
+  # Return the version of a git binary as a {Git::Version}
+  #
+  # @param binary_path [String, nil] path to the git binary; defaults to
+  #   `Git::Base.config.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
+  #
+  # @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>
+  #
+  def self.git_version(binary_path = nil)
+    path = binary_path || Git::Base.config.binary_path
+    Git::Lib.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
+
   # Return the version of the git binary
   #
   # @example
@@ -480,7 +519,17 @@ module Git # rubocop:disable Style/OneClassPerFile
   #
   # @return [Array<Integer>] the version of the git binary
   #
+  # @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 = Git::Base.config.binary_path)
-    Base.binary_version(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.