git 5.0.0.beta.3 → 5.0.0.beta.4

data/lib/git/repository/stashing.rb

@@ -9,7 +9,7 @@ module Git
     #
     # Included by {Git::Repository}.
     #
-    # @api public
+    # @api private
     #
     module Stashing
       # Returns all stash entries as an array of index and message pairs
@@ -19,13 +19,6 @@ module Git
       # message is the stash description with the leading branch prefix (e.g.
       # `"On main:"` or `"WIP on main:"`) stripped.
       #
-      # @note The sequential index returned here is **not** the same as git's
-      #   `stash@{N}` reference used by {#stash_apply}. In git, `stash@{0}` is the
-      #   **most recent** stash, while index `0` here is the **oldest**. To apply a
-      #   specific stash from this list, convert the entry's position to a git
-      #   reference: `'stash@{%d}' % (total - 1 - index)`, or pass the string
-      #   reference directly to {#stash_apply}.
-      #
       # @example List all stashes (oldest first)
       #   repo.stashes_all #=> [[0, "Fix bug"], [1, "Add feature"]]
       #
@@ -35,6 +28,13 @@ module Git
       #
       # @raise [Git::FailedError] if git exits with a non-zero exit status
       #
+      # @note The sequential index returned here is **not** the same as git's
+      #   `stash@{N}` reference used by {#stash_apply}. In git, `stash@{0}` is the
+      #   **most recent** stash, while index `0` here is the **oldest**. To apply a
+      #   specific stash from this list, convert the entry's position to a git
+      #   reference: `'stash@{%d}' % (total - 1 - index)`, or pass the string
+      #   reference directly to {#stash_apply}.
+      #
       # @see https://git-scm.com/docs/git-stash git-stash documentation
       #
       def stashes_all
@@ -48,8 +48,6 @@ module Git
 
       # Returns stash entries as a formatted string matching `git stash list` output
       #
-      # @deprecated Use {#stashes_all} instead.
-      #
       # @example List stashes as a formatted string
       #   repo.stash_list #=> "stash@{0}: On main: WIP\nstash@{1}: On feature: Fix bug"
       #
@@ -59,6 +57,8 @@ module Git
       #
       # @raise [Git::FailedError] if git exits with a non-zero exit status
       #
+      # @deprecated Use {#stashes_all} instead
+      #
       # @see #stashes_all
       #
       # @see https://git-scm.com/docs/git-stash git-stash documentation
@@ -75,6 +75,9 @@ module Git
 
       # Save the current working directory and index state to a new stash
       #
+      # @example Save current changes
+      #   repo.stash_save('WIP: feature work')
+      #
       # @param message [String] the stash message
       #
       # @return [Boolean] true if changes were stashed, false if there were no
@@ -82,9 +85,6 @@ module Git
       #
       # @raise [Git::FailedError] if git exits with a non-zero exit status
       #
-      # @example Save current changes
-      #   repo.stash_save('WIP: feature work')
-      #
       # @see https://git-scm.com/docs/git-stash git-stash documentation
       #
       def stash_save(message) # rubocop:disable Naming/PredicateMethod
@@ -125,14 +125,14 @@ module Git
       # Removes all entries from the stash list. Use with caution as this
       # operation cannot be undone.
       #
+      # @example Clear all stashes
+      #   repo.stash_clear #=> ""
+      #
       # @return [String] the output from the git stash clear command
       #   (typically empty)
       #
       # @raise [Git::FailedError] if git exits with a non-zero exit status
       #
-      # @example Clear all stashes
-      #   repo.stash_clear #=> ""
-      #
       # @see https://git-scm.com/docs/git-stash git-stash documentation
       #
       def stash_clear

data/lib/git/repository/status_operations.rb

@@ -15,7 +15,7 @@ module Git
     #
     # Included by {Git::Repository}.
     #
-    # @api public
+    # @api private
     #
     module StatusOperations
       # Returns `true` if the repository has no commits yet

data/lib/git/repository/worktree_operations.rb

@@ -10,7 +10,7 @@ module Git
     #
     # Included by {Git::Repository}.
     #
-    # @api public
+    # @api private
     #
     module WorktreeOperations
       # Returns all worktrees as an array of directory and SHA pairs

data/lib/git/repository.rb

@@ -4,7 +4,6 @@ require 'find'
 require 'pathname'
 
 require 'git/configuring'
-require 'git/deprecation'
 require 'git/execution_context/repository'
 require 'git/repository/branching'
 require 'git/repository/context_helpers'
@@ -49,8 +48,6 @@ module Git
   # @api public
   #
   class Repository # rubocop:disable Metrics/ClassLength
-    extend Git::Repository::Factories
-
     include Git::Configuring
     include Git::Repository::Branching
     include Git::Repository::ContextHelpers
@@ -67,17 +64,33 @@ module Git
     include Git::Repository::StatusOperations
     include Git::Repository::WorktreeOperations
 
+    # Allowed keyword options for deprecated config write operations
+    #
+    # @return [Array<Symbol>] accepted option keys
+    #
     CONFIG_SET_ALLOWED_OPTS = %i[file].freeze
     private_constant :CONFIG_SET_ALLOWED_OPTS
 
+    # Allowed keyword options for deprecated config read operations
+    #
+    # @return [Array<Symbol>] accepted option keys
+    #
     CONFIG_READ_ALLOWED_OPTS = %i[file].freeze
     private_constant :CONFIG_READ_ALLOWED_OPTS
 
+    # Deprecation warning emitted by {#config}
+    #
+    # @return [String] the warning message shown to callers
+    #
     CONFIG_DEPRECATION_WARNING =
       'Git::Repository#config is deprecated and will be removed in v6.0.0. ' \
       'Use config_get(name), config_set(name, value), or config_list instead.'
     private_constant :CONFIG_DEPRECATION_WARNING
 
+    # Deprecation warning emitted by {#global_config}
+    #
+    # @return [String] the warning message shown to callers
+    #
     GLOBAL_CONFIG_DEPRECATION_WARNING =
       'Git::Repository#global_config is deprecated and will be removed in v6.0.0. ' \
       'Use config_get(name, global: true), config_set(name, value, global: true), ' \
@@ -86,6 +99,7 @@ module Git
 
     # @return [Git::ExecutionContext::Repository] the execution context used to run
     #   git commands for this repository
+    #
     # @api private
     attr_reader :execution_context
 
@@ -169,6 +183,11 @@ module Git
     # @api private
     def git_index_file = execution_context.git_index_file
 
+    # Returns the installed git version
+    #
+    # @param timeout [Numeric, nil] seconds to wait for `git version`; `nil`
+    #   uses the default timeout for this execution context
+    #
     # @return [Git::Version] the installed git version
     #
     # @api private
@@ -184,7 +203,7 @@ module Git
     # @api private
     def binary_path = execution_context.binary_path
 
-    # Read or write a git configuration entry
+    # Reads or writes a git configuration entry
     #
     # Dispatches to one of three modes depending on the arguments supplied:
     #
@@ -193,72 +212,29 @@ module Git
     # * **Set** — `config(name, value)` writes a value and returns the raw
     #   command result.
     #
-    # @overload config(options = {})
-    #
-    #   @example List all config entries
-    #     repo.config #=> { "user.name" => "Alice", "core.bare" => "false" }
-    #
-    #   @example List all entries from a custom config file
-    #     repo.config(file: '/path/to/.gitconfig')
-    #     #=> { "user.name" => "Alice", "core.bare" => "false" }
-    #
-    #   @param options [Hash] options for the list operation
-    #
-    #   @option options [String, nil] :file (nil) path to a custom config file
-    #     to read from instead of the default resolution chain
+    # @example List all config entries
+    #   repo.config #=> { "user.name" => "Alice", "core.bare" => "false" }
     #
-    #   @return [Hash{String => String}] all visible config entries, keyed by
-    #     their full dotted key names (e.g. `"user.name"`)
+    # @example Read a config value
+    #   repo.config('user.name') #=> "Alice"
     #
-    #   @raise [ArgumentError] if unsupported options are provided
+    # @example Set a config value
+    #   repo.config('user.name', 'Alice')
     #
-    # @overload config(name, options = {})
+    # @param name [String, Hash, nil] the dotted config key, or an options hash
+    #   for list mode when `value` and `options` are omitted
     #
-    #   @example Read the committer name from config
-    #     repo.config('user.name') #=> "Alice"
+    # @param value [#to_s, Hash, nil] the value to set, or an options hash in the
+    #   legacy `config(name, options)` call shape
     #
-    #   @example Read a value from a custom config file
-    #     repo.config('user.name', file: '/path/to/.gitconfig') #=> "Alice"
+    # @param options [Hash] options forwarded to git config
     #
-    #   @param name [String] the dotted config key to look up (e.g.
-    #     `"user.name"`)
+    # @option options [String, nil] :file (nil) path to a custom config file
     #
-    #   @param options [Hash] options for the get operation
+    # @return [Hash{String => String}, String, Git::CommandLine::Result] all config
+    #   entries, a single value, or the command result for set mode
     #
-    #   @option options [String, nil] :file (nil) path to a custom config file
-    #     to read from instead of the default resolution chain
-    #
-    #   @return [String] the value of the config entry
-    #
-    #   @raise [ArgumentError] if unsupported options are provided
-    #
-    # @overload config(name, value, options = {})
-    #
-    #   @example Set the committer name in local config
-    #     repo.config('user.name', 'Alice')
-    #
-    #   @example Write a value to a custom config file
-    #     repo.config('user.name', 'Alice', file: '/path/to/custom/config')
-    #
-    #   @param name [String] the dotted config key to write (e.g.
-    #     `"user.name"`)
-    #
-    #   @param value [#to_s] the value to assign; must not be `nil` (a `nil`
-    #     value is treated as "no value" and routes to the get overload).
-    #     Must not be a `Hash` (a Hash is treated as the `options` argument;
-    #     call `value.to_s` explicitly before passing if a stringified Hash
-    #     is genuinely needed). Any other non-nil object is converted to a
-    #     String via `#to_s` before being passed to git
-    #
-    #   @param options [Hash] options for the set operation
-    #
-    #   @option options [String, nil] :file (nil) path to a custom config file
-    #     to write to instead of the repository's default `.git/config`
-    #
-    #   @return [Git::CommandLineResult] the raw result of
-    #     `git config <name> <value>`
-    #
-    #   @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
     #
@@ -316,7 +292,7 @@ module Git
     #   @param value [#to_s] the value to assign; any object is accepted and
     #     converted to a String via `#to_s` before being passed to git
     #
-    #   @return [Git::CommandLineResult] the raw result of
+    #   @return [Git::CommandLine::Result] the raw result of
     #     `git config --global <name> <value>`
     #
     #   @raise [Git::FailedError] if git exits with a non-zero exit status
@@ -361,6 +337,22 @@ module Git
 
     private
 
+    # Normalizes deprecated `config` call shapes into positional arguments
+    #
+    # @param name [String, Hash, nil] config key or an options hash
+    #
+    # @param value [#to_s, Hash, nil] config value or an options hash
+    #
+    # @param options [Hash] explicit options hash argument
+    #
+    # @option options [String, nil] :file (nil) path to a custom config file
+    #
+    # @return [Array((String, nil), (#to_s, nil), Hash)] normalized
+    #   `[name, value, options]`
+    #
+    # @raise [ArgumentError] if deprecated arguments mix an options hash with
+    #   unexpected additional positional arguments
+    #
     def deprecated_normalize_config_args(name, value, options)
       if name.is_a?(Hash)
         raise ArgumentError, 'unexpected positional arguments after options hash' if !value.nil? || !options.empty?
@@ -375,11 +367,43 @@ module Git
       end
     end
 
+    # Writes a config value using the deprecated `config(name, value, ...)` path
+    #
+    # @overload deprecated_config_set(name, value, **options)
+    #
+    #   @param name [String] the dotted config key to write
+    #
+    #   @param value [#to_s] the value to assign
+    #
+    #   @param options [Hash] command options
+    #
+    #   @option options [String, nil] :file (nil) path to a custom config file
+    #
+    #   @return [Git::CommandLine::Result] the command result
+    #
+    #   @raise [ArgumentError] if unsupported options are provided
+    #
+    #   @raise [Git::FailedError] if git exits with a non-zero exit status
+    #
     def deprecated_config_set(name, value, **)
       SharedPrivate.assert_valid_opts!(CONFIG_SET_ALLOWED_OPTS, **)
       Git::Commands::ConfigOptionSyntax::Set.new(@execution_context).call(name, value, **)
     end
 
+    # Reads a config value using the deprecated `config(name, ...)` path
+    #
+    # @param name [String] the dotted config key to read
+    #
+    # @param options [Hash] command options
+    #
+    # @option options [String, nil] :file (nil) path to a custom config file
+    #
+    # @return [String] the config value
+    #
+    # @raise [ArgumentError] if unsupported options are provided
+    #
+    # @raise [Git::FailedError] if git exits with a non-zero exit status
+    #
     def deprecated_config_get(name, **options)
       SharedPrivate.assert_valid_opts!(CONFIG_READ_ALLOWED_OPTS, **options)
       opts = options[:file] ? { file: options[:file] } : {}
@@ -389,6 +413,18 @@ module Git
       result.stdout
     end
 
+    # Lists config entries using the deprecated `config(...)` path
+    #
+    # @param options [Hash] command options
+    #
+    # @option options [String, nil] :file (nil) path to a custom config file
+    #
+    # @return [Hash{String => String}] all visible config entries keyed by name
+    #
+    # @raise [ArgumentError] if unsupported options are provided
+    #
+    # @raise [Git::FailedError] if git exits with a non-zero exit status
+    #
     def deprecated_config_list(**options)
       SharedPrivate.assert_valid_opts!(CONFIG_READ_ALLOWED_OPTS, **options)
       opts = options[:file] ? { file: options[:file] } : {}
@@ -399,6 +435,14 @@ module Git
       end
     end
 
+    # Reads a global config value using the deprecated `global_config(name)` path
+    #
+    # @param name [String] the dotted config key to read
+    #
+    # @return [String] the config value
+    #
+    # @raise [Git::FailedError] if git exits with a non-zero exit status
+    #
     def deprecated_global_config_get(name)
       result = Git::Commands::ConfigOptionSyntax::Get.new(@execution_context).call(name, global: true)
       raise Git::FailedError, result if result.status.exitstatus != 0
@@ -406,6 +450,12 @@ module Git
       result.stdout
     end
 
+    # Lists global config entries using the deprecated `global_config` path
+    #
+    # @return [Hash{String => String}] all global config entries keyed by name
+    #
+    # @raise [Git::FailedError] if git exits with a non-zero exit status
+    #
     def deprecated_global_config_list
       lines = Git::Commands::ConfigOptionSyntax::List.new(@execution_context).call(global: true).stdout.split("\n")
       lines.each_with_object({}) do |line, hsh|
@@ -414,6 +464,16 @@ module Git
       end
     end
 
+    # Writes a global config value using the deprecated `global_config` path
+    #
+    # @param name [String] the dotted config key to write
+    #
+    # @param value [#to_s] the value to assign
+    #
+    # @return [Git::CommandLine::Result] the command result
+    #
+    # @raise [Git::FailedError] if git exits with a non-zero exit status
+    #
     def deprecated_global_config_set(name, value)
       Git::Commands::ConfigOptionSyntax::Set.new(@execution_context).call(name, value, global: true)
     end

data/lib/git/stash.rb

@@ -16,15 +16,6 @@ module Git
     # When `existing` is `false` (the default), immediately calls {#save} to push
     # the current working-directory state onto the stash stack.
     #
-    # @param base [Git::Repository] the git repository
-    #
-    # @param message [String] the stash message
-    #
-    # @param existing [Boolean] (false) when `true`, wraps an existing stash entry
-    #   without pushing any changes
-    #
-    # @return [void]
-    #
     # @example Create a new stash entry
     #   stash = Git::Stash.new(repo, 'WIP: feature work')
     #   stash.saved?  #=> true
@@ -33,6 +24,14 @@ module Git
     #   stash = Git::Stash.new(repo, 'WIP: feature work', existing: true)
     #   stash.saved?  #=> nil
     #
+    # @param base [Git::Repository] the git repository
+    #
+    # @param message [String] the stash message
+    #
+    # @param existing [Boolean] (false) when `true`, wraps an existing stash entry
+    #   without pushing any changes
+    #
+    # @return [void]
     def initialize(base, message, existing: false)
       @base = base
       @message = message
@@ -41,50 +40,46 @@ module Git
 
     # Saves the current working-directory state to the stash stack
     #
-    # @return [Boolean] `true` if changes were stashed, `false` if there were no
-    #   local changes to save
-    #
-    # @raise [Git::FailedError] if git exits with a non-zero exit status
-    #
     # @example Save changes to the stash stack
     #   stash = Git::Stash.new(repo, 'WIP', existing: true)
     #   stash.save  #=> true
     #
+    # @return [Boolean] `true` if changes were stashed, `false` if there were no
+    #   local changes to save
+    #
+    # @raise [Git::FailedError] if git exits with a non-zero exit status
     def save
       @saved = stash_repository.stash_save(@message)
     end
 
     # Returns whether the stash was saved successfully
     #
-    # @return [Boolean, nil] `true` if changes were stashed, `false` if there were no
-    #   local changes, `nil` if {#save} has not been called (e.g. `existing: true`)
-    #
     # @example Check if changes were stashed
     #   stash = Git::Stash.new(repo, 'WIP: feature work')
     #   stash.saved?  #=> true
     #
+    # @return [Boolean, nil] `true` if changes were stashed, `false` if there were no
+    #   local changes, `nil` if {#save} has not been called (e.g. `existing: true`)
     def saved?
       @saved
     end
 
     # Returns the stash description
     #
-    # @return [String] the stash message
-    #
     # @example Read the stash message
     #   stash = Git::Stash.new(repo, 'WIP: feature work', existing: true)
     #   stash.message  #=> "WIP: feature work"
     #
+    # @return [String] the stash message
     attr_reader :message
 
     # Returns the stash description as a string
     #
-    # @return [String] the stash message
-    #
     # @example Convert stash to string
     #   stash = Git::Stash.new(repo, 'WIP: feature work', existing: true)
     #   stash.to_s  #=> "WIP: feature work"
     #
+    # @return [String] the stash message
     def to_s
       message
     end

data/lib/git/stash_info.rb

@@ -8,7 +8,6 @@ module Git
   # its index, reference name, commit SHA, branch, message, author/committer
   # details, and timestamps.
   #
-  # @api public
   #
   # @example Create a StashInfo from parsed stash list output
   #   info = Git::StashInfo.new(
@@ -39,6 +38,8 @@ module Git
   #   info.committer_email # => 'jane@example.com'
   #   info.committer_date  # => '2026-01-24T10:30:00-08:00'
   #
+  # @api public
+  #
   # @!attribute [r] index
   #   @return [Integer] the stash index (0, 1, 2, ...)
   #
@@ -92,11 +93,10 @@ module Git
   ) do
     # Returns the stash reference name
     #
-    # @return [String] the stash name (e.g., 'stash@\\{0}')
-    #
-    # @example
+    # @example Convert to string
     #   info.to_s # => 'stash@{0}'
     #
+    # @return [String] the stash name (e.g., 'stash@\\{0}')
     def to_s
       name
     end

data/lib/git/stashes.rb

@@ -19,16 +19,15 @@ module Git
     #
     # Loads all existing stash entries from the repository at construction time.
     #
+    # @example Load stashes for a repository
+    #   stashes = Git::Stashes.new(repo)
+    #   stashes.size  #=> 2
+    #
     # @param base [Git::Repository] the git repository
     #
     # @return [void]
     #
     # @raise [Git::FailedError] if git exits with a non-zero exit status
-    #
-    # @example Load stashes for a repository
-    #   stashes = Git::Stashes.new(repo)
-    #   stashes.size  #=> 2
-    #
     def initialize(base)
       @stashes = []
       @base = base
@@ -57,16 +56,15 @@ module Git
 
     # Saves the current working-directory state to a new stash entry
     #
+    # @example Save current changes to the stash
+    #   git.stashes.save('WIP: feature work')
+    #   git.stashes.size  #=> 1
+    #
     # @param message [String] the stash message
     #
     # @return [void]
     #
     # @raise [Git::FailedError] if git exits with a non-zero exit status
-    #
-    # @example Save current changes to the stash
-    #   git.stashes.save('WIP: feature work')
-    #   git.stashes.size  #=> 1
-    #
     def save(message)
       s = Git::Stash.new(@base, message)
       @stashes.unshift(s) if s.saved?
@@ -74,32 +72,30 @@ module Git
 
     # Applies a stash entry to the working directory
     #
-    # @param index [Integer, nil] the stash index to apply (default: latest)
-    #
-    # @return [String] the output from the git stash apply command
-    #
-    # @raise [Git::FailedError] if git exits with a non-zero exit status
-    #
     # @example Apply the most recent stash
     #   git.stashes.apply
     #
     # @example Apply a specific stash by index
     #   git.stashes.apply(1)
     #
+    # @param index [Integer, nil] the stash index to apply (default: latest)
+    #
+    # @return [String] the output from the git stash apply command
+    #
+    # @raise [Git::FailedError] if git exits with a non-zero exit status
     def apply(index = nil)
       stash_repository.stash_apply(index)
     end
 
     # Removes all stash entries
     #
-    # @return [void]
-    #
-    # @raise [Git::FailedError] if git exits with a non-zero exit status
-    #
     # @example Clear all stashes
     #   git.stashes.clear
     #   git.stashes.size  #=> 0
     #
+    # @return [void]
+    #
+    # @raise [Git::FailedError] if git exits with a non-zero exit status
     def clear
       stash_repository.stash_clear
       @stashes = []
@@ -108,11 +104,10 @@ module Git
 
     # Returns the number of stash entries
     #
-    # @return [Integer] the number of stashes
-    #
     # @example Check how many stashes exist
     #   git.stashes.size  #=> 2
     #
+    # @return [Integer] the number of stashes
     def size
       @stashes.size
     end
@@ -144,13 +139,12 @@ module Git
     #
     # Stashes are stored in newest-first order; index 0 is the most recent stash.
     #
-    # @param index [Integer, #to_i] the stash index (0 = most recent)
-    #
-    # @return [Git::Stash, nil] the stash entry, or `nil` if the index is out of bounds
-    #
     # @example Access the most recent stash
     #   git.stashes[0].message  #=> "WIP: feature work"
     #
+    # @param index [Integer, #to_i] the stash index (0 = most recent)
+    #
+    # @return [Git::Stash, nil] the stash entry, or `nil` if the index is out of bounds
     def [](index)
       @stashes[index.to_i]
     end