git 5.0.0.beta.1 → 5.0.0.beta.2

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

data/lib/git/config_entry_info.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Git
+  # Represents a single Git configuration entry
+  #
+  # Returned by {Git::Configuring} read operations such as {Git::Configuring#config_get},
+  # {Git::Configuring#config_get_all}, {Git::Configuring#config_list}, and their
+  # related methods.
+  #
+  # @example Create a ConfigEntryInfo
+  #   entry = Git::ConfigEntryInfo.new(
+  #     scope: 'local',
+  #     origin: 'file:.git/config',
+  #     key: 'remote.origin.url',
+  #     value: 'https://github.com/ruby-git/ruby-git'
+  #   )
+  #   entry.section    # => "remote"
+  #   entry.subsection # => "origin"
+  #   entry.variable   # => "url"
+  #
+  # @api public
+  #
+  # @!attribute [r] scope
+  #
+  #   The scope of the configuration entry
+  #
+  #   May be one of `"system"`, `"global"`, `"local"`, `"worktree"`, `"command"`,
+  #   `"file"`, or `"blob"`. The `"command"` scope is used for values supplied
+  #   via the command line (including default values from `--default`).
+  #
+  #   @return [String] the config scope string (e.g. `"local"`, `"global"`)
+  #
+  # @!attribute [r] origin
+  #
+  #   Where the configuration entry originates
+  #
+  #   The origin is in the format `<origin-type>:<actual-origin>` and is never
+  #   blank. The origin type prefix is one of `file:`, `blob:`, `command line:`,
+  #   or `standard input:`.
+  #
+  #   `nil` when the git command used to retrieve this entry does not support
+  #   `--show-origin` (currently only `--get-urlmatch`).
+  #
+  #   @return [String, nil] the origin path in the format `<type>:<path>`, or `nil`
+  #
+  # @!attribute [r] key
+  #
+  #   The full dotted key name of the configuration entry (e.g., `remote.origin.url`)
+  #
+  #   @return [String] the full dotted key name (e.g. `remote.origin.url`)
+  #
+  # @!attribute [r] value
+  #
+  #   The value of the configuration entry
+  #
+  #   @return [String] the string value of this entry
+  #
+  ConfigEntryInfo = Data.define(:scope, :origin, :key, :value) do
+    # Returns the section component of the key (everything before the first dot)
+    #
+    # Returns an empty string when the key contains no dot.
+    #
+    # @example Section component of a dotted key
+    #   entry.section # => "remote"
+    #
+    # @return [String] the section name, or an empty string when the key has no dot
+    #
+    def section = first_dot ? key[0...first_dot] : ''
+
+    # Returns the subsection component of the key (everything between the first and last dot)
+    #
+    # Returns an empty string when the key has zero or one dot (no subsection).
+    #
+    # @example Subsection component of a dotted key
+    #   entry.subsection # => "origin"
+    #
+    # @return [String] the subsection name, or an empty string when there is no subsection
+    #
+    def subsection = first_dot && first_dot != last_dot ? key[(first_dot + 1)...last_dot] : ''
+
+    # Returns the variable component of the key (everything after the last dot)
+    #
+    # Returns the full key when the key contains no dot.
+    #
+    # @example Variable component of a dotted key
+    #   entry.variable # => "url"
+    #
+    # @return [String] the variable name (everything after the last dot)
+    #
+    def variable = last_dot ? key[(last_dot + 1)..] : key
+
+    private
+
+    # Returns the index of the first dot in the key, or nil if none exists
+    #
+    # @return [Integer, nil] the zero-based index of the first dot, or `nil`
+    #
+    def first_dot = key.index('.')
+
+    # Returns the index of the last dot in the key, or nil if none exists
+    #
+    # @return [Integer, nil] the zero-based index of the last dot, or `nil`
+    #
+    def last_dot = key.rindex('.')
+  end
+end