git 5.0.0.beta.3 → 5.0.0.beta.4

data/lib/git/repository/remote_operations.rb

@@ -17,7 +17,7 @@ module Git
     #
     # Included by {Git::Repository}.
     #
-    # @api public
+    # @api private
     #
     module RemoteOperations # rubocop:disable Metrics/ModuleLength
       # Key normalizations for {#fetch} options
@@ -71,62 +71,60 @@ module Git
       # @example Fetch and include all tags
       #   repo.fetch('origin', tags: true)
       #
-      # @overload fetch(remote = 'origin', opts = {})
+      # @param remote [String, Hash, nil] the remote name or URL to fetch from
       #
-      #   @param remote [String, Hash, nil] the remote name or URL to fetch from
+      #   When a Hash is given it is treated as `opts` and `remote` defaults to
+      #   `nil` (which omits the remote positional argument and lets git use the
+      #   configured default).
       #
-      #     When a Hash is given it is treated as `opts` and `remote` defaults to
-      #     `nil` (which omits the remote positional argument and lets git use the
-      #     configured default).
+      # @param opts [Hash] options for the fetch command
       #
-      #   @param opts [Hash] options for the fetch command
+      # @option opts [Boolean, nil] :all (nil) fetch from all configured remotes
+      #   (`--all`)
       #
-      #   @option opts [Boolean, nil] :all (nil) fetch from all configured remotes
-      #     (`--all`)
+      # @option opts [Boolean, nil] :tags (nil) fetch all tags from the remote
+      #   (`--tags`)
       #
-      #   @option opts [Boolean, nil] :tags (nil) fetch all tags from the remote
-      #     (`--tags`)
+      #   Alias: `:t`
       #
-      #     Alias: `:t`
+      # @option opts [Boolean, nil] :prune (nil) remove remote-tracking references
+      #   that no longer exist on the remote (`--prune`)
       #
-      #   @option opts [Boolean, nil] :prune (nil) remove remote-tracking references
-      #     that no longer exist on the remote (`--prune`)
+      #   Alias: `:p`
       #
-      #     Alias: `:p`
+      # @option opts [Boolean, nil] :prune_tags (nil) remove local tags that no
+      #   longer exist on the remote (`--prune-tags`)
       #
-      #   @option opts [Boolean, nil] :prune_tags (nil) remove local tags that no
-      #     longer exist on the remote (`--prune-tags`)
+      #   Alias: `:P`. The legacy dash-style key `:'prune-tags'` is also accepted
+      #   and normalized automatically.
       #
-      #     Alias: `:P`. The legacy dash-style key `:'prune-tags'` is also accepted
-      #     and normalized automatically.
+      # @option opts [Boolean, nil] :force (nil) override the fast-forward check
+      #   when using explicit refspecs (`--force`)
       #
-      #   @option opts [Boolean, nil] :force (nil) override the fast-forward check
-      #     when using explicit refspecs (`--force`)
+      #   Alias: `:f`
       #
-      #     Alias: `:f`
+      # @option opts [Boolean, nil] :update_head_ok (nil) allow `git fetch` to
+      #   update the branch pointed to by `HEAD` (`--update-head-ok`)
       #
-      #   @option opts [Boolean, nil] :update_head_ok (nil) allow `git fetch` to
-      #     update the branch pointed to by `HEAD` (`--update-head-ok`)
+      #   Alias: `:u`. The legacy dash-style key `:'update-head-ok'` is also
+      #   accepted and normalized automatically.
       #
-      #     Alias: `:u`. The legacy dash-style key `:'update-head-ok'` is also
-      #     accepted and normalized automatically.
+      # @option opts [Boolean, nil] :unshallow (nil) convert a shallow clone into a
+      #   full repository (`--unshallow`)
       #
-      #   @option opts [Boolean, nil] :unshallow (nil) convert a shallow clone into a
-      #     full repository (`--unshallow`)
+      # @option opts [String, Integer] :depth (nil) limit history to N commits from
+      #   each branch tip (`--depth=N`)
       #
-      #   @option opts [String, Integer] :depth (nil) limit history to N commits
-      #     from each branch tip (`--depth=N`)
+      # @option opts [String, Array<String>] :ref (nil) one or more refspecs to
+      #   fetch; forwarded as positional arguments after the remote name. An explicit
+      #   `remote` is required when `:ref` is given.
       #
-      #   @option opts [String, Array<String>] :ref (nil) one or more refspecs to
-      #     fetch; forwarded as positional arguments after the remote name. An
-      #     explicit `remote` is required when `:ref` is given.
+      # @return [String] the merged stdout from the fetch command
       #
-      #   @return [String] the merged stdout from the fetch command
+      # @raise [ArgumentError] when unsupported option keys are provided or `:ref`
+      #   is supplied without an explicit remote
       #
-      #   @raise [ArgumentError] when unsupported option keys are provided or `:ref`
-      #     is supplied without an explicit remote
-      #
-      #   @raise [Git::FailedError] when git exits with a non-zero status
+      # @raise [Git::FailedError] when git exits with a non-zero status
       #
       def fetch(remote = 'origin', opts = {})
         remote, opts = Private.resolve_fetch_target(remote, opts)
@@ -171,29 +169,27 @@ module Git
       # @example Pull allowing unrelated histories
       #   repo.pull('origin', 'main', allow_unrelated_histories: true)
       #
-      # @overload pull(remote = nil, branch = nil, opts = {})
-      #
-      #   @param remote [String, nil] the remote name or URL to pull from
+      # @param remote [String, nil] the remote name or URL to pull from
       #
-      #     When nil, git uses the tracking remote for the current branch.
+      #   When nil, git uses the tracking remote for the current branch.
       #
-      #   @param branch [String, nil] the remote branch name to pull
+      # @param branch [String, nil] the remote branch name to pull
       #
-      #     When nil, git uses the tracking branch for the current branch.
-      #     A branch may not be specified without also specifying a remote.
+      #   When nil, git uses the tracking branch for the current branch.
+      #   A branch may not be specified without also specifying a remote.
       #
-      #   @param opts [Hash] options for the pull command
+      # @param opts [Hash] options for the pull command
       #
-      #   @option opts [Boolean, nil] :allow_unrelated_histories (nil) allow merging
-      #     histories that do not share a common ancestor
-      #     (`--allow-unrelated-histories`)
+      # @option opts [Boolean, nil] :allow_unrelated_histories (nil) allow merging
+      #   histories that do not share a common ancestor
+      #   (`--allow-unrelated-histories`)
       #
-      #   @return [String] the stdout from the pull command
+      # @return [String] the stdout from the pull command
       #
-      #   @raise [ArgumentError] when a branch is given without a remote, or when
-      #     unsupported option keys are provided
+      # @raise [ArgumentError] when a branch is given without a remote, or when
+      #   unsupported option keys are provided
       #
-      #   @raise [Git::FailedError] when git exits with a non-zero status
+      # @raise [Git::FailedError] when git exits with a non-zero status
       #
       def pull(remote = nil, branch = nil, opts = {})
         raise ArgumentError, 'You must specify a remote if a branch is specified' if remote.nil? && !branch.nil?
@@ -240,122 +236,46 @@ module Git
       # @example Mirror all refs to a named remote
       #   repo.push('origin', mirror: true)
       #
-      # @overload push(options = {})
-      #   Push using the current branch's default remote and push configuration
-      #
-      #   @param options [Hash] push options (see option list below)
-      #
-      #   @option options [Boolean, nil] :all (nil) push all branches (`--all`)
-      #
-      #   @option options [Boolean, nil] :mirror (nil) push all refs under
-      #     `refs/` to the remote (`--mirror`)
-      #
-      #     When `:tags` is also given, the separate tags push is suppressed.
-      #
-      #   @option options [Boolean, nil] :tags (nil) push all refs under
-      #     `refs/tags/` in a second `git push` invocation (`--tags`)
-      #
-      #     When `:mirror` is also given, the tags push is suppressed because
-      #     `--mirror` already includes tags.
-      #
-      #   @option options [Boolean, nil] :force (nil) force updates,
-      #     overriding the fast-forward check (`--force`)
-      #
-      #     Alias: `:f`
-      #
-      #   @option options [Boolean, nil] :delete (nil) delete the named refs
-      #     from the remote (`--delete`)
-      #
-      #   @option options [String, Array<String>] :push_option (nil) one or
-      #     more server-side push option values (`--push-option=<value>`,
-      #     repeatable)
-      #
-      #   @return [String] the stdout from the push command
-      #
-      # @overload push(remote, options = {})
-      #   Push to the given remote using the current branch's default push configuration
-      #
-      #   @param remote [String] the remote name or URL to push to
-      #
-      #   @param options [Hash] push options (see option list below)
-      #
-      #   @option options [Boolean, nil] :all (nil) push all branches (`--all`)
-      #
-      #   @option options [Boolean, nil] :mirror (nil) push all refs under
-      #     `refs/` to the remote (`--mirror`)
-      #
-      #     When `:tags` is also given, the separate tags push is suppressed.
+      # @param remote [String, Hash, nil] the remote name or URL to push to
       #
-      #   @option options [Boolean, nil] :tags (nil) push all refs under
-      #     `refs/tags/` in a second `git push` invocation (`--tags`)
+      #   When a Hash is given it is treated as `opts` and `remote` defaults to
+      #   `nil` so git uses the configured default push target.
       #
-      #     When `:mirror` is also given, the tags push is suppressed because
-      #     `--mirror` already includes tags.
+      # @param branch [String, Hash, nil] the branch name or refspec to push
       #
-      #   @option options [Boolean, nil] :force (nil) force updates,
-      #     overriding the fast-forward check (`--force`)
+      #   When a Hash is given it is treated as `opts` and `branch` defaults to
+      #   `nil`. A branch may not be specified without also specifying a remote.
       #
-      #     Alias: `:f`
+      # @param opts [Hash, Boolean, nil] options for the push command
       #
-      #   @option options [Boolean, nil] :delete (nil) delete the named refs
-      #     from the remote (`--delete`)
+      #   For backward compatibility, a Boolean is interpreted as
+      #   `tags: <Boolean>`.
       #
-      #   @option options [String, Array<String>] :push_option (nil) one or
-      #     more server-side push option values (`--push-option=<value>`,
-      #     repeatable)
+      # @option opts [Boolean, nil] :all (nil) push all branches (`--all`)
       #
-      #   @return [String] the stdout from the push command
+      # @option opts [Boolean, nil] :mirror (nil) push all refs under `refs/` to
+      #   the remote (`--mirror`)
       #
-      # @overload push(remote, branch, options = {})
-      #   Push a branch or refspec to the given remote
+      # @option opts [Boolean, nil] :tags (nil) push all refs under `refs/tags/`
+      #   in a second `git push` invocation (`--tags`)
       #
-      #   @param remote [String] the remote name or URL to push to
+      #   When `:mirror` is also given, the tags push is suppressed because
+      #   `--mirror` already includes tags.
       #
-      #   @param branch [String] the branch name or refspec to push
+      # @option opts [Boolean, nil] :force (nil) force updates, overriding the
+      #   fast-forward check (`--force`)
       #
-      #   @param options [Hash] push options (see option list below)
+      #   Alias: `:f`
       #
-      #   @option options [Boolean, nil] :all (nil) push all branches (`--all`)
+      # @option opts [Boolean, nil] :delete (nil) delete the named refs from the
+      #   remote (`--delete`)
       #
-      #   @option options [Boolean, nil] :mirror (nil) push all refs under
-      #     `refs/` to the remote (`--mirror`)
+      # @option opts [String, Array<String>] :push_option (nil) one or more
+      #   server-side push option values (`--push-option=<value>`, repeatable)
       #
-      #     When `:tags` is also given, the separate tags push is suppressed.
+      # @return [String] the stdout from the push command
       #
-      #   @option options [Boolean, nil] :tags (nil) push all refs under
-      #     `refs/tags/` in a second `git push` invocation (`--tags`)
-      #
-      #     When `:mirror` is also given, the tags push is suppressed because
-      #     `--mirror` already includes tags.
-      #
-      #   @option options [Boolean, nil] :force (nil) force updates,
-      #     overriding the fast-forward check (`--force`)
-      #
-      #     Alias: `:f`
-      #
-      #   @option options [Boolean, nil] :delete (nil) delete the named refs
-      #     from the remote (`--delete`)
-      #
-      #   @option options [String, Array<String>] :push_option (nil) one or
-      #     more server-side push option values (`--push-option=<value>`,
-      #     repeatable)
-      #
-      #   @return [String] the stdout from the push command
-      #
-      #   @raise [ArgumentError] if `remote` is nil when `branch` is given
-      #
-      # @overload push(remote, branch, tags)
-      #   Backward-compatible shorthand for `push(remote, branch, tags: tags)`
-      #
-      #   @param remote [String] the remote name or URL to push to
-      #
-      #   @param branch [String] the branch name or refspec to push
-      #
-      #   @param tags [Boolean] whether to push all tags; equivalent to `tags: tags`
-      #
-      #   @return [String] the stdout from the push command
-      #
-      #   @raise [ArgumentError] if a branch is given and remote is nil
+      # @raise [ArgumentError] when `branch` is given without `remote`
       #
       # @raise [ArgumentError] when unsupported option keys are provided
       #
@@ -425,8 +345,6 @@ module Git
         Git::Remote.new(self, name)
       end
 
-      # @deprecated Use {#remote_add} instead.
-      #
       # @param name [String] the name for the new remote
       #
       # @param url [String, Git::Repository] the URL of the remote repository
@@ -451,6 +369,8 @@ module Git
       #
       # @raise [Git::FailedError] when git exits with a non-zero status
       #
+      # @deprecated Use {#remote_add} instead
+      #
       def add_remote(name, url, opts = {})
         Git::Deprecation.warn(
           'Git::Repository#add_remote is deprecated and will be removed in v6.0.0. ' \
@@ -469,7 +389,7 @@ module Git
       #
       # @param name [String] the name of the remote to remove
       #
-      # @return [Git::CommandLineResult] the result of calling `git remote remove`
+      # @return [Git::CommandLine::Result] the result of calling `git remote remove`
       #
       # @raise [Git::FailedError] when git exits with a non-zero status
       #
@@ -477,14 +397,14 @@ module Git
         Git::Commands::Remote::Remove.new(@execution_context).call(name)
       end
 
-      # @deprecated Use {#remote_remove} instead.
-      #
       # @param name [String] the name of the remote to remove
       #
-      # @return [Git::CommandLineResult] the result of calling `git remote remove`
+      # @return [Git::CommandLine::Result] the result of calling `git remote remove`
       #
       # @raise [Git::FailedError] when git exits with a non-zero status
       #
+      # @deprecated Use {#remote_remove} instead
+      #
       def remove_remote(name)
         Git::Deprecation.warn(
           'Git::Repository#remove_remote is deprecated and will be removed in v6.0.0. ' \
@@ -522,8 +442,6 @@ module Git
         Git::Remote.new(self, name)
       end
 
-      # @deprecated Use {#remote_set_url} instead.
-      #
       # @param name [String] the name of the remote to update
       #
       # @param url [String, Git::Repository] the new URL for the remote
@@ -535,6 +453,8 @@ module Git
       #
       # @raise [Git::FailedError] when git exits with a non-zero status
       #
+      # @deprecated Use {#remote_set_url} instead
+      #
       def set_remote_url(name, url)
         Git::Deprecation.warn(
           'Git::Repository#set_remote_url is deprecated and will be removed in v6.0.0. ' \
@@ -665,12 +585,6 @@ module Git
       #   # => {"head"=>{ref: "HEAD", sha: "abc123"},
       #   #     "branches"=>{"main"=>{ref: "refs", sha: "abc123"}}}
       #
-      # @note The `:ref` value in each pair is only the **first path segment** of the
-      #   full git ref (e.g. `"refs"` for `refs/heads/main`), not the complete ref
-      #   path. This matches the behavior of 4.x. See
-      #   [issue 1416](https://github.com/ruby-git/ruby-git/issues/1416) for the
-      #   planned fix.
-      #
       # @example List all refs from a named remote
       #   repo.ls_remote('origin')
       #   # => {"head"=>..., "branches"=>..., "tags"=>...}
@@ -708,6 +622,12 @@ module Git
       #
       # @raise [Git::FailedError] if git exits outside the allowed range (exit code > 2)
       #
+      # @note The `:ref` value in each pair is only the **first path segment** of the
+      #   full git ref (e.g. `"refs"` for `refs/heads/main`), not the complete ref
+      #   path. This matches the behavior of 4.x. See
+      #   [issue 1416](https://github.com/ruby-git/ruby-git/issues/1416) for the
+      #   planned fix.
+      #
       def ls_remote(location = nil, opts = {})
         SharedPrivate.assert_valid_opts!(LS_REMOTE_ALLOWED_OPTS, **opts)
         repository = location || '.'
@@ -730,8 +650,14 @@ module Git
         # would otherwise be silently promoted to the remote-name slot) is rejected.
         #
         # @param remote [String, Hash, nil] the remote name, or an options hash
+        #
         # @param opts [Hash] the options hash when remote is given positionally
         #
+        # @option opts [String, Array<String>, nil] :ref (nil) one or more refspecs
+        #   forwarded after the remote name
+        #
+        #   Requires an explicit `remote`.
+        #
         # @return [Array(String, Hash), Array(nil, Hash)] the resolved remote and opts
         #
         # @raise [ArgumentError] when :ref is supplied without an explicit remote
@@ -757,6 +683,11 @@ module Git
         #
         # @param opts [Hash] the raw options hash passed by the caller
         #
+        # @option opts [Object] :'prune-tags' a legacy dash-style fetch option value
+        #
+        # @option opts [Object] :'update-head-ok' a legacy dash-style fetch option
+        #   value
+        #
         # @return [Hash] a new hash with all applicable keys normalized
         #
         # @api private
@@ -777,10 +708,25 @@ module Git
         #   `{ tags: opts }` for backward compatibility
         #
         # @param remote [String, Hash, nil] remote name, URL, or opts hash
+        #
         # @param branch [String, Hash, nil] branch/refspec, or opts hash
+        #
         # @param opts [Hash, Boolean, nil] options hash or legacy Boolean shorthand
         #
-        # @return [Array(String|nil, String|nil, Hash)] normalized [remote, branch, opts]
+        # @option opts [Boolean, nil] :all (nil) push all branches
+        #
+        # @option opts [Boolean, nil] :mirror (nil) mirror all refs
+        #
+        # @option opts [Boolean, nil] :tags (nil) push all tags
+        #
+        # @option opts [Boolean, nil] :delete (nil) delete refs on the remote
+        #
+        # @option opts [Boolean, nil] :force (nil) force updates
+        #
+        # @option opts [String, Array<String>] :push_option (nil) one or more
+        #   push-option values
+        #
+        # @return [Array((String, nil), (String, nil), Hash)] normalized [remote, branch, opts]
         #
         # @api private
         #
@@ -809,11 +755,25 @@ module Git
         # {push_tags_separately?} is true.
         #
         # @param execution_context [Git::ExecutionContext::Repository] the repository execution context
+        #
         # @param remote [String, nil] remote name or URL
+        #
         # @param branch [String, nil] branch or refspec
+        #
         # @param opts [Hash] push options (`:tags` key will be stripped)
         #
-        # @return [Git::CommandLineResult]
+        # @option opts [Boolean, nil] :all (nil) push all branches
+        #
+        # @option opts [Boolean, nil] :mirror (nil) mirror all refs
+        #
+        # @option opts [Boolean, nil] :delete (nil) delete refs on the remote
+        #
+        # @option opts [Boolean, nil] :force (nil) force updates
+        #
+        # @option opts [String, Array<String>] :push_option (nil) one or more
+        #   push-option values
+        #
+        # @return [Git::CommandLine::Result]
         #
         # @api private
         #
@@ -830,6 +790,11 @@ module Git
         #
         # @param opts [Hash] the normalized push options
         #
+        # @option opts [Boolean, nil] :tags (nil) request a separate tags push
+        #
+        # @option opts [Boolean, nil] :mirror (nil) indicates refs are mirrored and
+        #   tags are already covered
+        #
         # @return [Boolean]
         #
         # @api private
@@ -841,10 +806,17 @@ module Git
         # Issue the tags push (second push when `:tags` is requested without `:mirror`)
         #
         # @param execution_context [Git::ExecutionContext::Repository] the repository execution context
+        #
         # @param remote [String, nil] remote name or URL
+        #
         # @param opts [Hash] push options (`:tags` key included to emit `--tags`)
         #
-        # @return [Git::CommandLineResult]
+        # @option opts [Boolean, nil] :tags (nil) emit `--tags`
+        #
+        # @option opts [String, Array<String>] :push_option (nil) one or more
+        #   push-option values
+        #
+        # @return [Git::CommandLine::Result]
         #
         # @api private
         #
@@ -859,6 +831,13 @@ module Git
         #
         # @param opts [Hash] the raw options hash passed by the caller
         #
+        # @option opts [Boolean, nil] :with_fetch (nil) deprecated alias for
+        #   immediate fetch behavior
+        #
+        # @option opts [Boolean, nil] :fetch (nil) fetch from the remote after adding
+        #
+        # @option opts [String, nil] :track (nil) track the given branch during fetch
+        #
         # @return [Hash] a new hash with all applicable keys normalized
         #
         # @api private

data/lib/git/repository/shared_private.rb

@@ -17,7 +17,7 @@ module Git
     module SharedPrivate
       module_function
 
-      # Validate that `options` contains only keys listed in `allowed`
+      # Validate that candidate option keys are listed in `allowed`
       #
       # Used by facade methods to enforce that only documented options (those
       # named in `@option` tags) are accepted, even when the underlying command
@@ -32,14 +32,16 @@ module Git
       #
       # @param allowed [Array<Symbol>] the keys permitted by the facade method
       #
-      # @param options [Hash] the options hash provided by the caller
+      # @param candidate_keywords [Hash<Symbol, Object>] the keywords to validate
+      #
+      # @option candidate_keywords [Object] key_name a candidate keyword value
       #
       # @return [void]
       #
-      # @raise [ArgumentError] when `options` contains any key not in `allowed`
+      # @raise [ArgumentError] when any candidate key is not in `allowed`
       #
-      def assert_valid_opts!(allowed, **options)
-        unknown = options.keys - allowed
+      def assert_valid_opts!(allowed, **candidate_keywords)
+        unknown = candidate_keywords.keys - allowed
         return if unknown.empty?
 
         raise ArgumentError, "Unknown options: #{unknown.join(', ')}"

data/lib/git/repository/staging.rb

@@ -19,7 +19,7 @@ module Git
     #
     # Included by {Git::Repository}.
     #
-    # @api public
+    # @api private
     #
     module Staging
       # Option keys accepted by {#add}
@@ -94,25 +94,28 @@ module Git
 
       # Reset the current HEAD to a specified state with `--hard`
       #
-      # @deprecated Use {#reset} with `hard: true` instead.
+      # @example Hard reset to HEAD
+      #   repo.reset_hard
       #
-      #   @example Hard reset to HEAD
-      #     repo.reset_hard
-      #
-      #   @example Hard reset to a specific commit
-      #     repo.reset_hard('HEAD~1')
+      # @example Hard reset to a specific commit
+      #   repo.reset_hard('HEAD~1')
       #
       # @param commitish [String, nil] the commit or tree-ish to reset to;
       #   defaults to HEAD when `nil`
       #
       # @param opts [Hash] options passed through to {#reset}
       #
+      # @option opts [Boolean, nil] :hard (nil) ignored; this method always forces
+      #   `hard: true`
+      #
       # @return [String] git's stdout from the reset
       #
       # @raise [ArgumentError] when unsupported options are provided
       #
       # @raise [Git::FailedError] when git exits with a non-zero exit status
       #
+      # @deprecated Use {#reset} with `hard: true` instead
+      #
       def reset_hard(commitish = nil, opts = {})
         Git::Deprecation.warn(
           'Git::Repository::Staging#reset_hard is deprecated and will be removed in a future version. ' \
@@ -421,29 +424,47 @@ module Git
         #
         # @param opts [Hash] the caller-provided clean options
         #
+        # @option opts [Boolean, nil] :ff (nil) deprecated alias for requesting a
+        #   double-force clean
+        #
+        # @option opts [Boolean, nil] :force_force (nil) deprecated alias for
+        #   requesting a double-force clean
+        #
+        # @option opts [Boolean, Integer, nil] :force (nil) existing force value
+        #   merged with deprecated options when present
+        #
         # @return [Hash] a new options hash with deprecated keys translated
         #
         # @raise [ArgumentError] when a deprecated value is not `true`, `false`, or `nil`
         #
         def migrate_clean_legacy_options(opts)
-          opts = deprecate_clean_option(opts, :ff, ':ff option is deprecated. Use force: 2 instead.')
-          deprecate_clean_option(opts, :force_force, ':force_force option is deprecated. Use force: 2 instead.')
+          opts = deprecate_clean_option(:ff, ':ff option is deprecated. Use force: 2 instead.', opts)
+          deprecate_clean_option(:force_force, ':force_force option is deprecated. Use force: 2 instead.', opts)
         end
 
         # Translate a single deprecated clean option key onto `:force`
         #
-        # @param opts [Hash] the clean options
-        #
         # @param key [Symbol] the deprecated option key (`:ff` or `:force_force`)
         #
         # @param message [String] the deprecation message to emit
         #
+        # @param opts [Hash] the clean options
+        #
+        # @option opts [Boolean, nil] :ff (nil) deprecated alias for requesting a
+        #   double-force clean
+        #
+        # @option opts [Boolean, nil] :force_force (nil) deprecated alias for
+        #   requesting a double-force clean
+        #
+        # @option opts [Boolean, Integer, nil] :force (nil) existing force value
+        #   updated when the deprecated key is true
+        #
         # @return [Hash] a new options hash with the deprecated key removed
         #
         # @raise [ArgumentError] when the deprecated value is not `true`, `false`,
         #   or `nil`
         #
-        def deprecate_clean_option(opts, key, message)
+        def deprecate_clean_option(key, message, opts)
           return opts unless opts.key?(key)
 
           opts = opts.dup
@@ -461,6 +482,9 @@ module Git
         #
         # @param opts [Hash] the clean options
         #
+        # @option opts [Boolean, Integer, nil] :force (nil) the clean force value
+        #   to inspect
+        #
         # @return [Boolean] true if `:force` was set to a non-nil value, false
         #   otherwise
         #