git 5.7.0 → 6.0.0

data/lib/git/repository/context_helpers.rb

@@ -4,14 +4,33 @@ require 'fileutils'
 require 'pathname'
 require 'tmpdir'
 require 'git/execution_context/repository'
+require 'git/system_call_guard'
 
 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.
+    # The `with_*` helpers build a second {Git::Repository} bound to a different
+    # index file or working directory, yield it, and leave the receiver bound to
+    # its original index and working directory. Nothing on the receiver changes,
+    # so nothing on it is restored when the block exits. The working directory
+    # variants change the process working directory for the duration of the
+    # block and change it back afterward. The temporary variants remove the
+    # scratch directory they created, even if the block raises an exception.
+    #
+    # The second repository is built with `self.class.new(execution_context:)`,
+    # so a subclass of {Git::Repository} must accept that constructor call for
+    # the helpers to yield an instance of the subclass.
+    #
+    # Each `with_*` helper requires a block that declares a positional parameter
+    # for the yielded repository and raises `ArgumentError` otherwise. A block with no
+    # positional parameter is the v5.x form, which relied on the receiver being
+    # rebound; failing fast keeps that form from running against the original
+    # index or working directory.
+    #
+    # {#set_index} and {#set_working} are deprecated and warn on every call
+    # through {Git::Deprecation}; UPGRADING.md explains why and shows the
+    # replacements.
     #
     # Included by {Git::Repository}.
     #
@@ -22,6 +41,18 @@ module Git
       CONTEXT_HELPERS_POSITIONAL_PARAMETERS = %i[req opt rest].freeze
       private_constant :CONTEXT_HELPERS_POSITIONAL_PARAMETERS
 
+      # Deprecation message for {#set_index}
+      SET_INDEX_DEPRECATION = 'Git::Repository#set_index is deprecated and will be removed in a future major ' \
+                              'release. Open a repository bound to the index instead: ' \
+                              'Git.open(dir, index: path) or Git.bare(git_dir, index: path).'
+      private_constant :SET_INDEX_DEPRECATION
+
+      # Deprecation message for {#set_working}
+      SET_WORKING_DEPRECATION = 'Git::Repository#set_working is deprecated and will be removed in a future major ' \
+                                'release. Open a repository bound to the working tree instead: ' \
+                                'Git.open(work_dir, repository: git_dir).'
+      private_constant :SET_WORKING_DEPRECATION
+
       # Changes the current working directory to the repository working directory
       # for the duration of the block
       #
@@ -36,6 +67,8 @@ module Git
       # @raise [ArgumentError] if the repository has no working directory (bare
       #   repository)
       #
+      # @raise [Git::Error] if the working directory cannot be entered
+      #
       # @yield [dir] the repository working directory
       #
       # @yieldparam dir [Pathname] the working directory path
@@ -45,104 +78,114 @@ module Git
       def chdir
         raise ArgumentError, 'cannot chdir: repository has no working directory (bare repository)' if dir.nil?
 
-        Dir.chdir(dir.to_s) { yield dir }
+        context_helpers_chdir(dir.to_s) { yield dir }
       end
 
-      # Temporarily switches the git index to `new_index` for the duration of
-      # the block
+      # Yields a repository bound to `new_index` in place of the receiver's index
       #
-      # 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.
-      #
-      # Deprecated form: a block that declares no positional parameter emits a
-      # deprecation warning, because v6.0.0 yields a separate repository
-      # instead of `self`.
+      # Yields a second repository bound to `new_index`; its working directory
+      # and git directory are the receiver's. The receiver is not changed, so
+      # calls on it inside the block still use the original index.
       #
       # @example Read a tree into a custom index
-      #   repo.with_index('/tmp/custom.index') do |r|
-      #     r.read_tree('HEAD')
+      #   repo.with_index('/tmp/custom.index') do |indexed|
+      #     indexed.read_tree('HEAD')
       #   end
       #
       # @param new_index [String, Pathname] path to the replacement index file
       #
       # @return [Object] the value returned by the block
       #
-      # @yield [repo] the repository instance with the new index active
+      # @raise [ArgumentError] if no block is given or the block declares no
+      #   positional parameter
+      #
+      # @raise [Git::Error] if `new_index` cannot be expanded to an absolute path
+      #
+      # @yield [repo] the repository bound to `new_index`
       #
-      # @yieldparam repo [Git::Repository] `self`
+      # @yieldparam repo [Git::Repository] a new repository of the receiver's
+      #   class bound to `new_index`
       #
       # @yieldreturn [Object] returned as the method's return value
       #
-      def with_index(new_index, &block) # :yields: self
-        context_helpers_warn_if_block_declares_no_parameter(:with_index, block)
-        old_context = @execution_context
-        set_index(new_index, must_exist: false)
-        yield self
-      ensure
-        @execution_context = old_context
+      def with_index(new_index, &block)
+        context_helpers_require_repository_block(block)
+        new_path = context_helpers_validate_path(new_index, false)
+        yield context_helpers_derived_repository(git_index_file: new_path.to_s)
       end
 
-      # Temporarily switches the git index to a new temporary file for the
-      # duration of the block, then removes the file
+      # Yields a repository bound to a new temporary index file, 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.
-      #
-      # Deprecated form: a block that declares no positional parameter emits a
-      # deprecation warning, because v6.0.0 yields a separate repository
-      # instead of `self`.
-      #
-      # @example Stage changes using a temporary index
-      #   repo.with_temp_index do |r|
-      #     r.read_tree('HEAD')
-      #     r.write_tree
+      # 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. The yielded repository is bound as {#with_index} binds it.
+      #
+      # @example Write a tree from a temporary index
+      #   tree_sha = repo.with_temp_index do |indexed|
+      #     indexed.read_tree('HEAD')
+      #     indexed.add('generated.txt')
+      #     indexed.write_tree
       #   end
       #
       # @return [Object] the value returned by the block
       #
-      # @yield [repo] the repository instance with the temporary index active
+      # @raise [ArgumentError] if no block is given or the block declares no
+      #   positional parameter
       #
-      # @yieldparam repo [Git::Repository] `self`
+      # @raise [Git::Error] if the temporary directory cannot be created
+      #
+      # @yield [repo] the repository bound to the temporary index
+      #
+      # @yieldparam repo [Git::Repository] a new repository of the receiver's
+      #   class bound to an index file inside the temporary directory
       #
       # @yieldreturn [Object] returned as the method's return value
       #
-      def with_temp_index(&block) # :yields: self
-        context_helpers_warn_if_block_declares_no_parameter(:with_temp_index, block)
+      # @note The yielded repository stays bound to the temporary index path
+      #   after the directory that held it is removed. Do not let it, or an
+      #   object that holds it and later runs commands against the index,
+      #   escape the block. Git treats the missing index file, even with its
+      #   directory gone, as an empty index, so reads such as {Git::Repository::StatusOperations#ls_files}
+      #   return nothing and {Git::Repository::StatusOperations#status_info}
+      #   reports every tracked file both as deleted and as untracked; writes
+      #   such as {Git::Repository::Staging#add} raise {Git::Error}. Reads from
+      #   the object database, such as {Git::Object::AbstractObject#contents},
+      #   still work.
+      #
+      def with_temp_index(&block)
+        context_helpers_require_repository_block(block)
         # 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-')
+        temp_dir = context_helpers_mktmpdir('git-temp-index-')
         begin
-          # The inner block declares a parameter so with_index does not warn a
-          # second time under its own name; forwarding &block would.
-          # rubocop:disable-next Style/ExplicitBlockArgument
-          with_index(File.join(temp_dir, 'index')) { |repo| yield repo }
+          with_index(File.join(temp_dir, 'index'), &block)
         ensure
           FileUtils.remove_entry(temp_dir, true)
         end
       end
 
-      # Temporarily switches the git working directory to `work_dir` for the
-      # duration of the block
+      # Yields a repository bound to `work_dir` in place of the receiver's
+      # working directory
       #
-      # 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.
+      # Yields a second repository bound to `work_dir`. It shares the
+      # receiver's index and git directory, so staging through it changes what
+      # the receiver sees as staged. The process working directory is changed
+      # to `work_dir` via `Dir.chdir` for the duration of the block and changed
+      # back afterward. The receiver is not changed, so calls on it inside the
+      # block still use the original working directory.
       #
-      # Deprecated form: a block that declares no positional parameter emits a
-      # deprecation warning, because v6.0.0 yields a separate repository
-      # instead of `self`.
+      # `Dir.chdir` is process-global, so this method is not safe to call from
+      # more than one thread at a time.
       #
       # @example Commit changes from a different worktree path
-      #   repo.with_working('/path/to/worktree') do |r|
-      #     r.add('.')
-      #     r.commit('chore: automated update')
+      #   repo.with_working('/path/to/worktree') do |worktree|
+      #     worktree.add('.')
+      #     worktree.commit('chore: automated update')
       #   end
       #
       # @param work_dir [String, Pathname] path to the replacement working
@@ -150,56 +193,69 @@ module Git
       #
       # @return [Object] the value returned by the block
       #
-      # @raise [ArgumentError] if `work_dir` does not exist on disk
+      # @raise [ArgumentError] if `work_dir` does not exist on disk, if no block
+      #   is given, or if the block declares no positional parameter
+      #
+      # @raise [Git::Error] if `work_dir` cannot be expanded to an absolute path
+      #   or cannot be entered
       #
-      # @yield [repo] the repository instance with the new working directory
-      #   active
+      # @yield [repo] the repository bound to `work_dir`
       #
-      # @yieldparam repo [Git::Repository] `self`
+      # @yieldparam repo [Git::Repository] a new repository of the receiver's
+      #   class bound to `work_dir`
       #
       # @yieldreturn [Object] returned as the method's return value
       #
-      def with_working(work_dir, &block) # :yields: self
-        context_helpers_warn_if_block_declares_no_parameter(:with_working, block)
-        old_context = @execution_context
-        set_working(work_dir)
-        Dir.chdir(dir.to_s) { yield self }
-      ensure
-        @execution_context = old_context
+      def with_working(work_dir, &block)
+        context_helpers_require_repository_block(block)
+        new_path = context_helpers_validate_path(work_dir, true)
+        repo = context_helpers_derived_repository(git_work_dir: new_path.to_s)
+        context_helpers_chdir(new_path.to_s) { yield repo }
       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
+      # Yields a repository bound to a new temporary working directory, then
+      # removes the directory and its contents
       #
-      # The temporary directory is removed unconditionally after the block
-      # exits, even if the block raises an exception.
-      #
-      # Deprecated form: a block that declares no positional parameter emits a
-      # deprecation warning, because v6.0.0 yields a separate repository
-      # instead of `self`.
+      # The process working directory is changed to the temporary directory for
+      # the duration of the block, as {#with_working} does, so this method is
+      # not safe to call from more than one thread at a time. The directory is
+      # removed unconditionally after the block exits, even if the block raises
+      # an exception. The yielded repository is bound as {#with_working} binds
+      # it.
       #
       # @example Write files in an isolated temporary working directory
-      #   repo.with_temp_working do |r|
+      #   repo.with_temp_working do |scratch|
       #     File.write('scratch.txt', 'temporary content')
-      #     r.add('scratch.txt')
+      #     scratch.untracked_files #=> ["scratch.txt"]
       #   end
       #
       # @return [Object] the value returned by the block
       #
-      # @yield [repo] the repository instance with the temporary working
-      #   directory active
+      # @raise [ArgumentError] if no block is given or the block declares no
+      #   positional parameter
+      #
+      # @raise [Git::Error] if the temporary directory cannot be created or
+      #   removed
+      #
+      # @yield [repo] the repository bound to the temporary working directory
       #
-      # @yieldparam repo [Git::Repository] `self`
+      # @yieldparam repo [Git::Repository] a new repository of the receiver's
+      #   class bound to the temporary directory
       #
       # @yieldreturn [Object] returned as the method's return value
       #
-      def with_temp_working(&block) # :yields: self
-        context_helpers_warn_if_block_declares_no_parameter(:with_temp_working, block)
-        # The inner block declares a parameter so with_working does not warn a
-        # second time under its own name; forwarding &block would.
-        # rubocop:disable-next Style/ExplicitBlockArgument
-        Dir.mktmpdir('temp-workdir') { |temp_dir| with_working(temp_dir) { |repo| yield repo } }
+      # @note The yielded repository stays bound to the temporary working
+      #   directory after it is removed. Do not let it, or an object that holds
+      #   it and later runs commands against the working tree, escape the
+      #   block: calls that read or write the working tree then raise
+      #   {Git::Error}. Reads from the object database, such as
+      #   {Git::Object::AbstractObject#contents}, still work.
+      #
+      def with_temp_working(&block)
+        context_helpers_require_repository_block(block)
+        Git::SystemCallGuard.call('Failed to create or remove a temporary directory') do |guard|
+          Dir.mktmpdir('temp-workdir') { |temp_dir| guard.unguarded { with_working(temp_dir, &block) } }
+        end
       end
 
       # Sets the git index to `index_file` and rebuilds the execution context
@@ -208,15 +264,20 @@ module Git
       # false` to skip the existence check (useful when the index will be
       # created by git later).
       #
+      # Every call warns through {Git::Deprecation}; see {ContextHelpers}.
+      #
       # @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
+      # @example Open a repository bound to the index instead
+      #   repo = Git.open('/path/to/repo', index: '/path/to/custom.index')
       #
-      # @param check [Boolean, nil] deprecated positional argument — use
-      #   `must_exist:` instead; emits a deprecation warning when non-`nil`
+      # @example Open a bare repository bound to the index instead
+      #   repo = Git.bare('/srv/repo.git', index: '/tmp/scratch.index')
       #
-      # @param must_exist [Boolean, nil] when `true` (the default), raises
+      # @param index_file [String, Pathname] path to the new index file
+      #
+      # @param must_exist [Boolean] when `true` (the default), raises
       #   `ArgumentError` if `index_file` does not exist on disk
       #
       # @return [void]
@@ -224,10 +285,15 @@ module Git
       # @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)
+      # @deprecated Use `Git.open(dir, index: path)` or
+      #   `Git.bare(git_dir, index: path)` to open a repository bound to the
+      #   index, or {#with_index} to bind a copy for the duration of a block.
+      #   Will be removed in a future major release.
+      #
+      def set_index(index_file, must_exist: true)
+        Git::Deprecation.warn(SET_INDEX_DEPRECATION)
         new_path = context_helpers_validate_path(index_file, must_exist)
-        context_helpers_rebuild_context(git_index_file: new_path.to_s)
+        @execution_context = @execution_context.dup_with(git_index_file: new_path.to_s)
         nil
       end
 
@@ -237,15 +303,25 @@ module Git
       # By default raises if `work_dir` does not exist. Pass `must_exist:
       # false` to skip the existence check.
       #
+      # Every call warns through {Git::Deprecation}; see {ContextHelpers}.
+      #
+      # `set_working` keeps the receiver's index. `Git.open` with `:repository`
+      # alone resolves the index to `<git_dir>/index`, so pass `:index` as well
+      # whenever the receiver's index was custom.
+      #
       # @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
+      # @example Open a repository bound to the working tree instead
+      #   repo = Git.open('/path/to/working', repository: '/path/to/repo/.git')
       #
-      # @param check [Boolean, nil] deprecated positional argument — use
-      #   `must_exist:` instead; emits a deprecation warning when non-`nil`
+      # @example Open a repository bound to the working tree and a custom index
+      #   repo = Git.open('/path/to/working', repository: '/path/to/repo/.git',
+      #                   index: '/path/to/custom.index')
       #
-      # @param must_exist [Boolean, nil] when `true` (the default), raises
+      # @param work_dir [String, Pathname] path to the new working directory
+      #
+      # @param must_exist [Boolean] when `true` (the default), raises
       #   `ArgumentError` if `work_dir` does not exist on disk
       #
       # @return [void]
@@ -253,76 +329,86 @@ module Git
       # @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)
+      # @deprecated Use `Git.open(work_dir, repository: git_dir)` to open a
+      #   repository bound to the working tree, adding `index:` when the
+      #   receiver's index was custom, or {#with_working} to bind a copy for
+      #   the duration of a block. Will be removed in a future major release.
+      #
+      def set_working(work_dir, must_exist: true)
+        Git::Deprecation.warn(SET_WORKING_DEPRECATION)
         new_path = context_helpers_validate_path(work_dir, must_exist)
-        context_helpers_rebuild_context(git_work_dir: new_path.to_s)
+        @execution_context = @execution_context.dup_with(git_work_dir: new_path.to_s)
         nil
       end
 
       private
 
-      # Emits a deprecation warning when `block` declares no positional parameter
+      # Runs the block with the process working directory set to `path`
+      #
+      # A `SystemCallError` from entering or leaving `path` is raised as
+      # {Git::Error}. A `SystemCallError` raised by the block propagates
+      # unchanged.
+      #
+      # The message does not name a directory because `Dir.chdir` fails on
+      # either leg: entering `path`, or restoring the previous directory
+      # afterward. The underlying `SystemCallError` names the directory that
+      # actually failed.
+      #
+      # @param path [String] the directory to enter
       #
-      # In v6.0.0 the `with_*` helpers yield a separate repository instead of
-      # rebinding the receiver, so a block that calls methods on the receiver
-      # (the v5.x form) acts on the wrong repository there. v6.0.0 raises
-      # `ArgumentError` for that form using this same rule: the block must
-      # declare a required, optional, or splat positional parameter. The rule
-      # reads `Proc#parameters` rather than arity because an optional parameter
-      # gives a proc an arity of zero although it receives the repository,
-      # while keyword and block parameters cannot receive it.
+      # @return [Object] the value returned by the block
+      #
+      # @raise [Git::Error] if `path` cannot be entered
       #
-      # A missing block is not checked here; the helper's `yield` raises
-      # `LocalJumpError` as before.
+      # @yield the code to run inside `path`
       #
-      # The warning reports the helper's caller, not this helper's caller, so
-      # the location points at the block that needs changing.
+      # @yieldreturn [Object] returned as the method's return value
       #
-      # @param helper [Symbol] the public helper name used in the warning
+      # @api private
       #
-      # @param block [Proc, nil] the block passed to the helper
+      def context_helpers_chdir(path, &block)
+        Git::SystemCallGuard.call('Failed to change directory') do |guard|
+          Dir.chdir(path) { guard.unguarded(&block) }
+        end
+      end
+
+      # Raises unless `block` declares a positional parameter for the yielded
+      # repository
+      #
+      # A block with no positional parameter is the v5.x form that relied on
+      # the receiver being rebound; it fails fast rather than running against
+      # the original index or working directory. The check reads the block's
+      # parameter list rather than its arity because an optional parameter
+      # (`|repo = nil|`) gives a proc an arity of zero although it receives the
+      # repository, while keyword and block parameters cannot receive it.
+      #
+      # @param block [Proc, nil] the block passed to a `with_*` helper
       #
       # @return [void]
       #
-      def context_helpers_warn_if_block_declares_no_parameter(helper, block)
-        return if block.nil?
-        return if block.parameters.any? { |type, _name| CONTEXT_HELPERS_POSITIONAL_PARAMETERS.include?(type) }
+      # @raise [ArgumentError] if `block` is nil or declares no positional
+      #   parameter
+      #
+      # @api private
+      #
+      def context_helpers_require_repository_block(block)
+        return if block&.parameters&.any? { |type, _name| CONTEXT_HELPERS_POSITIONAL_PARAMETERS.include?(type) }
 
-        Git::Deprecation.warn(
-          "Calling Git::Repository##{helper} with a block that declares no positional " \
-          'parameter is deprecated and will be removed in v6.0.0, where the helper ' \
-          'yields a separate repository instead of self. Declare a block parameter and ' \
-          "call methods on it instead: #{helper} { |repo| repo.some_method }",
-          caller_locations(2)
-        )
+        raise ArgumentError, 'a block that accepts the yielded repository is required'
       end
 
-      # Resolves deprecated `check` argument semantics with `must_exist:`
+      # Creates a temporary directory, raising {Git::Error} on failure
       #
-      # @param check [Boolean, nil] deprecated positional existence-check value
+      # @param prefix [String] the directory name prefix
       #
-      # @param must_exist [Boolean, nil] keyword existence-check override
+      # @return [String] the path of the new directory
       #
-      # @return [Boolean] whether path existence must be enforced
+      # @raise [Git::Error] if the directory cannot be created
       #
-      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 v6.0.0. ' \
-            '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
+      # @api private
+      #
+      def context_helpers_mktmpdir(prefix)
+        Git::SystemCallGuard.call('Failed to create a temporary directory') { Dir.mktmpdir(prefix) }
       end
 
       # Expands `path` and validates existence when required
@@ -335,13 +421,19 @@ module Git
       #
       # @raise [ArgumentError] if `must_exist` is `true` and the path does not exist
       #
+      # @raise [Git::Error] if the path cannot be expanded, which happens when
+      #   `path` is relative and the process working directory has been removed
+      #
       def context_helpers_validate_path(path, must_exist)
-        Pathname.new(File.expand_path(path.to_s)).tap do |expanded_path|
+        expanded = Git::SystemCallGuard.call('Failed to expand the path') { File.expand_path(path.to_s) }
+
+        Pathname.new(expanded).tap do |expanded_path|
           raise ArgumentError, "path does not exist: #{expanded_path}" if must_exist && !expanded_path.exist?
         end
       end
 
-      # Rebuilds the repository execution context with selected overrides
+      # Builds a repository of the receiver's class bound to a copy of this
+      # execution context with selected overrides, leaving the receiver untouched
       #
       # @param overrides [Hash] execution-context attributes to override
       #
@@ -350,10 +442,12 @@ module Git
       # @option overrides [String, nil] :git_work_dir replacement working directory
       #   path
       #
-      # @return [void]
+      # @return [Git::Repository] a new repository built from the derived context
+      #
+      # @api private
       #
-      def context_helpers_rebuild_context(**overrides)
-        @execution_context = @execution_context.dup_with(**overrides)
+      def context_helpers_derived_repository(**overrides)
+        self.class.new(execution_context: @execution_context.dup_with(**overrides))
       end
     end
   end