git 5.2.0 → 5.3.0

data/lib/git/parsers/stash.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require 'time'
+
+require 'git/author_info'
 require 'git/stash_info'
 
 module Git
@@ -45,10 +48,10 @@ module Git
       # %gs = reflog subject (the stash message)
       # %an = author name
       # %ae = author email
-      # %aI = author date (ISO 8601 format)
+      # %aI = author date (ISO 8601 format, parsed into a Time)
       # %cn = committer name
       # %ce = committer email
-      # %cI = committer date (ISO 8601 format)
+      # %cI = committer date (ISO 8601 format, parsed into a Time)
       STASH_FORMAT = [
         '%H',  # 0: full SHA
         '%h',  # 1: short SHA
@@ -163,7 +166,7 @@ module Git
       # @return [Hash] attributes for StashInfo.new
       #
       def stash_info_attrs(parts, index)
-        core_attrs(parts, index).merge(author_attrs(parts)).merge(committer_attrs(parts))
+        core_attrs(parts, index).merge(author: author_info(parts), committer: committer_info(parts))
       end
 
       # Build core StashInfo attributes from parsed fields
@@ -182,30 +185,60 @@ module Git
         }
       end
 
-      # Build author-related StashInfo attributes from parsed fields
+      # Build the author identity from the parsed fields
       #
       # @param parts [Array<String>] the parsed format fields
       #
-      # @return [Hash<Symbol, String>] author attributes for StashInfo.new
+      # @return [Git::AuthorInfo] the stash author; its `date` is a `Time`
       #
-      def author_attrs(parts)
-        {
-          author_name: parts[Fields::AUTHOR_NAME], author_email: parts[Fields::AUTHOR_EMAIL],
-          author_date: parts[Fields::AUTHOR_DATE]
-        }
+      def author_info(parts)
+        build_author_info(parts[Fields::AUTHOR_NAME], parts[Fields::AUTHOR_EMAIL], parts[Fields::AUTHOR_DATE])
       end
 
-      # Build committer-related StashInfo attributes from parsed fields
+      # Build the committer identity from the parsed fields
       #
       # @param parts [Array<String>] the parsed format fields
       #
-      # @return [Hash<Symbol, String>] committer attributes for StashInfo.new
+      # @return [Git::AuthorInfo] the stash committer; its `date` is a `Time`
       #
-      def committer_attrs(parts)
-        {
-          committer_name: parts[Fields::COMMITTER_NAME], committer_email: parts[Fields::COMMITTER_EMAIL],
-          committer_date: parts[Fields::COMMITTER_DATE]
-        }
+      def committer_info(parts)
+        build_author_info(
+          parts[Fields::COMMITTER_NAME], parts[Fields::COMMITTER_EMAIL], parts[Fields::COMMITTER_DATE]
+        )
+      end
+
+      # Build a Git::AuthorInfo from identity fields
+      #
+      # The date is parsed with `Time.iso8601`, so the UTC offset git emits for
+      # `%aI` and `%cI` is preserved in the resulting `Time`.
+      #
+      # @param name [String] the `%an` or `%cn` field
+      #
+      # @param email [String] the `%ae` or `%ce` field
+      #
+      # @param date [String] the `%aI` or `%cI` field in ISO 8601 format
+      #
+      # @return [Git::AuthorInfo] the identity with `date` as a `Time`
+      #
+      # @raise [Git::UnexpectedResultError] if the date is not a valid ISO 8601 date
+      #
+      def build_author_info(name, email, date)
+        Git::AuthorInfo.new(name: name, email: email, date: parse_date(date))
+      end
+
+      # Parse a `%aI` or `%cI` field into a Time
+      #
+      # @param date [String] the date field in ISO 8601 format
+      #
+      # @return [Time] the parsed time, preserving the UTC offset
+      #
+      # @raise [Git::UnexpectedResultError] if the field is not a valid ISO 8601 date
+      #
+      def parse_date(date)
+        Time.iso8601(date)
+      rescue ArgumentError => e
+        raise Git::UnexpectedResultError,
+              "Unexpected date #{date.inspect} in output from `git stash list`: #{e.message}"
       end
 
       # Extract the stash index from a reflog selector

data/lib/git/parsers/tag.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require 'time'
+
+require 'git/author_info'
 require 'git/tag_info'
 require 'git/tag_delete_result'
 require 'git/tag_delete_failure'
@@ -114,7 +117,7 @@ module Git
       # where <FS> is the unit separator character ("\x1f").
       #
       # For lightweight tags, Git emits empty strings for the tagger fields and message;
-      # these are converted to nil by {#parse_optional_field} and {#parse_message}.
+      # these are converted to nil by {#parse_tagger} and {#parse_message}.
       #
       # @param record [String] a single tag record from git tag --format output
       #
@@ -183,19 +186,62 @@ module Git
       def build_tag_info_object(parts, oid, target_oid)
         Git::TagInfo.new(
           name: parts[0], oid: oid, target_oid: target_oid, objecttype: parts[3],
-          tagger_name: parse_optional_field(parts[4]), tagger_email: parse_optional_field(parts[5]),
-          tagger_date: parse_optional_field(parts[6]), message: parse_message(parts[3], parts[7])
+          tagger: parse_tagger(parts[4], parts[5], parts[6]), message: parse_message(parts[3], parts[7])
         )
       end
 
-      # Parse an optional field, returning nil if empty
+      # Build the tagger identity from the tagger name, email, and date fields
+      #
+      # Git emits empty strings for all three fields when there is no tag object
+      # (lightweight tags) or the tag object has no tagger header, in which case
+      # the tagger is nil. Otherwise the angle brackets git wraps around
+      # `%(taggeremail)` are stripped and the strict ISO 8601
+      # `%(taggerdate:iso8601-strict)` value is parsed into a `Time` that
+      # preserves the UTC offset. A partially populated identity (for example an
+      # empty name with an email and date) is kept as emitted rather than dropped,
+      # and an empty date becomes `nil`.
+      #
+      # @example An annotated tag's tagger
+      #   parse_tagger('John Doe', '<john@example.com>', '2024-01-15T10:30:00-08:00')
+      #   #=> #<data Git::AuthorInfo name="John Doe", email="john@example.com", ...>
+      #
+      # @example A lightweight tag has no tagger
+      #   parse_tagger('', '', '') #=> nil
+      #
+      # @param name [String] the `%(taggername)` field
+      #
+      # @param email [String] the `%(taggeremail)` field, including angle brackets
+      #
+      # @param date [String] the `%(taggerdate:iso8601-strict)` field
+      #
+      # @return [Git::AuthorInfo, nil] the tagger, or nil when all three fields are empty
+      #
+      # @raise [Git::UnexpectedResultError] if a non-empty date is not a valid ISO 8601
+      #   date
+      #
+      def parse_tagger(name, email, date)
+        return nil if [name, email, date].all?(&:empty?)
+
+        Git::AuthorInfo.new(
+          name: name,
+          email: email.delete_prefix('<').delete_suffix('>'),
+          date: date.empty? ? nil : parse_date(date)
+        )
+      end
+
+      # Parse a `%(taggerdate:iso8601-strict)` field into a Time
+      #
+      # @param date [String] the date field in strict ISO 8601 format
       #
-      # @param value [String] the field value
+      # @return [Time] the parsed time, preserving the UTC offset
       #
-      # @return [String, nil] the value or nil if empty
+      # @raise [Git::UnexpectedResultError] if the field is not a valid ISO 8601 date
       #
-      def parse_optional_field(value)
-        value.empty? ? nil : value
+      def parse_date(date)
+        Time.iso8601(date)
+      rescue ArgumentError => e
+        raise Git::UnexpectedResultError,
+              "Unexpected tagger date #{date.inspect} in output from `git tag --list`: #{e.message}"
       end
 
       # Parse message field, returning nil for lightweight tags or empty messages

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