git 5.2.0 → 5.4.0

data/lib/git/parsers/worktree.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require 'git/worktree_info'
+
+module Git
+  module Parsers
+    # Parser for git worktree command output
+    #
+    # Handles parsing of `git worktree list --porcelain` output into structured
+    # data objects.
+    #
+    # @note Known limitation: git C-quotes a lock or prune reason that contains
+    #   unusual characters such as a newline or a non-ASCII byte (see the
+    #   `--porcelain` description in the git-worktree documentation). The reason
+    #   is returned as git prints it, quotes and escapes included; it is not
+    #   unquoted.
+    #
+    # ## Design Note: Namespace Organization
+    #
+    # This parser creates and returns {Git::WorktreeInfo} objects, which live at
+    # the top-level `Git::` namespace rather than within `Git::Parsers::`. This
+    # is intentional:
+    #
+    # - **Parsers are infrastructure** - marked `@api private`, users shouldn't
+    #   interact with them directly
+    # - **Info classes are public API** - returned by commands and used throughout
+    #   the codebase
+    # - **Info classes are domain entities** - represent core git concepts
+    #   (worktrees as data)
+    #
+    # Keeping Info classes at `Git::` improves discoverability and correctly
+    # reflects their role as public types rather than parser internals.
+    #
+    # @api private
+    #
+    module Worktree
+      # Pattern splitting a porcelain line into its key and optional value
+      #
+      # The key is everything before the first space and the value is everything
+      # after it, so a path or reason that contains spaces is kept intact. The
+      # pattern matches every line; a line with no space has a nil value.
+      LINE_PATTERN = /\A(?<key>[^ ]*)(?: (?<value>.*))?\z/
+
+      # Attribute values for a worktree with no flags set
+      #
+      # @return [Hash{Symbol => Object}]
+      DEFAULT_ATTRS = {
+        head: nil, branch: nil, bare: false, detached: false,
+        locked: false, lock_reason: nil, prunable: false, prune_reason: nil
+      }.freeze
+
+      module_function
+
+      # Parse git worktree list --porcelain output into WorktreeInfo objects
+      #
+      # Records are separated by a blank line. Each record starts with a
+      # `worktree <path>` line followed by any of `HEAD <sha>`, `branch <ref>`,
+      # `bare`, `detached`, `locked [<reason>]`, and `prunable <reason>`.
+      #
+      # @example
+      #   Git::Parsers::Worktree.parse_list(
+      #     "worktree /tmp/wt/main\nHEAD f3e2c1f...\nbranch refs/heads/main\n"
+      #   )
+      #   # => [#<data Git::WorktreeInfo path="/tmp/wt/main", ...>]
+      #
+      # @param stdout [String] output from `git worktree list --porcelain`
+      #
+      # @return [Array<Git::WorktreeInfo>] one entry per worktree, in the order
+      #   git listed them (the main worktree first)
+      #
+      # @raise [Git::UnexpectedResultError] if a record does not start with a
+      #   `worktree` line or contains an unrecognized key
+      #
+      def parse_list(stdout)
+        records(stdout).map { |lines| parse_record(lines, stdout) }
+      end
+
+      # Split the output into records, each an array of chomped non-blank lines
+      #
+      # Blank lines separate records. `chunk` drops every run of lines whose
+      # block value is `:_separator`, so only the non-blank runs are returned.
+      #
+      # @param stdout [String] output from `git worktree list --porcelain`
+      #
+      # @return [Array<Array<String>>] the lines of each record
+      #
+      def records(stdout)
+        stdout.each_line(chomp: true).chunk { |line| line.empty? ? :_separator : true }.map { |_, lines| lines }
+      end
+
+      # Parse one record into a WorktreeInfo
+      #
+      # @param lines [Array<String>] the lines of the record
+      #
+      # @param stdout [String] the full output (for error messages)
+      #
+      # @return [Git::WorktreeInfo] the parsed entry
+      #
+      # @raise [Git::UnexpectedResultError] if the record does not start with a
+      #   `worktree` line or contains an unrecognized key
+      #
+      def parse_record(lines, stdout)
+        key, path = split_line(lines.first)
+        unless key == 'worktree' && path
+          raise Git::UnexpectedResultError,
+                unexpected_line_error(stdout, lines.first, 'expected a record to start with "worktree <path>"')
+        end
+
+        Git::WorktreeInfo.new(path: path, **DEFAULT_ATTRS, **record_attrs(lines.drop(1), stdout))
+      end
+
+      # Collect the attributes set by the lines that follow the `worktree` line
+      #
+      # @param lines [Array<String>] the record's lines after the first
+      #
+      # @param stdout [String] the full output (for error messages)
+      #
+      # @return [Hash{Symbol => Object}] the attributes to override in DEFAULT_ATTRS
+      #
+      # @raise [Git::UnexpectedResultError] if a line has an unrecognized key
+      #
+      def record_attrs(lines, stdout)
+        lines.each_with_object({}) { |line, attrs| attrs.merge!(line_attrs(line, stdout)) }
+      end
+
+      # Map one porcelain line to the WorktreeInfo attributes it sets
+      #
+      # @param line [String] a chomped line of porcelain output
+      #
+      # @param stdout [String] the full output (for error messages)
+      #
+      # @return [Hash{Symbol => Object}] the attributes set by the line
+      #
+      # @raise [Git::UnexpectedResultError] if the line has an unrecognized key
+      #
+      def line_attrs(line, stdout)
+        key, value = split_line(line)
+
+        case key
+        when 'HEAD' then { head: value }
+        when 'branch' then { branch: value }
+        when 'bare' then { bare: true }
+        when 'detached' then { detached: true }
+        when 'locked' then { locked: true, lock_reason: value }
+        when 'prunable' then { prunable: true, prune_reason: value }
+        else raise Git::UnexpectedResultError, unexpected_line_error(stdout, line, 'unrecognized key')
+        end
+      end
+
+      # Split a porcelain line into its key and optional value
+      #
+      # @param line [String] a chomped line of porcelain output
+      #
+      # @return [Array(String, String), Array(String, nil)] the key and the
+      #   value, or nil when the line has no value
+      #
+      def split_line(line)
+        match = LINE_PATTERN.match(line)
+        [match[:key], match[:value]]
+      end
+
+      # Generate the error message for a line the parser cannot handle
+      #
+      # @param stdout [String] the full output
+      #
+      # @param line [String] the problematic line
+      #
+      # @param reason [String] why the line is unexpected
+      #
+      # @return [String] the formatted error message
+      #
+      def unexpected_line_error(stdout, line, reason)
+        <<~ERROR
+          Unexpected line in output from `git worktree list --porcelain`: #{reason}
+
+          Line:
+            "#{line}"
+
+          Full output:
+            #{stdout.gsub("\n", "\n  ")}
+        ERROR
+      end
+    end
+  end
+end

data/lib/git/remote.rb

@@ -7,13 +7,26 @@ module Git
   # A remote in a Git repository
   #
   # Remote objects provide access to remote metadata and operations like fetch,
-  # merge, and remove. They should be obtained via `Git::Repository#remote`,
-  # not constructed directly.
+  # merge, and remove. This class and `Git::Repository#remote`, which returns
+  # it, are both deprecated: read remote configuration through
+  # {Git::Repository::RemoteOperations#remote_list} and call the
+  # repository-level operations with the remote name instead.
   #
-  # @example Getting a remote
+  # @example Reading a remote and fetching from it without Git::Remote
   #   git = Git.open('.')
-  #   remote = git.remote('origin')
-  #   remote.fetch
+  #   origin = git.remote_list.find { |r| r.name == 'origin' }  #=> Git::RemoteInfo
+  #   origin.url.first
+  #   git.fetch(origin.name)
+  #
+  # @deprecated Use {Git::Repository::RemoteOperations#remote_list} and the
+  #   repository-level remote operations instead
+  #
+  #   {Git::Repository::RemoteOperations#remote_list} returns immutable
+  #   {Git::RemoteInfo} value objects. Operations that lived on this class are
+  #   called on the repository with the remote name instead (for example
+  #   {Git::Repository::RemoteOperations#fetch} and
+  #   {Git::Repository::RemoteOperations#remote_remove}). Constructing a
+  #   `Git::Remote` emits a deprecation warning.
   #
   # @api public
   #
@@ -42,13 +55,20 @@ module Git
     #
     # @param name [String] the remote name (e.g. `'origin'`)
     #
-    # @note Use `Git::Repository#remote` instead of constructing directly
+    # @note Do not construct directly. `Git::Repository#remote` is deprecated as
+    #   well; use {Git::Repository::RemoteOperations#remote_list} and the
+    #   repository-level remote operations instead.
     #
     # @api private
     #
     def initialize(base, name)
+      Git::Deprecation.warn(
+        'Git::Remote is deprecated and will be removed in v6.0.0. ' \
+        'Use Git::Repository#remote_list and the repository-level remote operations instead.'
+      )
       @base = base
-      config = remote_repository.config_remote(name)
+      # config_remote is deprecated too; silence it so one Git::Remote.new emits one warning
+      config = Git::Deprecation.silence { remote_repository.config_remote(name) }
       @name = name
       @url = config['url']
       @fetch_opts = config['fetch']
@@ -119,6 +139,16 @@ module Git
     #
     # @return [Git::Branch] a branch object representing `<remote>/<branch>`
     #
+    # @deprecated Use
+    #   `Git::Repository#branch_list("#{name}/#{branch || current_branch}").first`
+    #   instead
+    #
+    #   With no argument this method falls back to the current branch, so the
+    #   replacement has to supply `Git::Repository#current_branch` itself. The
+    #   replacement returns a {Git::BranchInfo} value object rather than a
+    #   {Git::Branch}, and returns `nil` when the remote-tracking branch does
+    #   not exist.
+    #
     def branch(branch = nil)
       branch ||= remote_repository.current_branch
       Git::Branch.new(@base, "#{@name}/#{branch}")

data/lib/git/remote_info.rb

@@ -6,7 +6,11 @@ module Git
   # Each instance holds the parsed configuration for a single remote as read
   # from the repository's git config. Multi-value fields (`:url`, `:push_url`,
   # `:fetch`, `:push`) are always `Array<String>` (never `nil`; may be empty).
-  # All other fields are nilable except `:name`.
+  # Those arrays are frozen copies of the values given, so the set of URLs and
+  # refspecs cannot change after construction; use `with` to derive a modified
+  # copy. The immutability is shallow, as with any `Data` member: the strings
+  # inside those arrays and the scalar members are the objects the caller
+  # passed in, not copies. All other fields are nilable except `:name`.
   #
   # @example Minimal remote (fetch-only, one URL)
   #   info = Git::RemoteInfo.new(
@@ -88,13 +92,13 @@ module Git
     #
     # @param name [String] the name of the remote (required)
     #
-    # @param url [Array<String>] fetch URLs (default `[]`)
+    # @param url [Array<String>] fetch URLs (default `[]`); stored as a frozen copy
     #
-    # @param push_url [Array<String>] push URLs (default `[]`)
+    # @param push_url [Array<String>] push URLs (default `[]`); stored as a frozen copy
     #
-    # @param fetch [Array<String>] fetch refspecs (default `[]`)
+    # @param fetch [Array<String>] fetch refspecs (default `[]`); stored as a frozen copy
     #
-    # @param push [Array<String>] push refspecs (default `[]`)
+    # @param push [Array<String>] push refspecs (default `[]`); stored as a frozen copy
     #
     # @param mirror [Boolean, nil] mirror flag (default `nil`)
     #
@@ -118,7 +122,7 @@ module Git
     #
     # @return [Git::RemoteInfo]
     #
-    def initialize(
+    def initialize( # rubocop:disable Metrics/ParameterLists
       name:,
       url: [],
       push_url: [],
@@ -136,11 +140,64 @@ module Git
       vcs: nil
     )
       super(
-        name:, url: Array(url), push_url: Array(push_url), fetch: Array(fetch),
-        push: Array(push), mirror:, skip_default_update:, tag_opt:, prune:,
-        prune_tags:, receivepack:, uploadpack:, promisor:, partial_clone_filter:,
-        vcs:
+        name:, url: Array(url).dup.freeze, push_url: Array(push_url).dup.freeze,
+        fetch: Array(fetch).dup.freeze, push: Array(push).dup.freeze, mirror:,
+        skip_default_update:, tag_opt:, prune:, prune_tags:, receivepack:, uploadpack:,
+        promisor:, partial_clone_filter:, vcs:
       )
     end
+
+    # Return a copy of this RemoteInfo with the given fields replaced
+    #
+    # Routes through {#initialize} so the multi-value fields of the copy are
+    # frozen copies, the same as on construction. `Data#with` bypasses
+    # `initialize` on Ruby 3.2, which would leave those arrays mutable.
+    #
+    # @example Replace the fetch URL
+    #   info.with(url: ['https://example.com/other.git']).url
+    #   # => ["https://example.com/other.git"]
+    #
+    # @param fields [Hash{Symbol => Object}] the fields to replace, keyed by
+    #   member name
+    #
+    # @option fields [String] :name the name of the remote
+    #
+    # @option fields [Array<String>] :url fetch URLs
+    #
+    # @option fields [Array<String>] :push_url push URLs
+    #
+    # @option fields [Array<String>] :fetch fetch refspecs
+    #
+    # @option fields [Array<String>] :push push refspecs
+    #
+    # @option fields [Boolean, nil] :mirror mirror flag
+    #
+    # @option fields [Boolean, nil] :skip_default_update skip-default-update flag
+    #
+    # @option fields [String, nil] :tag_opt tag-fetching option
+    #
+    # @option fields [Boolean, nil] :prune prune flag
+    #
+    # @option fields [Boolean, nil] :prune_tags prune-tags flag
+    #
+    # @option fields [String, nil] :receivepack receive-pack path
+    #
+    # @option fields [String, nil] :uploadpack upload-pack path
+    #
+    # @option fields [Boolean, nil] :promisor promisor flag
+    #
+    # @option fields [String, nil] :partial_clone_filter partial-clone filter
+    #
+    # @option fields [String, nil] :vcs VCS type
+    #
+    # @return [Git::RemoteInfo] a new instance; `self` when no fields are given
+    #
+    # @raise [ArgumentError] if a key is not a member of this Data class
+    #
+    def with(**fields)
+      return self if fields.empty?
+
+      self.class.new(**to_h, **fields)
+    end
   end
 end

data/lib/git/repository/branching.rb

@@ -187,6 +187,73 @@ module Git
         Git::Commands::Checkout::Branch.new(@execution_context).call(target, **translated_opts).stdout
       end
 
+      # Run a block with the given branch checked out, then restore the original branch
+      #
+      # Records the current branch (or the current commit when HEAD is detached),
+      # checks out `branch`, and yields to the block. If the block returns a truthy
+      # value, all pending changes are committed with `message` (see
+      # {#commit_all}); if it returns a falsy value, the index and working tree are
+      # hard-reset instead (see {#reset}). The original branch or commit is then
+      # checked out again. The hard reset discards changes to tracked files only;
+      # untracked files created by the block are left in place.
+      #
+      # Unlike `Git::Branch#in_branch`, this method does not create `branch`. The
+      # branch must be an existing local branch. Unlike {#checkout}, a commit SHA,
+      # tag, or remote-tracking branch is rejected before any checkout happens:
+      # those detach HEAD, and a commit made there would be left dangling once the
+      # original branch is restored. HEAD must
+      # be on a branch with at least one commit, or detached: an unborn branch (no
+      # commits yet) cannot be checked out again by name, so it is rejected before
+      # any checkout happens.
+      #
+      # **Note:** the restore checkout is not wrapped in `ensure`. If the block,
+      # the commit, or the reset raises an exception, the repository is left
+      # checked out on `branch` rather than restored to the original branch.
+      #
+      # @example Commit a new file on a feature branch
+      #   repo.in_branch('feature', 'Add README') do
+      #     File.write('README.md', '# Hello')
+      #     repo.add('README.md')
+      #     true  # commit and return to the original branch
+      #   end
+      #
+      # @example Discard experimental changes to a tracked file
+      #   repo.in_branch('scratch') do
+      #     File.write('README.md', '# Try something')
+      #     false  # hard-reset and return to the original branch
+      #   end
+      #
+      # @param branch [String] the name of an existing local branch to check out
+      #
+      # @param message [String] the commit message used when the block returns a
+      #   truthy value
+      #
+      # @return [String] git's stdout from the final checkout back to the original
+      #   branch or commit
+      #
+      # @raise [ArgumentError] if `branch` is not an existing local branch
+      #
+      # @raise [Git::Error] if HEAD is on an unborn branch
+      #
+      # @raise [Git::FailedError] if git exits with a non-zero exit status
+      #
+      # @yield executes the block with `branch` checked out
+      #
+      # @yieldreturn [Object] a truthy value to commit all changes, a falsy value to
+      #   hard-reset
+      #
+      def in_branch(branch, message = 'in branch work')
+        SharedPrivate.assert_local_branch!(self, branch)
+        restore_point = SharedPrivate.head_restore_point(self)
+        checkout(branch)
+        if yield
+          commit_all(message)
+        else
+          reset(nil, hard: true)
+        end
+        checkout(restore_point)
+      end
+
       # Populate the working tree from the index
       #
       # @example Check out all files from the index
@@ -630,7 +697,31 @@ module Git
       #
       # @raise [Git::FailedError] if git exits with a non-zero exit status
       #
+      # @deprecated Use `branch_list(name).first` and the name-based branch
+      #   operations instead
+      #
+      #   {#branch_list} returns immutable {Git::BranchInfo} value objects
+      #   rather than {Git::Branch}. It takes `git branch --list` patterns, so
+      #   pass the short name of a local branch or `"#{remote}/#{name}"` for a
+      #   remote-tracking branch; the `remotes/` and `refs/` prefixes this
+      #   method accepts match nothing. A `"#{remote}/#{name}"` pattern also
+      #   matches a local branch of that name, so take `find(&:remote?)` rather
+      #   than `first` for a remote-tracking branch. With no argument this
+      #   method wraps {#current_branch}, which is `'HEAD'` when HEAD is
+      #   detached; {#branch_list} has no entry for a detached or unborn HEAD,
+      #   so use {#current_branch_state} in those states. Call the
+      #   corresponding {Git::Repository} method (e.g. {#checkout},
+      #   {#branch_new}, {#branch_delete}) for operations on a branch.
+      #
+      # @see #branch_list
+      #
       def branch(branch_name = current_branch)
+        Git::Deprecation.warn(
+          'Git::Repository#branch is deprecated and will be removed in v6.0.0. ' \
+          'Use Git::Repository#branch_list(name).first for a local branch, ' \
+          'Git::Repository#branch_list("remote/name").find(&:remote?) for a remote-tracking branch, ' \
+          'and the name-based branch operations instead.'
+        )
         Git::Branch.new(self, branch_name)
       end
 
@@ -657,7 +748,21 @@ module Git
       #
       # @raise [Git::FailedError] if git exits with a non-zero exit status
       #
+      # @deprecated Use {#branch_list} instead
+      #
+      #   {#branch_list} returns `Array<Git::BranchInfo>` (immutable value
+      #   objects) rather than a {Git::Branches} collection. Filter it with
+      #   `select(&:remote?)` or `reject(&:remote?)` in place of
+      #   `branches.remote` and `branches.local`, and look a branch up by name
+      #   with `branch_list(name).first` in place of `branches[name]`.
+      #
+      # @see #branch_list
+      #
       def branches
+        Git::Deprecation.warn(
+          'Git::Repository#branches is deprecated and will be removed in v6.0.0. ' \
+          'Use Git::Repository#branch_list instead.'
+        )
         Git::Branches.new(self)
       end
 
@@ -677,6 +782,11 @@ module Git
         # @param execution_context [Git::ExecutionContext::Repository] the
         #   execution context for git commands
         #
+        # The full `refs/heads/<name>` ref is verified rather than the bare name.
+        # A bare name follows the gitrevisions search order, in which
+        # `refs/tags/<name>` is tried before `refs/heads/<name>`, so an unborn
+        # branch that shares its name with a tag would be reported as `:active`.
+        #
         # @param branch_name [String] the branch name to verify
         #
         # @return [:active, :unborn] the branch ref state
@@ -687,7 +797,7 @@ module Git
         # @api private
         #
         def get_branch_state(execution_context, branch_name)
-          Git::Commands::RevParse.new(execution_context).call(branch_name, verify: true, quiet: true)
+          Git::Commands::RevParse.new(execution_context).call("refs/heads/#{branch_name}", verify: true, quiet: true)
           :active
         rescue Git::FailedError => e
           raise unless e.result.status.exitstatus == 1 && e.result.stderr.empty?

data/lib/git/repository/merging.rb

@@ -10,8 +10,8 @@ require 'git/repository/shared_private'
 
 module Git
   class Repository
-    # Facade methods for merge operations: merging branches into the current branch,
-    # and finding common ancestors between commits
+    # Facade methods for merge operations: merging branches into the current branch
+    # or into another branch, and finding common ancestors between commits
     #
     # Included by {Git::Repository}.
     #
@@ -97,6 +97,100 @@ module Git
         Git::Commands::Merge::Start.new(@execution_context).call(*branches, no_edit: true, **opts).stdout
       end
 
+      # Option keys accepted by {#merge_into}
+      #
+      # The keys accepted by {#merge} except `:no_commit`. A merge stopped before
+      # its commit leaves `target_branch` unchanged, and the restore checkout would
+      # carry the staged merge result onto the original branch instead.
+      MERGE_INTO_ALLOWED_OPTS = %i[no_ff m message].freeze
+      private_constant :MERGE_INTO_ALLOWED_OPTS
+
+      # Merge one or more branches into another branch without leaving the current branch
+      #
+      # Records the current branch (or the current commit when HEAD is detached),
+      # checks out `target_branch`, merges `branch` into it with {#merge}, then
+      # checks out the original branch or commit again. Use {#merge} directly when
+      # the target is the currently checked-out branch.
+      #
+      # `target_branch` must be an existing local branch. Unlike {#checkout}, a
+      # commit SHA, tag, or remote-tracking branch is rejected before any checkout
+      # happens: those detach HEAD, and the merge commit made there would be left
+      # dangling once the original branch is restored while the named ref stayed
+      # unchanged.
+      #
+      # HEAD must be on a branch with at least one commit, or detached: an unborn
+      # branch (no commits yet) cannot be checked out again by name, so it is
+      # rejected before any checkout happens.
+      #
+      # Option keys, the source list, and `target_branch` are checked before any
+      # 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.
+      #
+      # 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')
+      #
+      # @example Merge with a no-fast-forward commit message
+      #   repo.merge_into('main', 'feature', 'Merge feature into main', no_ff: true)
+      #
+      # @example Octopus merge of multiple branches into main
+      #   repo.merge_into('main', %w[feature-a feature-b])
+      #
+      # @param target_branch [String] the name of an existing local branch to
+      #   merge into
+      #
+      # @param branch [#to_s, Array<#to_s>] the branch or branches to merge into
+      #   `target_branch`; accepts the same forms as {#merge}, but must name at
+      #   least one branch
+      #
+      # @param message [String, nil] optional commit message for the merge commit;
+      #   see {#merge} for how it interacts with the `:message` and `:m` options
+      #
+      # @param opts [Hash] additional options forwarded to {#merge}
+      #
+      # @option opts [Boolean, nil] :no_ff (nil) create a merge commit even when
+      #   fast-forward is possible (`--no-ff`)
+      #
+      # @option opts [String] :message (nil) commit message; prefer the `:m` option
+      #
+      # @option opts [String] :m (nil) commit message (`-m` flag)
+      #
+      # @return [String] git's stdout from the merge command
+      #
+      # @raise [ArgumentError] when unsupported options (including `:no_commit`)
+      #   are provided
+      #
+      # @raise [ArgumentError] when `branch` is `nil` or an empty Array
+      #
+      # @raise [ArgumentError] when `target_branch` is not an existing local branch
+      #
+      # @raise [Git::Error] when HEAD is on an unborn branch
+      #
+      # @raise [Git::FailedError] when git exits with a non-zero exit status
+      #
+      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?
+
+        SharedPrivate.assert_local_branch!(self, target_branch)
+        restore_point = SharedPrivate.head_restore_point(self)
+        checkout(target_branch)
+        output = merge(branch, message, opts)
+        checkout(restore_point)
+        output
+      end
+
       # Find common ancestor commit(s) for use in a merge
       #
       # @example Find the common ancestor of two branches