git 5.0.0.beta.1 → 5.0.0.beta.3

data/UPGRADING.md

@@ -0,0 +1,141 @@
+# Upgrading the `git` Gem
+
+> **⚠️ Work in progress — v5.0.0 is currently in beta.**
+> This document is updated incrementally as development continues and is not yet
+> complete. If you encounter a compatibility problem not covered here, please
+> [open an issue](https://github.com/ruby-git/ruby-git/issues).
+
+- [Upgrading from v4.x to v5.x](#upgrading-from-v4x-to-v5x)
+  - [Overview](#overview)
+  - [`Git::Lib` removal](#gitlib-removal)
+    - [Methods with a direct replacement](#methods-with-a-direct-replacement)
+    - [Methods with no replacement](#methods-with-no-replacement)
+    - [Internal plumbing methods (no replacement)](#internal-plumbing-methods-no-replacement)
+  - [Deprecated methods](#deprecated-methods)
+
+## Upgrading from v4.x to v5.x
+
+### Overview
+
+The primary goal of v5.0.0 is to move everyone onto a new internal architecture
+while keeping the existing v4.x API working. The vast majority of v4.x code
+requires no changes to run on v5.x.
+
+The new architecture delivered in v5.0.0 is the foundation for future API
+improvements across upcoming major releases.
+
+The new architecture introduces a layered design (`Git::Commands`, `Git::Repository`,
+and associated parsers). Compatibility shims — deprecated forwarding methods that map
+old call patterns to the new API — ensure that v4.x code continues to work. These
+shims emit deprecation warnings that tell you exactly what to change and what will be
+eliminated in a future major release (most likely v6.0.0).
+
+Hard breaks are limited to a small number of methods that had no safe
+migration path — these are described in detail below.
+
+Our intent is to make upgrading to v5.x as smooth as possible. For information
+on how to suppress or configure deprecation warnings, see the
+[Deprecations](README.md#deprecations) section of the README.
+
+---
+
+### `Git::Lib` removal
+
+The object returned by `Git.open`, `Git.clone`, and `Git.init` — the object
+you call methods on to interact with your repository — inadvertently exposed
+a `#lib` method that gave access to `Git::Lib`, the gem's internal
+implementation class. This was never intended to be public; it was an
+implementation detail that leaked out. `Git::Lib` is removed in v5.0.0.
+
+Calling `#lib` on the repository object returns `self` with a deprecation
+warning so that existing `g.lib.*` call chains continue to work during
+migration. The `#lib` method itself is removed in v6.0.0. Calls to methods
+that have no replacement (see below) raise `NoMethodError` with an
+informative message.
+
+Most public behavior previously accessible via `g.lib.*` is available
+directly on the repository object (i.e., `g.*`). A small number of methods
+have no replacement — see below. The sections below list every affected method.
+
+#### Methods with a direct replacement
+
+All of the following `g.lib.*` calls work in v5.x but emit a deprecation
+warning. Migrate to the replacement shown to silence the `g.lib.*` deprecation
+warning; note that some replacements are themselves deprecated — see the table
+notes for the final migration target.
+
+| Deprecated call (works in v5.x, removed in v6.0.0) | Replacement |
+|---------------------------------------------------|-------------|
+| `g.lib.config_get(name)` | `g.config(name)` |
+| `g.lib.config_list` | `g.config` |
+| `g.lib.config_set(name, value)` | `g.config(name, value)` |
+| `g.lib.git_version` | `g.git_version` |
+| `g.lib.global_config_get(name)` | `g.global_config(name)` |
+| `g.lib.global_config_list` | `g.global_config` |
+| `g.lib.global_config_set(name, value)` | `g.global_config(name, value)` |
+| `g.lib.parse_config(file)` | `g.config(file: file)` |
+| `g.lib.stash_list` | `g.stash_list` *(also deprecated — use `g.stashes_all`)* |
+| `g.lib.unmerged` | `g.unmerged` |
+| `g.lib.change_head_branch(name)` | `g.change_head_branch(name)` |
+| `g.lib.branch_current` | `g.current_branch` |
+| `g.lib.ls_remote(location, opts)` | `g.ls_remote(location, opts)` |
+| `g.lib.current_branch_state` | `g.current_branch_state` |
+
+> **Note — `current_branch_state` return type change:** `g.lib.current_branch_state`
+> returned a `Git::Lib::HeadState` (a mutable `Struct`). `g.current_branch_state`
+> returns a `Git::Repository::Branching::HeadState` (an immutable `Data` object).
+> Both expose `.state` (`:active`, `:unborn`, or `:detached`) and `.name`. If your
+> code relies on the struct being mutable or uses positional construction
+> (`Git::Lib::HeadState.new(:active, 'main')`), update to keyword construction:
+> `Git::Repository::Branching::HeadState.new(state: :active, name: 'main')`.
+
+#### Methods with no replacement
+
+| v4.x call | Notes |
+|-----------|-------|
+| `g.lib.list_files(ref_dir)` | Walked `.git/refs/` directly. Use `g.branches`, `g.tags`, or `g.remotes` instead. |
+
+#### Internal plumbing methods (no replacement)
+
+The following methods were technically public on `Git::Lib` but are internal
+helpers with no plausible external use. They have no replacement in v5.0.0:
+
+- `assert_args_are_not_options`
+- `assert_valid_opts`
+- `cat_file_object_meta`
+- `command_capturing`
+- `command_streaming`
+- `each_cat_file_header`
+- `handle_deprecated_path_option`
+- `normalize_pathspecs`
+- `parse_cat_file_meta`
+- `parse_config_list`
+- `process_commit_data`
+- `validate_pathspec_types`
+
+---
+
+### Deprecated methods
+
+The following methods are available in v5.x with deprecation warnings and
+are removed in v6.0.0.
+
+| Deprecated call (works in v5.x, removed in v6.0.0) | Replacement |
+|---------------------------------------------------|-------------|
+| `g.config_get(name)` | `g.config(name)` |
+| `g.config_list` | `g.config` |
+| `g.config_set(name, value)` | `g.config(name, value)` |
+| `g.global_config_get(name)` | `g.global_config(name)` |
+| `g.global_config_list` | `g.global_config` |
+| `g.global_config_set(name, value)` | `g.global_config(name, value)` |
+| `g.parse_config(file)` | `g.config(file: file)` |
+| `g.stash_list` | `g.stashes_all` |
+| `g.add_remote(name, url, opts)` | `g.remote_add(name, url, opts)` |
+| `g.remove_remote(name)` | `g.remote_remove(name)` |
+| `g.set_remote_url(name, url)` | `g.remote_set_url(name, url)` |
+| `g.add_tag(name, ...)` | `g.tag_add(name, ...)` |
+| `g.delete_tag(name)` | `g.tag_delete(name)` |
+| `include Git; config(...)` | `Git.open(Dir.pwd).config(...)` |
+| `include Git; global_config(...)` | `Git.global_config(...)` |
+
+---

data/git.gemspec

@@ -48,6 +48,11 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'simplecov-rspec', '~> 0.4'
   spec.add_development_dependency 'test-unit', '~> 3.7'
 
+  if RUBY_ENGINE == 'truffleruby' && Gem::Version.new(RUBY_ENGINE_VERSION) < Gem::Version.new('34.0.0')
+    # i18n 1.15+ uses Fiber.[] (Ruby 3.2 Fiber storage) which TruffleRuby < 34.0.0 does not implement
+    spec.add_development_dependency 'i18n', '< 1.15'
+  end
+
   unless RUBY_PLATFORM == 'java' || RUBY_ENGINE == 'truffleruby'
     spec.add_development_dependency 'irb', '~> 1.16'
     spec.add_development_dependency 'redcarpet', '~> 3.6'

data/lib/git/branch.rb

@@ -1,14 +1,13 @@
 # frozen_string_literal: true
 
-require 'git/base'
 require_relative 'branch_info'
 
 module Git
   # Represents a Git branch
   #
   # Branch objects provide access to branch metadata and operations like checkout,
-  # delete, and merge. They should be obtained via {Git::Base#branch} or
-  # {Git::Base#branches}, not constructed directly.
+  # delete, and merge. They should be obtained via {Git::Repository#branch} or
+  # {Git::Repository#branches}, not constructed directly.
   #
   # @example Getting a branch
   #   git = Git.open('.')
@@ -24,7 +23,7 @@ module Git
     # The full refname of this branch
     #
     # For local branches this is the short name (e.g. `'main'`). For
-    # remote-tracking branches obtained via {Git::Base#branches} this includes
+    # remote-tracking branches obtained via {Git::Repository#branches} this includes
     # the `remotes/` prefix (e.g. `'remotes/origin/main'`). Branches constructed
     # by {Git::Remote#branch} use the `<remote>/<branch>` form (e.g.
     # `'origin/main'`) which does **not** populate {#remote}.
@@ -68,17 +67,13 @@ module Git
 
     # Initialize a new Branch object
     #
-    # @param base [Git::Base, Git::Repository] the git repository
-    #
-    #   Accepts either a {Git::Base} (legacy) or a {Git::Repository} (new form).
-    #   The `is_a?(Git::Base)` guard will be removed when {Git::Base} is deleted
-    #   in Phase 4.
+    # @param base [Git::Repository] the git repository
     #
     # @param branch_info_or_name [Git::BranchInfo, String] branch info object or name string
     #
     #   Passing a BranchInfo is preferred; String support is for backward compatibility.
     #
-    # @note Use {Git::Base#branch} or {Git::Base#branches} instead of constructing directly
+    # @note Use {Git::Repository#branch} or {Git::Repository#branches} instead of constructing directly
     #
     # @api private
     #
@@ -151,7 +146,7 @@ module Git
     #
     # @param file [String] path to the destination archive file
     #
-    # @param opts [Hash] archive options (see {Git::Base#archive})
+    # @param opts [Hash] archive options (see {Git::Repository#archive})
     #
     # @return [String] the path to the written archive file
     #
@@ -464,18 +459,12 @@ module Git
       nil
     end
 
-    # Resolves the {Git::Repository} for this branch
-    #
-    # Accepts either a {Git::Repository} (new form) or a {Git::Base} (legacy).
-    # The `is_a?(Git::Base)` guard will be removed when {Git::Base} is deleted
-    # in Phase 4.
-    #
     # @return [Git::Repository]
     #
     # @api private
     #
     def branch_repository
-      @base.is_a?(Git::Base) ? @base.facade_repository : @base
+      @base
     end
   end
 end

data/lib/git/branches.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require 'git/base'
-
 module Git
   # Collection of all Git branches in a repository
   #
@@ -19,7 +17,7 @@ module Git
 
     # Creates a new Branches collection populated from the given repository
     #
-    # @param base [Git::Base, Git::Repository] the repository to enumerate
+    # @param base [Git::Repository] the repository to enumerate
     #   branches from
     #
     # @return [void]
@@ -136,18 +134,12 @@ module Git
 
     private
 
-    # Resolves the {Git::Repository} for this collection of branches
-    #
-    # Accepts either a {Git::Repository} (new form) or a {Git::Base} (legacy).
-    # The `is_a?(Git::Base)` guard will be removed when {Git::Base} is deleted
-    # in Phase 4.
-    #
     # @return [Git::Repository] the repository used to enumerate branches
     #
     # @api private
     #
     def branch_repository
-      @base.is_a?(Git::Base) ? @base.facade_repository : @base
+      @base
     end
 
     # Indexes all supported lookup keys for a branch without mutating

data/lib/git/command_line/base.rb

@@ -156,6 +156,11 @@ module Git
       #
       # @raise [Git::ProcessIOError] in place of ProcessExecuter::ProcessIOError
       #
+      # @raise [Git::ProcessIOError] when a timeout race causes Errno::ESRCH. On Ruby 4.0+,
+      #   `Process.kill` raises `Errno::ESRCH` when the spawned process exits between the
+      #   timeout firing and the kill signal being delivered. This is a race in
+      #   process_executer's timeout handling and is semantically equivalent to a timeout.
+      #
       # @return [Object] the return value of the block
       #
       # @api private
@@ -168,6 +173,11 @@ module Git
         raise Git::Error, e.message, cause: e.cause
       rescue ProcessExecuter::ProcessIOError => e
         raise Git::ProcessIOError, e.message, cause: e.cause
+      rescue Errno::ESRCH => e
+        # Ruby 4.0+: Process.kill raises Errno::ESRCH when the spawned process exits
+        # in the narrow window between the timeout firing and the kill signal being sent.
+        # This is a known race in process_executer's timeout handling.
+        raise Git::ProcessIOError, "Git process no longer exists (timeout race): #{e.message}", cause: e
       end
 
       # Build the git command line from the available sources to send to `Process.spawn`

data/lib/git/command_line/capturing.rb

@@ -9,7 +9,7 @@ module Git
     # {Git::CommandLine::Capturing} is the buffering strategy: it calls
     # `ProcessExecuter.run_with_capture`, which reads all subprocess output into
     # `String` objects before returning.  Use this class (via
-    # {Git::Lib#command_capturing}) for the vast majority of git subcommands whose
+    # {Git::ExecutionContext#command_capturing}) for the vast majority of git subcommands whose
     # output fits comfortably in memory.
     #
     # {Git::CommandLine::Streaming} is the complementary strategy for commands
@@ -23,7 +23,7 @@ module Git
     #   result.stdout   # => "abc1234 Initial commit\n..."
     #   result.stderr   # => ""
     #
-    # @see Git::Lib#command_capturing
+    # @see Git::ExecutionContext#command_capturing
     #
     # @see Git::CommandLine::Streaming
     #
@@ -149,7 +149,9 @@ module Git
       # @raise [Git::FailedError] if the command returned a non-zero exit status
       #
       # @raise [Git::ProcessIOError] if an exception was raised while collecting
-      #   subprocess output
+      #   subprocess output, or (Ruby 4.0+) if a timeout-handling race causes
+      #   `Errno::ESRCH` when the spawned process exits between the timeout
+      #   firing and the kill signal being delivered
       #
       # @raise [Git::TimeoutError] if the command times out
       #

data/lib/git/command_line/streaming.rb

@@ -12,7 +12,7 @@ module Git
     # IO object.  Stderr is always captured internally in a `StringIO` for error
     # diagnostics and is available as `result.stderr`.
     #
-    # Use this class (via {Git::Lib#command_streaming}) for commands such as
+    # Use this class (via {Git::ExecutionContext#command_streaming}) for commands such as
     # `cat-file -p <blob>` whose stdout may be too large to buffer in memory.
     #
     # {Git::CommandLine::Capturing} is the complementary strategy for the common case
@@ -26,7 +26,7 @@ module Git
     #     streaming.run('cat-file', 'blob', sha, out: f)
     #   end
     #
-    # @see Git::Lib#command_streaming
+    # @see Git::ExecutionContext#command_streaming
     #
     # @see Git::CommandLine::Capturing
     #
@@ -102,7 +102,9 @@ module Git
       # @raise [Git::FailedError] if the command returned a non-zero exit status
       #
       # @raise [Git::ProcessIOError] if an exception was raised while collecting
-      #   subprocess output
+      #   subprocess output, or (Ruby 4.0+) if a timeout-handling race causes
+      #   `Errno::ESRCH` when the spawned process exits between the timeout
+      #   firing and the kill signal being delivered
       #
       # @raise [Git::TimeoutError] if the command times out
       #

data/lib/git/command_line.rb

@@ -14,9 +14,9 @@ module Git
   #   Use this for commands (e.g. `cat-file -p <blob>`) whose output may be
   #   too large to buffer.
   #
-  # Both classes inherit from {Git::CommandLine::Base} and are instantiated
-  # via factory helpers in {Git::Lib}: {Git::Lib#command_capturing} and
-  # {Git::Lib#command_streaming}.
+  # Both classes inherit from {Git::CommandLine::Base} and are used internally
+  # by {Git::ExecutionContext#command_capturing} and
+  # {Git::ExecutionContext#command_streaming}.
   #
   # Results are returned as {Git::CommandLine::Result} objects (also accessible
   # as {Git::CommandLineResult} for backward compatibility).

data/lib/git/commands/base.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'git/commands/arguments'
+require 'git/version_constraint'
 
 module Git
   module Commands
@@ -173,8 +174,8 @@ module Git
         end
       end
 
-      # @param execution_context [Git::ExecutionContext, Git::Lib] context that provides
-      #   {Git::Lib#command_capturing} and {Git::Lib#command_streaming}
+      # @param execution_context [Git::ExecutionContext] context that provides
+      #   {Git::ExecutionContext#command_capturing} and {Git::ExecutionContext#command_streaming}
       def initialize(execution_context)
         @execution_context = execution_context
       end
@@ -210,7 +211,7 @@ module Git
       # @raise [Git::VersionError] if the installed git version doesn't meet requirements
       def call(*, **)
         bound = args_definition.bind(*, **)
-        validate_version!
+        validate_version!(bound.execution_options)
         result = execute_command(bound)
         validate_exit_status!(result)
         result
@@ -312,10 +313,10 @@ module Git
       #
       # Floor check always runs first and fails fast.
       #
-      def validate_version!
+      def validate_version!(exec_opts = {})
         return if self.class.skip_version_validation?
 
-        actual_version = @execution_context.git_version
+        actual_version = @execution_context.git_version(timeout: exec_opts[:timeout])
 
         # Floor check: fail-fast if git is too old for the gem itself
         validate_floor_version!(actual_version)
@@ -351,7 +352,7 @@ module Git
       # the read end. The write and close happen concurrently with the block.
       #
       # The read end can be passed as the `in:` keyword to
-      # {Git::Lib#command_capturing} / {Git::CommandLine#run_with_capture}, connecting it directly to
+      # {Git::ExecutionContext#command_capturing} / {Git::CommandLine#run_with_capture}, connecting it directly to
       # the spawned git process's stdin without an intermediate file or shell
       # heredoc. This is required because `Process.spawn` only accepts real IO
       # objects with a file descriptor — `StringIO` does not work.

data/lib/git/commands/cat_file/batch.rb

@@ -103,6 +103,9 @@ module Git
           # When provided, {#call} dispatches to the streaming execution path.
           execution_option :out
 
+          # Abort the command after this many seconds.
+          execution_option :timeout
+
           # Object names (or batch-command lines) are written to stdin, not argv.
           # Using skip_cli: true because these values are fed via stdin — git never
           # sees them as CLI arguments so Ruby must enforce the cross-argument
@@ -302,6 +305,8 @@ module Git
         #   @option options [#write, nil] :out (nil) stream stdout to this IO object
         #     instead of buffering in memory; when given, `result.stdout` will be `''`
         #
+        #   @option options [Numeric, nil] :timeout (nil) abort the command after this many seconds
+        #
         #   @return [Git::CommandLineResult] the result of calling `git cat-file`
         #
         #     Stdout contains one metadata line per object (or `''` when `out:` is given)
@@ -311,7 +316,7 @@ module Git
         #   @raise [Git::FailedError] if git exits non-zero
         def call(*objects, **)
           bound = args_definition.bind(*objects, **)
-          validate_version!
+          validate_version!(bound.execution_options)
           # `-Z` puts git into NUL I/O mode: input objects must be NUL-terminated.
           # Without `-Z`, the standard newline delimiter is used.
           delimiter = bound.Z? ? "\0" : "\n"

data/lib/git/commands/cat_file/raw.rb

@@ -62,6 +62,9 @@ module Git
           # When provided, {#call} dispatches to the streaming execution path.
           execution_option :out
 
+          # Abort the command after this many seconds.
+          execution_option :timeout
+
           end_of_options
 
           # Expected object type — one of `commit`, `tree`, `blob`, or `tag`.
@@ -191,9 +194,12 @@ module Git
         #
         #   @raise [Git::FailedError] if the object does not exist or is not of the
         #     given type
+        #
+        #   @option options [Numeric, nil] :timeout (nil) abort the command after this many seconds
+        #
         def call(*, **)
           bound = args_definition.bind(*, **)
-          validate_version!
+          validate_version!(bound.execution_options)
           result = execute_command(bound)
 
           # `-e` treats exit 1 as a meaningful result (object not found), but any other

data/lib/git/commands/config_option_syntax/get_urlmatch.rb

@@ -45,6 +45,9 @@ module Git
           # General read options
           flag_option :includes, negatable: true
 
+          # Output modifiers
+          flag_option :show_scope
+
           # Operands
           end_of_options
           operand :name, required: true
@@ -91,6 +94,8 @@ module Git
         #     @option options [Boolean, nil] :no_includes (nil) disable include directives
         #       in config files (`--no-includes`)
         #
+        #     @option options [Boolean, nil] :show_scope (nil) show the scope of each config entry
+        #
         #     @return [Git::CommandLineResult] the result of calling `git config --get-urlmatch`
         #
         #     @raise [ArgumentError] if unsupported options are provided

data/lib/git/commands/show_ref/exclude_existing.rb

@@ -86,7 +86,7 @@ module Git
           end
 
           bound = args_definition.bind(*, exclude_existing: exclude_existing, **)
-          validate_version!
+          validate_version!(bound.execution_options)
           stdin = Array(bound.ref).map { |r| "#{r}\n" }.join
           with_stdin(stdin) { |reader| run_filter(bound, reader) }
         end

data/lib/git/commands/update_ref/batch.rb

@@ -118,7 +118,7 @@ module Git
         #   @raise [Git::FailedError] if git exits with a non-zero exit status
         def call(*, **)
           bound = args_definition.bind(*, **)
-          validate_version!
+          validate_version!(bound.execution_options)
           with_stdin(build_stdin(bound)) do |reader|
             result = @execution_context.command_capturing(
               *bound, in: reader, **bound.execution_options, raise_on_failure: false

data/lib/git/commands/version.rb

@@ -28,6 +28,7 @@ module Git
       skip_version_validation
 
       arguments do
+        execution_option :timeout
         literal 'version'
         flag_option :build_options
       end
@@ -42,6 +43,10 @@ module Git
       #
       #     @option options [Boolean, nil] :build_options (nil) include build options in the output
       #
+      #     @option options [Numeric, nil] :timeout (nil) the number of seconds to wait
+      #       for the command to complete; if nil, uses the global timeout from
+      #       {Git::Config}; if 0, no timeout is enforced
+      #
       #     @return [Git::CommandLineResult] the result of calling `git version`
       #
       #     @raise [ArgumentError] if unsupported options are provided

data/lib/git/commands.rb

@@ -61,19 +61,17 @@ module Git
   # {Git::CommandLine}, and return a raw {Git::CommandLineResult}.
   #
   # Commands do **not** parse output — that responsibility belongs to the
-  # {Git::Parsers} layer, orchestrated by the facade ({Git::Lib} / future
-  # {Git::Repository}).
+  # {Git::Parsers} layer, orchestrated by the facade ({Git::Repository}).
   #
   # All classes in this namespace are internal (`@api private`). End users
-  # should interact with the public API on {Git::Base} instead.
+  # should interact with the public API on {Git::Repository} instead.
   #
   # ## Architecture
   #
   # ```
-  # Git::Base (public API)
-  #   └── Git::Lib / Git::Repository (facade — orchestrates commands + parsers)
-  #         └── Git::Commands::* (defines CLI API, binds args, executes)
-  #               └── Git::CommandLine (subprocess execution)
+  # Git::Repository (public API / facade — orchestrates commands + parsers)
+  #   └── Git::Commands::* (defines CLI API, binds args, executes)
+  #         └── Git::CommandLine (subprocess execution)
   # ```
   #
   # Simple commands inherit from {Commands::Base} and only need an `arguments`

data/lib/git/config.rb

@@ -3,6 +3,23 @@
 module Git
   # The global configuration for this gem
   class Config
+    # Returns the process-wide singleton {Git::Config} instance
+    #
+    # All calls to {Git.configure}, {Git.config}, and the {Git::ExecutionContext}
+    # classes resolve global configuration through this method.
+    #
+    # @example Read the configured binary path
+    #   Git::Config.instance.binary_path  #=> "git"
+    #
+    # @example Mutate the singleton (same as Git.configure { |c| ... })
+    #   Git::Config.instance.binary_path = '/usr/local/bin/git'
+    #
+    # @return [Git::Config] the singleton config object
+    #
+    def self.instance
+      @instance ||= new
+    end
+
     attr_writer :binary_path, :git_ssh, :timeout
 
     def initialize