git 5.1.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

@@ -41,7 +41,7 @@ module Git
 
       # Option keys accepted by {#checkout}
       #
-      CHECKOUT_ALLOWED_OPTS = %i[force f new_branch b start_point].freeze
+      CHECKOUT_ALLOWED_OPTS = %i[force f new_branch b start_point orphan].freeze
       private_constant :CHECKOUT_ALLOWED_OPTS
 
       # Option keys accepted by {#checkout_index}
@@ -130,6 +130,9 @@ module Git
       # @example Create a new branch with a name different from the start point
       #   repo.checkout('main', new_branch: 'new-feature')
       #
+      # @example Create and check out an unborn branch with no history
+      #   repo.checkout('gh-pages', orphan: true)
+      #
       # @example Force checkout discarding local changes
       #   repo.checkout('main', force: true)
       #
@@ -151,13 +154,25 @@ module Git
       #
       # @option opts [Boolean, nil] :f (nil) alias for `:force`
       #
+      # @option opts [Boolean, String, nil] :orphan (nil) when `true`, creates a
+      #   new unborn branch named `branch` whose first commit has no parents
+      #
+      #   When a `String`, creates an unborn branch with that name, using
+      #   `branch` as the start point for the working tree and index.
+      #
+      #   `false` and `nil` are both treated as unset. A blank branch name is
+      #   rejected rather than ignored.
+      #
       # @option opts [String, nil] :start_point (nil) the commit or branch to
-      #   start the new branch from; used together with `new_branch: true`
+      #   start the new branch from; used together with `new_branch: true` or
+      #   `orphan: true`
       #
       # @return [String] git's stdout from the checkout
       #
       # @raise [ArgumentError] if unsupported options are provided
       #
+      # @raise [ArgumentError] if `:orphan` is given a blank or missing branch name
+      #
       # @raise [Git::FailedError] if git exits with a non-zero exit status
       #
       def checkout(branch = nil, opts = {})
@@ -172,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
@@ -615,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
 
@@ -642,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
 
@@ -662,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
@@ -672,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?
@@ -680,19 +805,24 @@ module Git
           :unborn
         end
 
-        # Translates legacy checkout options to the new command interface
+        # Translates {#checkout} options to the new command interface
         #
         # Legacy callers passed combinations like:
         #   checkout('branch', new_branch: true, start_point: 'main')
         # which should map to:
         #   checkout('main', b: 'branch')
         #
+        # `orphan: true` follows the same shape, naming the unborn branch:
+        #   checkout('branch', orphan: true, start_point: 'main')
+        # maps to:
+        #   checkout('main', orphan: 'branch')
+        #
         # @param branch [String, nil] the branch argument passed to {#checkout}
         #
         # @param checkout_options [Hash] the raw options passed to {#checkout}
         #
-        # @return [Array] a two-element tuple `[target, options]` containing the
-        #   translated checkout arguments
+        # @return [Array((String, nil), Hash)] a two-element tuple
+        #   `[target, options]` containing the translated checkout arguments
         #
         #   `target` (`String` or `nil`) is the branch or commit to check out.
         #   `options` is a `Hash` of keyword arguments for
@@ -701,15 +831,69 @@ module Git
         # @api private
         #
         def translate_checkout_opts(branch, checkout_options)
+          checkout_options = normalize_orphan_option(checkout_options)
+
           if checkout_options[:new_branch] == true || checkout_options[:b] == true
             [checkout_options[:start_point], checkout_options.except(:new_branch, :b, :start_point).merge(b: branch)]
           elsif checkout_options[:new_branch].is_a?(String)
             [branch, checkout_options.except(:new_branch).merge(b: checkout_options[:new_branch])]
+          elsif checkout_options[:orphan] == true
+            translate_orphan_opts(branch, checkout_options)
           else
             [branch, checkout_options]
           end
         end
 
+        # Normalizes the `:orphan` option, rejecting names that git would never see
+        #
+        # `:orphan` is a value option on the underlying command, so a literal
+        # `false` would be emitted as `--orphan false` and create a branch named
+        # "false". Flag options such as `:force` already ignore `false`; this
+        # gives `:orphan` the same behavior.
+        #
+        # A blank name is rejected rather than dropped: the argument DSL omits
+        # empty values, so `orphan: ''` would otherwise degrade silently into a
+        # plain checkout.
+        #
+        # @param checkout_options [Hash] the raw options passed to {#checkout}
+        #
+        # @return [Hash] the options with a `false` `:orphan` key removed
+        #
+        # @raise [ArgumentError] if `:orphan` is given a blank branch name
+        #
+        # @api private
+        #
+        def normalize_orphan_option(checkout_options)
+          orphan = checkout_options[:orphan]
+          return checkout_options.except(:orphan) if orphan == false
+          raise ArgumentError, 'orphan requires a non-empty branch name' if orphan.is_a?(String) && orphan.strip.empty?
+
+          checkout_options
+        end
+
+        # Translates `orphan: true` into the command's `:orphan` value option
+        #
+        # `orphan: true` names the unborn branch from the positional argument and
+        # takes its start point from `:start_point`, mirroring `new_branch: true`.
+        #
+        # @param branch [String, nil] the branch argument passed to {#checkout}
+        #
+        # @param checkout_options [Hash] the raw options passed to {#checkout}
+        #
+        # @return [Array((String, nil), Hash)] a two-element tuple
+        #   `[target, options]` containing the translated checkout arguments
+        #
+        # @raise [ArgumentError] if `branch` is blank (`nil`, empty, or whitespace
+        #   only), since the unborn branch would otherwise have no name
+        #
+        # @api private
+        #
+        def translate_orphan_opts(branch, checkout_options)
+          raise ArgumentError, 'orphan: true requires a branch name' if branch.to_s.strip.empty?
+
+          [checkout_options[:start_point], checkout_options.except(:start_point).merge(orphan: branch)]
+        end
+
         # Normalizes path specifications for Git commands
         #
         # @param pathspecs [String, Pathname, Array<String, Pathname>, nil]