git 5.0.0.beta.2 → 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,12 +4,10 @@ require 'find'
 require 'pathname'
 
 require 'git/configuring'
-require 'git/deprecation'
 require 'git/execution_context/repository'
 require 'git/repository/branching'
 require 'git/repository/context_helpers'
 require 'git/repository/committing'
-require 'git/repository/configuring'
 require 'git/repository/diffing'
 require 'git/repository/factories'
 require 'git/repository/inspecting'
@@ -18,6 +16,7 @@ require 'git/repository/maintenance'
 require 'git/repository/merging'
 require 'git/repository/object_operations'
 require 'git/repository/remote_operations'
+require 'git/repository/shared_private'
 require 'git/repository/staging'
 require 'git/repository/stashing'
 require 'git/repository/status_operations'
@@ -48,14 +47,11 @@ module Git
   #
   # @api public
   #
-  class Repository
-    extend Git::Repository::Factories
-
+  class Repository # rubocop:disable Metrics/ClassLength
     include Git::Configuring
     include Git::Repository::Branching
     include Git::Repository::ContextHelpers
     include Git::Repository::Committing
-    include Git::Repository::Configuring
     include Git::Repository::Diffing
     include Git::Repository::Inspecting
     include Git::Repository::Logging
@@ -68,8 +64,42 @@ 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), ' \
+      'or config_list(global: true) instead.'
+    private_constant :GLOBAL_CONFIG_DEPRECATION_WARNING
+
     # @return [Git::ExecutionContext::Repository] the execution context used to run
     #   git commands for this repository
+    #
     # @api private
     attr_reader :execution_context
 
@@ -153,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
@@ -168,6 +203,111 @@ module Git
     # @api private
     def binary_path = execution_context.binary_path
 
+    # Reads or writes a git configuration entry
+    #
+    # Dispatches to one of three modes depending on the arguments supplied:
+    #
+    # * **List** — `config()` returns all visible config entries as a `Hash`.
+    # * **Get** — `config(name)` returns the value for a single key as a `String`.
+    # * **Set** — `config(name, value)` writes a value and returns the raw
+    #   command result.
+    #
+    # @example List all config entries
+    #   repo.config #=> { "user.name" => "Alice", "core.bare" => "false" }
+    #
+    # @example Read a config value
+    #   repo.config('user.name') #=> "Alice"
+    #
+    # @example Set a config value
+    #   repo.config('user.name', 'Alice')
+    #
+    # @param name [String, Hash, nil] the dotted config key, or an options hash
+    #   for list mode when `value` and `options` are omitted
+    #
+    # @param value [#to_s, Hash, nil] the value to set, or an options hash in the
+    #   legacy `config(name, options)` call shape
+    #
+    # @param options [Hash] options forwarded to git config
+    #
+    # @option options [String, nil] :file (nil) path to a custom config file
+    #
+    # @return [Hash{String => String}, String, Git::CommandLine::Result] all config
+    #   entries, a single value, or the command result for set mode
+    #
+    # @raise [ArgumentError] if unsupported options are provided
+    #
+    # @raise [Git::FailedError] if git exits with a non-zero exit status
+    #
+    def config(name = nil, value = nil, options = {})
+      Git::Deprecation.warn(CONFIG_DEPRECATION_WARNING)
+      name, value, options = deprecated_normalize_config_args(name, value, options)
+
+      if !name.nil? && !value.nil?
+        deprecated_config_set(name, value, **options)
+      elsif name
+        deprecated_config_get(name, **options)
+      else
+        deprecated_config_list(**options)
+      end
+    end
+
+    # Read or write a global git configuration entry
+    #
+    # Dispatches to one of three modes depending on the arguments supplied,
+    # targeting the git global config scope (`git config --global`):
+    #
+    # * **List** — `global_config()` returns all global config entries as a `Hash`.
+    # * **Get** — `global_config(name)` returns the value for a single key as a `String`.
+    # * **Set** — `global_config(name, value)` writes a value and returns the raw
+    #   command result.
+    #
+    # @overload global_config
+    #
+    #   @example List all global config entries
+    #     repo.global_config #=> { "user.name" => "Alice", "core.autocrlf" => "false" }
+    #
+    #   @return [Hash{String => String}] all global config entries, keyed by their
+    #     full dotted key names (e.g. `"user.name"`)
+    #
+    #   @raise [Git::FailedError] if git exits with a non-zero exit status
+    #
+    # @overload global_config(name)
+    #
+    #   @example Read the global committer name
+    #     repo.global_config('user.name') #=> "Alice"
+    #
+    #   @param name [String] the dotted config key to look up (e.g. `"user.name"`)
+    #
+    #   @return [String] the value of the global config entry
+    #
+    #   @raise [Git::FailedError] if git exits with a non-zero exit status
+    #
+    # @overload global_config(name, value)
+    #
+    #   @example Set the global committer name
+    #     repo.global_config('user.name', 'Alice')
+    #
+    #   @param name [String] the dotted config key to write (e.g. `"user.name"`)
+    #
+    #   @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::CommandLine::Result] the raw result of
+    #     `git config --global <name> <value>`
+    #
+    #   @raise [Git::FailedError] if git exits with a non-zero exit status
+    #
+    def global_config(name = nil, value = nil)
+      Git::Deprecation.warn(GLOBAL_CONFIG_DEPRECATION_WARNING)
+      if !name.nil? && !value.nil?
+        deprecated_global_config_set(name, value)
+      elsif !name.nil?
+        deprecated_global_config_get(name)
+      else
+        deprecated_global_config_list
+      end
+    end
+
     # Returns the size of the repository directory in bytes
     #
     # Sums the sizes of every regular file under the repository (`.git`)
@@ -197,6 +337,147 @@ 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?
+
+        [nil, nil, name]
+      elsif value.is_a?(Hash)
+        raise ArgumentError, 'unexpected third argument when second argument is options hash' unless options.empty?
+
+        [name, nil, value]
+      else
+        [name, value, options]
+      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] } : {}
+      result = Git::Commands::ConfigOptionSyntax::Get.new(@execution_context).call(name, **opts)
+      raise Git::FailedError, result if result.status.exitstatus != 0
+
+      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] } : {}
+      lines = Git::Commands::ConfigOptionSyntax::List.new(@execution_context).call(**opts).stdout.split("\n")
+      lines.each_with_object({}) do |line, hsh|
+        key, value = line.split('=', 2)
+        hsh[key] = value || ''
+      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
+
+      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|
+        key, value = line.split('=', 2)
+        hsh[key] = value || ''
+      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
+
     # All git config scopes are valid in a repository context
     #
     # @return [void]

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