git 5.7.0 → 6.0.0

data/lib/git/repository/diffing.rb

@@ -299,7 +299,7 @@ module Git
       #
       # @api private
       #
-      DIFF_PATH_STATUS_ALLOWED_OPTS = %i[path_limiter path].freeze
+      DIFF_PATH_STATUS_ALLOWED_OPTS = %i[path_limiter].freeze
       private_constant :DIFF_PATH_STATUS_ALLOWED_OPTS
 
       # Returns the file path status between two trees
@@ -349,9 +349,6 @@ module Git
       # @option opts [String, Pathname, Array<String, Pathname>, nil] :path_limiter (nil)
       #   limit the status report to the given path(s)
       #
-      # @option opts [String, Pathname, Array<String, Pathname>, nil] :path (nil)
-      #   **deprecated** — use `:path_limiter` instead
-      #
       # @return [Git::DiffPathStatus] the name-status report for the comparison
       #
       # @raise [ArgumentError] if unsupported options are provided
@@ -366,50 +363,12 @@ module Git
         SharedPrivate.assert_valid_opts!(DIFF_PATH_STATUS_ALLOWED_OPTS, **opts)
         raise ArgumentError, 'Invalid arguments: `from` is nil but `to` is not' if from.nil? && !to.nil?
 
-        path_limiter = Private.resolve_path_limiter(opts)
-        pathspecs = Private.normalize_pathspecs(path_limiter, 'path limiter')
+        pathspecs = Private.normalize_pathspecs(opts[:path_limiter], 'path limiter')
 
         result = Private.call_diff_command(@execution_context, from, to, pathspecs)
         Git::DiffPathStatus.new(Private.extract_name_status_from_raw(result.stdout))
       end
 
-      # Reports each changed path with its status (deprecated name for {#diff_path_status})
-      #
-      # @example Report path statuses between HEAD and the working tree
-      #   repo.diff_name_status.to_h #=> { "lib/foo.rb" => "M" }
-      #
-      # @param from [String, nil] the first commit or object to compare
-      #
-      # @param to [String, nil] the second commit or object to compare
-      #
-      # @param opts [Hash] the options accepted by {#diff_path_status}
-      #
-      # @option opts [String, Pathname, Array<String, Pathname>, nil] :path_limiter (nil)
-      #   limit the status report to the given path(s)
-      #
-      # @option opts [String, Pathname, Array<String, Pathname>, nil] :path (nil)
-      #   **deprecated** — use `:path_limiter` instead
-      #
-      # @return [Git::DiffPathStatus] the name-status report for the comparison
-      #
-      # @raise [ArgumentError] if unsupported options are provided
-      #
-      # @raise [ArgumentError] if `from` is `nil` but `to` is not OR if `from` or `to` starts with `"-"`
-      #
-      # @raise [Git::FailedError] if git exits outside the allowed range (exit code > 2)
-      #
-      # @deprecated Use {#diff_path_status} instead. Will be removed in v6.0.0.
-      #
-      # @see #diff_path_status
-      #
-      def diff_name_status(from = 'HEAD', to = nil, opts = {})
-        Git::Deprecation.warn(
-          'Git::Repository#diff_name_status is deprecated and will be removed in v6.0.0. ' \
-          'Use Git::Repository#diff_path_status instead.'
-        )
-        diff_path_status(from, to, opts)
-      end
-
       # Compares the index and the working directory
       #
       # Runs `git diff-files` to list files that differ between the index
@@ -523,35 +482,6 @@ module Git
       module Private
         module_function
 
-        # Resolves the effective path limiter from the options hash
-        #
-        # When `:path_limiter` is present it is used directly and no warning is
-        # emitted. When only `:path` is present a deprecation warning is emitted
-        # and its value is used. Returns `nil` when neither key is present.
-        #
-        # @param opts [Hash] the options hash from {#diff_path_status}
-        #
-        # @option opts [String, Pathname, Array<String, Pathname>, nil] :path_limiter (nil)
-        #   primary path limiter value used as-is when present
-        #
-        # @option opts [String, Pathname, Array<String, Pathname>, nil] :path (nil)
-        #   **deprecated** — fallback path limiter when `:path_limiter` is not provided
-        #
-        # @return [String, Pathname, Array<String, Pathname>, nil]
-        #   the effective path limiter
-        #
-        def resolve_path_limiter(opts)
-          if opts.key?(:path_limiter)
-            opts[:path_limiter]
-          elsif opts.key?(:path)
-            Git::Deprecation.warn(
-              'Git::Repository#diff_path_status :path option is deprecated and will be removed in v6.0.0. ' \
-              'Use :path_limiter instead.'
-            )
-            opts[:path]
-          end
-        end
-
         # Extracts only the patch text from combined diff command output
         #
         # When {Git::Commands::Diff} is called with `patch: true, numstat: true,

data/lib/git/repository/merging.rb

@@ -7,6 +7,7 @@ require 'git/commands/merge_base'
 require 'git/commands/revert/start'
 require 'git/commands/show'
 require 'git/repository/shared_private'
+require 'git/system_call_guard'
 
 module Git
   class Repository
@@ -81,6 +82,10 @@ module Git
       #
       # @raise [Git::FailedError] when git exits with a non-zero exit status
       #
+      # @note On a conflict, the merge is left in progress: the conflicted paths
+      #   are in the index and working tree, and `MERGE_HEAD` is set until the
+      #   caller commits the resolution or aborts the merge.
+      #
       def merge(branch, message = nil, opts = {})
         SharedPrivate.assert_valid_opts!(MERGE_ALLOWED_OPTS, **opts)
 
@@ -126,18 +131,13 @@ module Git
       # branch is checked out, so those failures never leave the repository on
       # `target_branch`. Anything rejected later, such as an option value that is
       # not accepted or a source ref that does not exist, surfaces inside {#merge}
-      # after the checkout and follows the Note below.
+      # after the checkout and leaves the repository checked out on `target_branch`.
       #
       # The `:no_commit` option is not accepted: a merge stopped before its commit
       # would leave `target_branch` unchanged and the restore checkout would carry
       # the staged result onto the original branch. To merge without committing,
       # call {#checkout} and {#merge} directly.
       #
-      # **Note:** the restore checkout is not wrapped in `ensure`. If the merge
-      # fails (for example, on a conflict), the repository is left checked out on
-      # `target_branch` with the merge in progress rather than restored to the
-      # original branch.
-      #
       # @example Merge a feature branch into main while staying on the current branch
       #   repo.merge_into('main', 'feature')
       #
@@ -179,6 +179,12 @@ module Git
       #
       # @raise [Git::FailedError] when git exits with a non-zero exit status
       #
+      # @note If the merge or the restore checkout fails, the repository is left
+      #   checked out on `target_branch` rather than restored to the original
+      #   branch. On a conflict, the merge is also left in progress. When the
+      #   restore checkout is the step that fails, the merge has already been
+      #   committed on `target_branch`.
+      #
       def merge_into(target_branch, branch, message = nil, opts = {})
         SharedPrivate.assert_valid_opts!(MERGE_INTO_ALLOWED_OPTS, **opts)
         raise ArgumentError, 'at least one branch to merge is required' if Array(branch).empty?
@@ -187,6 +193,7 @@ module Git
         restore_point = SharedPrivate.head_restore_point(self)
         checkout(target_branch)
         output = merge(branch, message, opts)
+        # Runs only on success. See ADR-0009.
         checkout(restore_point)
         output
       end
@@ -278,6 +285,9 @@ module Git
       # @raise [Git::FailedError] when `git diff --cached` exits outside the
       #   allowed range (exit code > 2)
       #
+      # @raise [Git::Error] when the staged content cannot be written to a
+      #   temporary file
+      #
       # @yield [file, your_version, their_version] passes conflict details for
       #   each unmerged file
       #
@@ -302,49 +312,6 @@ module Git
         end
       end
 
-      # Iterate over files with merge conflicts, yielding conflict details for each
-      #
-      # For each unmerged file, the staged content for both sides of the conflict
-      # (stage 2 "ours" and stage 3 "theirs") is written to temporary files whose
-      # paths are yielded alongside the file path. The temporary files are deleted
-      # automatically when the block returns.
-      #
-      # @example Inspect conflicting files
-      #   repo.conflicts do |file, your_version, their_version|
-      #     puts "Conflict in #{file}"
-      #     puts File.read(your_version)
-      #     puts File.read(their_version)
-      #   end
-      #
-      # @return [Array<String>] the list of unmerged file paths
-      #
-      # @raise [Git::FailedError] when `git diff --cached` exits outside the
-      #   allowed range (exit code > 2)
-      #
-      # @yield [file, your_version, their_version] passes conflict details for
-      #   each unmerged file
-      #
-      # @yieldparam file [String] path to the conflicting file, relative to the
-      #   working tree
-      #
-      # @yieldparam your_version [String] path to a temporary file containing the
-      #   stage-2 (ours) content for the conflicting file
-      #
-      # @yieldparam their_version [String] path to a temporary file containing the
-      #   stage-3 (theirs) content for the conflicting file
-      #
-      # @yieldreturn [void]
-      #
-      # @deprecated Use {#each_conflict} instead
-      #
-      def conflicts(&)
-        Git::Deprecation.warn(
-          'Git::Repository#conflicts is deprecated and will be removed in v6.0.0. ' \
-          'Use Git::Repository#each_conflict instead.'
-        )
-        each_conflict(&)
-      end
-
       # Option keys accepted by {#revert}
       #
       # Derived from the 4.x option map for `Git::Lib#revert`.
@@ -385,6 +352,12 @@ module Git
       #
       # @raise [Git::FailedError] when git exits with a non-zero exit status
       #
+      # @note On a conflict, the revert is left in progress with the conflicted
+      #   paths in the index and working tree until the caller continues, skips,
+      #   or aborts it. When more than one commit is reverted, the revert commits
+      #   made before the conflict are on the branch; aborting the revert removes
+      #   them again.
+      #
       def revert(commitish = nil, opts = {})
         commitish = 'HEAD' if commitish.nil?
         SharedPrivate.assert_valid_opts!(REVERT_ALLOWED_OPTS, **opts)
@@ -429,6 +402,9 @@ module Git
         #
         # @return [void]
         #
+        # @raise [Git::Error] if the staged content cannot be written to a
+        #   temporary file
+        #
         # @yield [f] yields the open Tempfile containing the staged content
         #
         # @yieldparam f [Tempfile] open IO object for the staged content
@@ -437,11 +413,13 @@ module Git
         #
         # @api private
         #
-        def write_staged_file(execution_context, file_path, stage)
-          Tempfile.create([STAGE_PREFIXES[stage], File.basename(file_path)]) do |f|
-            Git::Commands::Show.new(execution_context).call(":#{stage}:#{file_path}", out: f)
-            f.flush
-            yield f
+        def write_staged_file(execution_context, file_path, stage, &block)
+          Git::SystemCallGuard.call('Failed to write the staged content to a temporary file') do |guard|
+            Tempfile.create([STAGE_PREFIXES[stage], File.basename(file_path)]) do |f|
+              Git::Commands::Show.new(execution_context).call(":#{stage}:#{file_path}", out: f)
+              f.flush
+              guard.unguarded { block.call(f) }
+            end
           end
         end
       end