git 5.0.0.beta.2 → 5.0.0.beta.4

data/lib/git/commands/worktree/lock.rb

@@ -31,27 +31,27 @@ module Git
           operand :worktree, required: true
         end
 
-        # @!method call(*, **)
+        # @overload call(worktree, **options)
         #
-        #   @overload call(worktree, **options)
+        #   Lock a worktree to prevent it from being pruned
         #
-        #     Lock a worktree to prevent it from being pruned
+        #   @param worktree [String] path or unique suffix identifying the
+        #     worktree to lock
         #
-        #     @param worktree [String] path or unique suffix identifying the
-        #       worktree to lock
+        #   @param options [Hash] command options
         #
-        #     @param options [Hash] command options
+        #   @option options [String] :reason (nil) human-readable explanation stored
+        #     alongside the lock
         #
-        #     @option options [String] :reason (nil) human-readable explanation stored
-        #       alongside the lock
+        #   @return [Git::CommandLine::Result] the result of calling `git worktree lock`
         #
-        #     @return [Git::CommandLineResult] the result of calling `git worktree lock`
+        # @raise [ArgumentError] if unsupported options are provided
         #
-        #     @raise [ArgumentError] if unsupported options are provided
+        # @raise [Git::FailedError] if git exits with a non-zero exit status
         #
-        #     @raise [Git::FailedError] if git exits with a non-zero exit status
+        # @api public
         #
-        #     @api public
+        def call(...) = super # rubocop:disable Lint/UselessMethodDefinition
       end
     end
   end

data/lib/git/commands/worktree/move.rb

@@ -32,34 +32,34 @@ module Git
           operand :new_path, required: true
         end
 
-        # @!method call(*, **)
+        # @overload call(worktree, new_path, **options)
         #
-        #   @overload call(worktree, new_path, **options)
+        #   Move a linked worktree to a new filesystem location
         #
-        #     Move a linked worktree to a new filesystem location
+        #   @param worktree [String] path or unique suffix identifying the
+        #     worktree to move
         #
-        #     @param worktree [String] path or unique suffix identifying the
-        #       worktree to move
+        #   @param new_path [String] destination path for the worktree
         #
-        #     @param new_path [String] destination path for the worktree
+        #   @param options [Hash] command options
         #
-        #     @param options [Hash] command options
+        #   @option options [Boolean, Integer, nil] :force (nil) allow moving a
+        #     locked worktree
         #
-        #     @option options [Boolean, Integer, nil] :force (nil) allow moving a
-        #       locked worktree
+        #     Pass `true` or `1` to emit `--force` once. Pass `2` to emit
+        #     `--force --force`, which also handles locked or missing destinations.
         #
-        #       Pass `true` or `1` to emit `--force` once. Pass `2` to emit
-        #       `--force --force`, which also handles locked or missing destinations.
+        #     Alias: :f
         #
-        #       Alias: :f
+        #   @return [Git::CommandLine::Result] the result of calling `git worktree move`
         #
-        #     @return [Git::CommandLineResult] the result of calling `git worktree move`
+        # @raise [ArgumentError] if unsupported options are provided
         #
-        #     @raise [ArgumentError] if unsupported options are provided
+        # @raise [Git::FailedError] if git exits with a non-zero exit status
         #
-        #     @raise [Git::FailedError] if git exits with a non-zero exit status
+        # @api public
         #
-        #     @api public
+        def call(...) = super # rubocop:disable Lint/UselessMethodDefinition
       end
     end
   end

data/lib/git/commands/worktree/prune.rb

@@ -34,7 +34,7 @@ module Git
           value_option :expire
         end
 
-        # @!method call(*, **)
+        # @!method call(*)
         #
         #   @overload call(**options)
         #
@@ -54,7 +54,7 @@ module Git
         #     @option options [String] :expire (nil) only prune entries older than
         #       this time expression
         #
-        #     @return [Git::CommandLineResult] the result of calling `git worktree prune`
+        #     @return [Git::CommandLine::Result] the result of calling `git worktree prune`
         #
         #     @raise [ArgumentError] if unsupported options are provided
         #

data/lib/git/commands/worktree/remove.rb

@@ -31,7 +31,7 @@ module Git
           operand :worktree, required: true
         end
 
-        # @!method call(*, **)
+        # @!method call(*)
         #
         #   @overload call(worktree, **options)
         #
@@ -50,7 +50,7 @@ module Git
         #
         #       Alias: :f
         #
-        #     @return [Git::CommandLineResult] the result of calling `git worktree remove`
+        #     @return [Git::CommandLine::Result] the result of calling `git worktree remove`
         #
         #     @raise [ArgumentError] if unsupported options are provided
         #

data/lib/git/commands/worktree/repair.rb

@@ -37,7 +37,7 @@ module Git
         # git worktree repair was introduced in git 2.29.0
         requires_git_version '2.29.0'
 
-        # @!method call(*, **)
+        # @!method call(*)
         #
         #   @overload call(*path, **options)
         #
@@ -61,7 +61,7 @@ module Git
         #       repair to update linking files if there is an absolute/relative
         #       mismatch, even if the links are already correct.
         #
-        #     @return [Git::CommandLineResult] the result of calling `git worktree repair`
+        #     @return [Git::CommandLine::Result] the result of calling `git worktree repair`
         #
         #     @raise [ArgumentError] if unsupported options are provided
         #

data/lib/git/commands/worktree/unlock.rb

@@ -27,7 +27,7 @@ module Git
           operand :worktree, required: true
         end
 
-        # @!method call(*, **)
+        # @!method call(*)
         #
         #   @overload call(worktree)
         #
@@ -36,7 +36,7 @@ module Git
         #     @param worktree [String] path or unique suffix identifying the worktree
         #       to unlock
         #
-        #     @return [Git::CommandLineResult] the result of calling `git worktree unlock`
+        #     @return [Git::CommandLine::Result] the result of calling `git worktree unlock`
         #
         #     @raise [Git::FailedError] if git exits with a non-zero exit status
         #

data/lib/git/commands/write_tree.rb

@@ -38,7 +38,7 @@ module Git
         value_option :prefix, inline: true
       end
 
-      # @!method call(*, **)
+      # @!method call(*)
       #
       #   @overload call(**options)
       #
@@ -55,7 +55,7 @@ module Git
       #
       #       The prefix path should end with `/` (e.g., `'lib/'`).
       #
-      #     @return [Git::CommandLineResult] the result of calling `git write-tree`
+      #     @return [Git::CommandLine::Result] the result of calling `git write-tree`
       #
       #     @raise [ArgumentError] if unsupported options are provided
       #

data/lib/git/commands.rb

@@ -58,7 +58,7 @@ module Git
   # Each git operation is represented by a class within this namespace. Command
   # classes define the CLI contract via the {Arguments} DSL, bind caller-supplied
   # parameters to command-line flags and operands, execute the subprocess through
-  # {Git::CommandLine}, and return a raw {Git::CommandLineResult}.
+  # {Git::CommandLine}, and return a raw {Git::CommandLine::Result}.
   #
   # Commands do **not** parse output — that responsibility belongs to the
   # {Git::Parsers} layer, orchestrated by the facade ({Git::Repository}).
@@ -78,10 +78,11 @@ module Git
   # block. Multi-mode git commands (e.g., `git branch`, `git stash`) are split
   # into namespace modules with one class per mode.
   #
-  # @api private
-  #
   # @see Git::Commands::Base
+  #
   # @see Git::Commands::Arguments
   #
+  # @api private
+  #
   module Commands; end
 end

data/lib/git/config.rb

@@ -2,6 +2,9 @@
 
 module Git
   # The global configuration for this gem
+  #
+  # @api public
+  #
   class Config
     # Returns the process-wide singleton {Git::Config} instance
     #
@@ -20,7 +23,23 @@ module Git
       @instance ||= new
     end
 
-    attr_writer :binary_path, :git_ssh, :timeout
+    # Sets the configuration options for the git executable, SSH, and timeout
+    #
+    # @return [String] the configured value
+    #
+    attr_writer :binary_path
+
+    # Sets the SSH command to use for git operations
+    #
+    # @return [String] the configured SSH command
+    #
+    attr_writer :git_ssh
+
+    # Sets the timeout for git operations
+    #
+    # @return [Integer] the configured timeout in seconds
+    #
+    attr_writer :timeout
 
     def initialize
       @binary_path = nil
@@ -28,14 +47,41 @@ module Git
       @timeout = nil
     end
 
+    # Returns the git executable path
+    #
+    # Uses an explicitly configured path first, then `GIT_PATH`, then `git`.
+    #
+    # @example Read the default executable
+    #   Git::Config.instance.binary_path #=> "git"
+    #
+    # @return [String] the git executable path
+    #
     def binary_path
       @binary_path || (ENV.fetch('GIT_PATH', nil) && File.join(ENV.fetch('GIT_PATH', nil), 'git')) || 'git'
     end
 
+    # Returns the SSH wrapper path used by git operations
+    #
+    # Uses an explicitly configured wrapper path first, then `GIT_SSH`.
+    #
+    # @example Read the configured SSH wrapper path
+    #   Git::Config.instance.git_ssh #=> "/usr/bin/ssh-wrapper"
+    #
+    # @return [String, nil] the configured SSH wrapper path
+    #
     def git_ssh
       @git_ssh || ENV.fetch('GIT_SSH', nil)
     end
 
+    # Returns the timeout for git operations
+    #
+    # Uses an explicitly configured timeout first, then `GIT_TIMEOUT`.
+    #
+    # @example Read the configured timeout
+    #   Git::Config.instance.timeout #=> 30
+    #
+    # @return [Integer, nil] the timeout in seconds
+    #
     def timeout
       @timeout || (ENV.fetch('GIT_TIMEOUT', nil) && ENV['GIT_TIMEOUT'].to_i)
     end

data/lib/git/configuring.rb

@@ -39,7 +39,7 @@ module Git
   #   end
   #   private_class_method :assert_valid_scope!
   #
-  # @api public
+  # @api private
   #
   module Configuring # rubocop:disable Metrics/ModuleLength
     # @!group Read Operations
@@ -113,7 +113,25 @@ module Git
     #
     # @param value_regex [String, nil] optional regex to filter by value
     #
-    # @param options [Hash] scope and filter options (see {#config_get})
+    # @param options [Hash] scope and filter options
+    #
+    # @option options [Boolean, nil] :global (nil) read from `~/.gitconfig`
+    #
+    # @option options [Boolean, nil] :system (nil) read from the system config file
+    #
+    # @option options [Boolean, nil] :local (nil) read from `.git/config`
+    #
+    # @option options [Boolean, nil] :worktree (nil) read from the worktree config
+    #
+    # @option options [String, nil] :file (nil) path to a custom config file (alias: `:f`)
+    #
+    # @option options [String, nil] :blob (nil) read from a git blob object
+    #
+    # @option options [Boolean, nil] :includes (nil) follow include directives
+    #
+    # @option options [Boolean, nil] :no_includes (nil) suppress include directives
+    #
+    # @option options [String, nil] :type (nil) enforce a type constraint on the value
     #
     # @return [Array<Git::ConfigEntryInfo>] all entries matching the key
     #
@@ -194,7 +212,25 @@ module Git
     #
     # @param value_regex [String, nil] optional regex to filter by value
     #
-    # @param options [Hash] scope and filter options (see {#config_get})
+    # @param options [Hash] scope and filter options
+    #
+    # @option options [Boolean, nil] :global (nil) read from `~/.gitconfig`
+    #
+    # @option options [Boolean, nil] :system (nil) read from the system config file
+    #
+    # @option options [Boolean, nil] :local (nil) read from `.git/config`
+    #
+    # @option options [Boolean, nil] :worktree (nil) read from the worktree config
+    #
+    # @option options [String, nil] :file (nil) path to a custom config file (alias: `:f`)
+    #
+    # @option options [String, nil] :blob (nil) read from a git blob object
+    #
+    # @option options [Boolean, nil] :includes (nil) follow include directives
+    #
+    # @option options [Boolean, nil] :no_includes (nil) suppress include directives
+    #
+    # @option options [String, nil] :type (nil) enforce a type constraint on the value
     #
     # @return [Array<Git::ConfigEntryInfo>] all entries whose key matches the regex
     #
@@ -219,10 +255,6 @@ module Git
     #
     # Wraps `git config --get-urlmatch --show-scope --null`.
     #
-    # Note: `--show-origin` is not supported by git for `--get-urlmatch`, so
-    # the {Git::ConfigEntryInfo} entries returned by this method always have
-    # `origin: nil`.
-    #
     # @example Get config entries for a specific URL
     #   entries = repo.config_get_urlmatch('http', 'https://github.com/user/repo')
     #   entries.map(&:key)
@@ -231,7 +263,25 @@ module Git
     #
     # @param url [String] the URL to match against
     #
-    # @param options [Hash] scope and filter options (see {#config_get})
+    # @param options [Hash] scope and filter options
+    #
+    # @option options [Boolean, nil] :global (nil) read from `~/.gitconfig`
+    #
+    # @option options [Boolean, nil] :system (nil) read from the system config file
+    #
+    # @option options [Boolean, nil] :local (nil) read from `.git/config`
+    #
+    # @option options [Boolean, nil] :worktree (nil) read from the worktree config
+    #
+    # @option options [String, nil] :file (nil) path to a custom config file (alias: `:f`)
+    #
+    # @option options [String, nil] :blob (nil) read from a git blob object
+    #
+    # @option options [Boolean, nil] :includes (nil) follow include directives
+    #
+    # @option options [Boolean, nil] :no_includes (nil) suppress include directives
+    #
+    # @option options [String, nil] :type (nil) enforce a type constraint on the value
     #
     # @return [Array<Git::ConfigEntryInfo>] all entries matching the URL; `origin` is `nil` on each
     #
@@ -239,6 +289,10 @@ module Git
     #
     # @raise [Git::FailedError] if git exits with an unexpected non-zero status
     #
+    # @note `--show-origin` is not supported by git for `--get-urlmatch`, so the
+    #   {Git::ConfigEntryInfo} entries returned by this method always have
+    #   `origin: nil`.
+    #
     def config_get_urlmatch(name, url, **options)
       Private.assert_valid_opts!(CONFIG_GET_URLMATCH_ALLOWED_OPTS, **options)
       assert_valid_scope!(**options)
@@ -260,7 +314,25 @@ module Git
     #   entries = repo.config_list
     #   entries.first.scope  # => "local"
     #
-    # @param options [Hash] scope and filter options (see {#config_get})
+    # @param options [Hash] scope and filter options
+    #
+    # @option options [Boolean, nil] :global (nil) read from `~/.gitconfig`
+    #
+    # @option options [Boolean, nil] :system (nil) read from the system config file
+    #
+    # @option options [Boolean, nil] :local (nil) read from `.git/config`
+    #
+    # @option options [Boolean, nil] :worktree (nil) read from the worktree config
+    #
+    # @option options [String, nil] :file (nil) path to a custom config file (alias: `:f`)
+    #
+    # @option options [String, nil] :blob (nil) read from a git blob object
+    #
+    # @option options [Boolean, nil] :includes (nil) follow include directives
+    #
+    # @option options [Boolean, nil] :no_includes (nil) suppress include directives
+    #
+    # @option options [String, nil] :type (nil) enforce a type constraint on the value
     #
     # @return [Array<Git::ConfigEntryInfo>] all visible config entries
     #
@@ -422,7 +494,7 @@ module Git
 
     # @overload config_replace_all(name, value, value_regex = nil, **options)
     #
-    #   Replace all values matching a key (and optional value regex)
+    #   Replace all values matching a key and optional value regex
     #
     #   Wraps `git config --replace-all`.
     #
@@ -642,18 +714,20 @@ module Git
     module Private
       module_function
 
-      # Validate that `options` contains only keys listed in `allowed`
+      # Validate that candidate option keys are listed in `allowed`
       #
       # @param allowed [Array<Symbol>] the permitted option keys
       #
-      # @param options [Hash] the options hash provided by the caller
+      # @param candidate_keywords [Hash<Symbol, Object>] the keywords to validate
+      #
+      # @option candidate_keywords [Object] key a candidate keyword value
       #
       # @return [void]
       #
-      # @raise [ArgumentError] when `options` contains any key not in `allowed`
+      # @raise [ArgumentError] when any candidate key is not in `allowed`
       #
-      def assert_valid_opts!(allowed, **options)
-        unknown = options.keys - allowed
+      def assert_valid_opts!(allowed, **candidate_keywords)
+        unknown = candidate_keywords.keys - allowed
         return if unknown.empty?
 
         raise ArgumentError, "Unknown options: #{unknown.join(', ')}"

data/lib/git/detached_head_info.rb

@@ -28,9 +28,12 @@ module Git
   #   system("git log #{head.short_name}")    # Works for both types
   #
   # @see Git::BranchInfo for the branch counterpart
+  #
   # @see Git::Commands::Branch::ShowCurrent for the command that produces this
   #
-  # @api public
+  # @api private
+  #
+  # Work in progress; this class is internal for now and may be made public in a future release.
   #
   # @!attribute [r] target_oid
   #

data/lib/git/diff.rb

@@ -326,11 +326,8 @@ module Git
       #   SHA is the null SHA
       #
       def blob(type = :dst)
-        if type == :src && !NIL_BLOB_REGEXP.match(@src)
-          @base.object(@src)
-        elsif !NIL_BLOB_REGEXP.match(@dst)
-          @base.object(@dst)
-        end
+        sha = type == :src ? @src : @dst
+        @base.object(sha) unless NIL_BLOB_REGEXP.match(sha)
       end
     end
 

data/lib/git/diff_file_numstat_info.rb

@@ -3,7 +3,9 @@
 module Git
   # Immutable value object representing stats for a single file from git numstat output
   #
-  # @api public
+  # @api private
+  #
+  # Work in progress; this class is internal for now and may be made public in a future release.
   #
   # @!attribute [r] path
   #   @return [String] the file path (destination path for renames)

data/lib/git/diff_file_patch_info.rb

@@ -9,7 +9,6 @@ module Git
   # including source and destination file references, the patch text, change type,
   # and line statistics.
   #
-  # @api public
   #
   # @example A modified file patch
   #   patch_info = Git::DiffFilePatchInfo.new(
@@ -59,6 +58,9 @@ module Git
   # @!attribute [r] deletions
   #   @return [Integer] number of lines deleted
   #
+  # @api private
+  #
+  # Work in progress; this class is internal for now and may be made public in a future release.
   DiffFilePatchInfo = Data.define(
     :src,
     :dst,

data/lib/git/diff_file_raw_info.rb

@@ -8,7 +8,6 @@ module Git
   # Contains the source and destination file references, change status,
   # similarity percentage (for renames/copies), and line change statistics.
   #
-  # @api public
   #
   # @example A modified file
   #   info = Git::DiffFileRawInfo.new(
@@ -64,6 +63,9 @@ module Git
   # @!attribute [r] binary
   #   @return [Boolean] whether this is a binary file
   #
+  # @api private
+  #
+  # Work in progress; this class is internal for now and may be made public in a future release.
   DiffFileRawInfo = Data.define(:src, :dst, :status, :similarity, :insertions, :deletions, :binary) do
     # Get the primary file path
     #

data/lib/git/diff_info.rb

@@ -8,7 +8,6 @@ module Git
   #
   # This class is used by DiffInfo for the legacy diff API.
   #
-  # @api public
   #
   # @example Create a FileDiffInfo from parsed diff output
   #   diff_info = Git::FileDiffInfo.new(
@@ -42,6 +41,9 @@ module Git
   # @!attribute [r] binary
   #   @return [Boolean] whether this is a binary file
   #
+  # @api private
+  #
+  # Work in progress; this class is internal for now and may be made public in a future release.
   FileDiffInfo = Data.define(
     :path,
     :patch,
@@ -70,8 +72,6 @@ module Git
   # - `:total` - Hash with `:insertions`, `:deletions`, `:lines`, `:files` keys
   # - `:files` - Hash mapping file paths to `{ insertions:, deletions: }` hashes
   #
-  # @api public
-  #
   # @example Create a DiffInfo from parsed stats output
   #   info = Git::DiffInfo.new(
   #     stats: {
@@ -90,6 +90,10 @@ module Git
   #   info.lines       # => 15
   #   info.file_count  # => 2
   #
+  # @api private
+  #
+  # Work in progress; this class is internal for now and may be made public in a future release.
+  #
   # @!attribute [r] stats
   #   @return [Hash] the statistics hash with :total and :files keys
   #
@@ -97,18 +101,6 @@ module Git
   #   @return [Array<FileDiffInfo>] array of file diff info objects (empty if patch not requested)
   #
   DiffInfo = Data.define(:stats, :file_patches) do
-    # @!method insertions
-    #   @return [Integer] total number of lines inserted
-
-    # @!method deletions
-    #   @return [Integer] total number of lines deleted
-
-    # @!method lines
-    #   @return [Integer] total number of lines changed (insertions + deletions)
-
-    # @!method file_count
-    #   @return [Integer] number of files changed
-
     # Total number of lines inserted
     #
     # @return [Integer]
@@ -160,6 +152,7 @@ module Git
     # Get patch info for a specific file
     #
     # @param path [String] the file path
+    #
     # @return [FileDiffInfo, nil] the diff info or nil if not found
     #
     def patch_for(path)

data/lib/git/diff_path_status.rb

@@ -13,6 +13,19 @@ module Git
     include Enumerable
 
     # @private
+    #
+    # @param base_or_hash [Git::Repository, Hash{String => String}] either a
+    #   repository object for legacy initialization or a pre-fetched name-status hash
+    #
+    # @param from [String, nil] the first commit/object to compare when using
+    #   legacy initialization
+    #
+    # @param to [String, nil] the second commit/object to compare when using
+    #   legacy initialization
+    #
+    # @param path_limiter [String, Pathname, Array, nil] path(s) to limit the
+    #   diff when using legacy initialization
+    #
     def initialize(base_or_hash, from = nil, to = nil, path_limiter = nil)
       if base_or_hash.is_a?(Hash)
         # New form: pre-fetched hash passed directly from Git::Repository::Diffing
@@ -29,6 +42,9 @@ module Git
     # @example Print each path and status
     #   diff_path_status.each { |path, status| puts "#{path}: #{status}" }
     #
+    # @return [Enumerator, Hash{String => String}] an `Enumerator` when no block
+    #   is given; the name-status hash when a block is given
+    #
     # @yield [path, status] each file path with its git status code
     #
     # @yieldparam path [String] the file path relative to the repository root
@@ -37,9 +53,6 @@ module Git
     #
     # @yieldreturn [void]
     #
-    # @return [Enumerator, Hash{String => String}] an `Enumerator` when no block
-    #   is given; the name-status hash when a block is given
-    #
     def each(&)
       return to_enum(__method__) unless block_given?
 

data/lib/git/diff_result.rb

@@ -11,7 +11,9 @@ module Git
   # - DiffFileRawInfo (from --raw)
   # - DiffFilePatchInfo (from --patch)
   #
-  # @api public
+  # @api private
+  #
+  # Work in progress; this class is internal for now and may be made public in a future release.
   #
   # @!attribute [r] files_changed
   #   @return [Integer] number of files changed (from --shortstat)

data/lib/git/diff_stats.rb

@@ -13,7 +13,22 @@ module Git
   #
   # @api public
   class DiffStats
+    # Initializes diff-stats state for a tree comparison.
+    #
     # @private
+    #
+    # @param base [Git::Repository] the git object used to fetch diff stats
+    #
+    # @param from [String] the first commit or object to compare
+    #
+    # @param to [String, nil] the second commit or object to compare
+    #
+    # @param path_limiter [String, Pathname, Array<String, Pathname>, nil]
+    #   path(s) to limit the diff
+    #
+    # @return [void]
+    #
+    # @raise [ArgumentError] when `from` or `to` starts with `"-"`
     def initialize(base, from, to, path_limiter = nil)
       # Eagerly check for invalid arguments
       [from, to].compact.each do |arg|