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

data/lib/git/repository/configuring.rb

@@ -5,10 +5,16 @@ require 'git/repository/shared_private'
 
 module Git
   class Repository
-    # Facade methods for reading and writing git configuration
+    # Legacy facade methods for reading and writing git configuration
     #
-    # Provides the {#config} method, which dispatches to read a single entry,
-    # list all entries, or write a value depending on the arguments supplied.
+    # Provides the {#config} and {#global_config} dispatch methods for 4.x
+    # compatibility. These methods return raw `String` / `Hash` values instead of
+    # {Git::ConfigEntryInfo} objects and are retained so that internal callers such
+    # as `Git::Status` continue to work unchanged.
+    #
+    # The structured `config_*` methods (e.g. `config_get`, `config_list`) are
+    # provided by {Git::Configuring}, which is included directly into
+    # {Git::Repository}.
     #
     # Included by {Git::Repository}.
     #
@@ -19,6 +25,10 @@ module Git
       CONFIG_SET_ALLOWED_OPTS = %i[file].freeze
       private_constant :CONFIG_SET_ALLOWED_OPTS
 
+      # Option keys accepted by {#config} when reading a single value or listing
+      CONFIG_READ_ALLOWED_OPTS = %i[file].freeze
+      private_constant :CONFIG_READ_ALLOWED_OPTS
+
       # Read or write a git configuration entry
       #
       # Dispatches to one of three modes depending on the arguments supplied:
@@ -28,24 +38,45 @@ module Git
       # * **Set** — `config(name, value)` writes a value and returns the raw
       #   command result.
       #
-      # @overload config
+      # @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
+      #
       #   @return [Hash{String => String}] all visible config entries, keyed by
       #     their full dotted key names (e.g. `"user.name"`)
       #
-      # @overload config(name)
+      #   @raise [ArgumentError] if unsupported options are provided
+      #
+      # @overload config(name, options = {})
       #
       #   @example Read the committer name from config
       #     repo.config('user.name') #=> "Alice"
       #
+      #   @example Read a value from a custom config file
+      #     repo.config('user.name', file: '/path/to/.gitconfig') #=> "Alice"
+      #
       #   @param name [String] the dotted config key to look up (e.g.
       #     `"user.name"`)
       #
+      #   @param options [Hash] options for the get operation
+      #
+      #   @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
@@ -57,7 +88,12 @@ module Git
       #   @param name [String] the dotted config key to write (e.g.
       #     `"user.name"`)
       #
-      #   @param value [String] the value to assign
+      #   @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
       #
@@ -72,12 +108,70 @@ module Git
       # @raise [Git::FailedError] if git exits with a non-zero exit status
       #
       def config(name = nil, value = nil, options = {})
-        if name && value
+        name, value, options = Private.normalize_config_args(name, value, options)
+
+        if !name.nil? && !value.nil?
           Private.config_set(@execution_context, name, value, **options)
         elsif name
-          Private.config_get(@execution_context, name)
+          Private.config_get(@execution_context, name, **options)
+        else
+          Private.config_list(@execution_context, **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::CommandLineResult] 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)
+        if !name.nil? && !value.nil?
+          Private.global_config_set(@execution_context, name, value)
+        elsif !name.nil?
+          Private.global_config_get(@execution_context, name)
         else
-          Private.config_list(@execution_context)
+          Private.global_config_list(@execution_context)
         end
       end
 
@@ -88,6 +182,39 @@ module Git
       module Private
         module_function
 
+        # Normalize `config()` positional arguments
+        #
+        # In Ruby 3.x, calling `config(file: '/path')` passes the hash as the
+        # first positional argument. This helper re-maps those patterns so that
+        # `name`, `value`, and `options` are always in their canonical positions.
+        #
+        # Raises `ArgumentError` for call shapes that are ambiguous or clearly
+        # wrong, such as passing extra positional arguments after an options Hash.
+        #
+        # @param name [String, Hash, nil] the raw first argument to {#config}
+        #
+        # @param value [Object, Hash, nil] the raw second argument to {#config}
+        #
+        # @param options [Hash] the raw third argument to {#config}
+        #
+        # @return [Array(String|nil, Object|nil, Hash)] normalized [name, value, options]
+        #
+        # @raise [ArgumentError] if extra positional arguments follow an options Hash
+        #
+        def 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
+
         # Set a config value by key name
         #
         # @overload config_set(execution_context, name, value, **options)
@@ -121,12 +248,20 @@ module Git
         #
         # @param name [String] the dotted config key to look up (e.g. `"user.name"`)
         #
+        # @param options [Hash] keyword options
+        #
+        # @option options [String, nil] :file (nil) path to a custom config file to read from
+        #
         # @return [String] the value of the config entry
         #
+        # @raise [ArgumentError] if unsupported options are provided
+        #
         # @raise [Git::FailedError] if git exits with a non-zero exit status
         #
-        def config_get(execution_context, name)
-          result = Git::Commands::ConfigOptionSyntax::Get.new(execution_context).call(name)
+        def config_get(execution_context, 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
@@ -136,18 +271,78 @@ module Git
         #
         # @param execution_context [Git::ExecutionContext] the execution context
         #
+        # @param options [Hash] keyword options
+        #
+        # @option options [String, nil] :file (nil) path to a custom config file to read from
+        #
         # @return [Hash{String => String}] all config entries, keyed by their full
         #   dotted key names (e.g. `"user.name"`)
         #
+        # @raise [ArgumentError] if unsupported options are provided
+        #
+        # @raise [Git::FailedError] if git exits with a non-zero exit status
+        #
+        def config_list(execution_context, **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
+
+        # Retrieve a global config value by key name
+        #
+        # @param execution_context [Git::ExecutionContext] the execution context
+        #
+        # @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
+        #
+        def global_config_get(execution_context, 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
+
+        # Retrieve all global config entries as a hash
+        #
+        # @param execution_context [Git::ExecutionContext] the execution context
+        #
+        # @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
         #
-        def config_list(execution_context)
-          lines = Git::Commands::ConfigOptionSyntax::List.new(execution_context).call.stdout.split("\n")
+        def global_config_list(execution_context)
+          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
+
+        # Set a global config value by key name
+        #
+        # @param execution_context [Git::ExecutionContext] the execution context
+        #
+        # @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::CommandLineResult] the raw result of
+        #   `git config --global <name> <value>`
+        #
+        # @raise [Git::FailedError] if git exits with a non-zero exit status
+        #
+        def global_config_set(execution_context, name, value)
+          Git::Commands::ConfigOptionSyntax::Set.new(execution_context).call(name, value, global: true)
+        end
       end
 
       private_constant :Private

data/lib/git/repository/context_helpers.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'pathname'
+require 'tmpdir'
+require 'git/execution_context/repository'
+
+module Git
+  class Repository
+    # Facade methods for block-based directory and index context helpers
+    #
+    # These helpers allow callers to temporarily change the working directory,
+    # the git index, or both, restoring the original state unconditionally when
+    # the block exits — even if the block raises an exception.
+    #
+    # Included by {Git::Repository}.
+    #
+    # @api public
+    #
+    module ContextHelpers
+      # Changes the current working directory to the repository working directory
+      # for the duration of the block
+      #
+      # @example Write a file inside the repository working directory
+      #   repo.chdir do |dir|
+      #     File.write('hello.txt', 'Hello, world!')
+      #     repo.add('hello.txt')
+      #   end
+      #
+      # @yield [dir] the repository working directory
+      #
+      # @yieldparam dir [Pathname] the working directory path
+      #
+      # @yieldreturn [Object] returned as the method's return value
+      #
+      # @return [Object] the value returned by the block
+      #
+      # @raise [ArgumentError] if the repository has no working directory (bare
+      #   repository)
+      #
+      def chdir
+        raise ArgumentError, 'cannot chdir: repository has no working directory (bare repository)' if dir.nil?
+
+        Dir.chdir(dir.to_s) { yield dir }
+      end
+
+      # Temporarily switches the git index to `new_index` for the duration of
+      # the block
+      #
+      # Rebuilds the repository execution context to point to the new index file,
+      # yields `self`, then unconditionally restores the original execution
+      # context — even if the block raises an exception.
+      #
+      # @example Read a tree into a custom index
+      #   repo.with_index('/tmp/custom.index') do
+      #     repo.read_tree('HEAD')
+      #   end
+      #
+      # @param new_index [String, Pathname] path to the replacement index file
+      #
+      # @yield [repo] the repository instance with the new index active
+      #
+      # @yieldparam repo [Git::Repository] `self`
+      #
+      # @yieldreturn [Object] returned as the method's return value
+      #
+      # @return [Object] the value returned by the block
+      #
+      def with_index(new_index) # :yields: self
+        old_context = @execution_context
+        set_index(new_index, must_exist: false)
+        yield self
+      ensure
+        @execution_context = old_context
+      end
+
+      # Temporarily switches the git index to a new temporary file for the
+      # duration of the block, then removes the file
+      #
+      # The temporary index file does not exist until git creates it on first
+      # write. A unique temporary directory is created to hold the index path,
+      # avoiding the risk of presenting an empty file to git (which git would
+      # reject as a corrupt index). The directory — and any files inside it —
+      # are removed unconditionally after the block exits, even if the block
+      # raises an exception.
+      #
+      # @example Stage changes using a temporary index
+      #   repo.with_temp_index do
+      #     repo.read_tree('HEAD')
+      #     repo.write_tree
+      #   end
+      #
+      # @yield [repo] the repository instance with the temporary index active
+      #
+      # @yieldparam repo [Git::Repository] `self`
+      #
+      # @yieldreturn [Object] returned as the method's return value
+      #
+      # @return [Object] the value returned by the block
+      #
+      def with_temp_index(&) # :yields: self
+        # Use a unique temp directory so the index file path is collision-free
+        # and does not exist until git writes it. An existing empty file would
+        # be treated as a corrupt index by git.
+        temp_dir = Dir.mktmpdir('git-temp-index-')
+        begin
+          with_index(File.join(temp_dir, 'index'), &)
+        ensure
+          FileUtils.remove_entry(temp_dir, true)
+        end
+      end
+
+      # Temporarily switches the git working directory to `work_dir` for the
+      # duration of the block
+      #
+      # Rebuilds the repository execution context to point to the new working
+      # directory, changes the process working directory via `Dir.chdir`, yields
+      # `self`, then unconditionally restores the original execution context —
+      # even if the block raises an exception.
+      #
+      # @example Commit changes from a different worktree path
+      #   repo.with_working('/path/to/worktree') do
+      #     repo.add('.')
+      #     repo.commit('chore: automated update')
+      #   end
+      #
+      # @param work_dir [String, Pathname] path to the replacement working
+      #   directory
+      #
+      # @yield [repo] the repository instance with the new working directory
+      #   active
+      #
+      # @yieldparam repo [Git::Repository] `self`
+      #
+      # @yieldreturn [Object] returned as the method's return value
+      #
+      # @return [Object] the value returned by the block
+      #
+      # @raise [ArgumentError] if `work_dir` does not exist on disk
+      #
+      def with_working(work_dir) # :yields: self
+        old_context = @execution_context
+        set_working(work_dir)
+        Dir.chdir(dir.to_s) { yield self }
+      ensure
+        @execution_context = old_context
+      end
+
+      # Temporarily switches the git working directory to a new temporary
+      # directory for the duration of the block, then removes the directory and
+      # its contents
+      #
+      # The temporary directory is removed unconditionally after the block
+      # exits, even if the block raises an exception.
+      #
+      # @example Write files in an isolated temporary working directory
+      #   repo.with_temp_working do
+      #     File.write('scratch.txt', 'temporary content')
+      #   end
+      #
+      # @yield [repo] the repository instance with the temporary working
+      #   directory active
+      #
+      # @yieldparam repo [Git::Repository] `self`
+      #
+      # @yieldreturn [Object] returned as the method's return value
+      #
+      # @return [Object] the value returned by the block
+      #
+      def with_temp_working(&block) # :yields: self
+        Dir.mktmpdir('temp-workdir') { |temp_dir| with_working(temp_dir, &block) }
+      end
+
+      # Sets the git index to `index_file` and rebuilds the execution context
+      #
+      # By default raises if `index_file` does not exist. Pass `must_exist:
+      # false` to skip the existence check (useful when the index will be
+      # created by git later).
+      #
+      # @example Set the index to a custom path
+      #   repo.set_index('/path/to/custom.index')
+      #
+      # @param index_file [String, Pathname] path to the new index file
+      #
+      # @param check [Boolean, nil] deprecated positional argument — use
+      #   `must_exist:` instead; emits a deprecation warning when non-`nil`
+      #
+      # @param must_exist [Boolean, nil] when `true` (the default), raises
+      #   `ArgumentError` if `index_file` does not exist on disk
+      #
+      # @return [void]
+      #
+      # @raise [ArgumentError] if `must_exist: true` (the default) and
+      #   `index_file` does not exist
+      #
+      def set_index(index_file, check = nil, must_exist: nil)
+        must_exist = context_helpers_deprecate_check_argument(check, must_exist)
+        new_path = context_helpers_validate_path(index_file, must_exist)
+        context_helpers_rebuild_context(git_index_file: new_path.to_s)
+        nil
+      end
+
+      # Sets the git working directory to `work_dir` and rebuilds the execution
+      # context
+      #
+      # By default raises if `work_dir` does not exist. Pass `must_exist:
+      # false` to skip the existence check.
+      #
+      # @example Set the working directory to a custom path
+      #   repo.set_working('/path/to/working')
+      #
+      # @param work_dir [String, Pathname] path to the new working directory
+      #
+      # @param check [Boolean, nil] deprecated positional argument — use
+      #   `must_exist:` instead; emits a deprecation warning when non-`nil`
+      #
+      # @param must_exist [Boolean, nil] when `true` (the default), raises
+      #   `ArgumentError` if `work_dir` does not exist on disk
+      #
+      # @return [void]
+      #
+      # @raise [ArgumentError] if `must_exist: true` (the default) and
+      #   `work_dir` does not exist
+      #
+      def set_working(work_dir, check = nil, must_exist: nil)
+        must_exist = context_helpers_deprecate_check_argument(check, must_exist)
+        new_path = context_helpers_validate_path(work_dir, must_exist)
+        context_helpers_rebuild_context(git_work_dir: new_path.to_s)
+        nil
+      end
+
+      private
+
+      def context_helpers_deprecate_check_argument(check, must_exist)
+        if !check.nil? && defined?(Git::Deprecation)
+          Git::Deprecation.warn(
+            'The "check" argument is deprecated and will be removed in a future version. ' \
+            'Use "must_exist:" instead.'
+          )
+        end
+        # Preserve the original Git::Base semantics: when both the deprecated
+        # positional `check` and the new `must_exist:` keyword are given, OR
+        # them so the more restrictive value wins.
+        #
+        # NilClass#| is defined in Ruby: nil | false → false, nil | true → true.
+        # This means single-argument callers (check only, or must_exist: only)
+        # are handled correctly without any nil-special-casing.
+        return true if must_exist.nil? && check.nil?
+
+        must_exist | check
+      end
+
+      def context_helpers_validate_path(path, must_exist)
+        Pathname.new(File.expand_path(path.to_s)).tap do |expanded_path|
+          raise ArgumentError, "path does not exist: #{expanded_path}" if must_exist && !expanded_path.exist?
+        end
+      end
+
+      def context_helpers_rebuild_context(**overrides)
+        @execution_context = @execution_context.dup_with(**overrides)
+      end
+    end
+  end
+end