git 5.0.0.beta.2 → 5.0.0.beta.4

data/lib/git/commands/stash/pop.rb

@@ -10,14 +10,6 @@ module Git
       # Like {Apply}, but removes the stash from the stash list after
       # applying, unless there are conflicts.
       #
-      # @note `arguments` block audited against https://git-scm.com/docs/git-stash/2.53.0
-      #
-      # @see Git::Commands::Stash Git::Commands::Stash for usage examples
-      #
-      # @see https://git-scm.com/docs/git-stash git-stash documentation
-      #
-      # @api private
-      #
       # @example Pop the latest stash
       #   Git::Commands::Stash::Pop.new(execution_context).call
       #
@@ -30,6 +22,14 @@ module Git
       # @example Pop quietly
       #   Git::Commands::Stash::Pop.new(execution_context).call(quiet: true)
       #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-stash/2.53.0
+      #
+      # @see Git::Commands::Stash Git::Commands::Stash for usage examples
+      #
+      # @see https://git-scm.com/docs/git-stash git-stash documentation
+      #
+      # @api private
+      #
       class Pop < Git::Commands::Base
         arguments do
           literal 'stash'
@@ -39,9 +39,12 @@ module Git
           operand :stash
         end
 
-        # @!method call(*, **)
+        # @!method call(*, **options)
+        #
+        #   @param options [Hash] command options
         #
-        #   Pop stashed changes
+        #   @option options [Boolean, nil] :index (nil) command option key; see overload docs
+        #     for the full option list
         #
         #   @overload call(**options)
         #
@@ -55,6 +58,8 @@ module Git
         #
         #       Alias: :q
         #
+        #     @return [Git::CommandLine::Result] the result of calling `git stash pop`
+        #
         #   @overload call(stash, **options)
         #
         #     Pop a specific stash
@@ -69,9 +74,13 @@ module Git
         #
         #       Alias: :q
         #
-        #   @return [Git::CommandLineResult] the result of calling `git stash pop`
+        #     @return [Git::CommandLine::Result] the result of calling `git stash pop`
+        #
+        #   @raise [ArgumentError] if unsupported options are provided
+        #
+        #   @raise [Git::FailedError] if git exits with a non-zero exit status
         #
-        #   @raise [Git::FailedError] if the stash does not exist
+        #   @api public
       end
     end
   end

data/lib/git/commands/stash/push.rb

@@ -11,14 +11,6 @@ module Git
       # to HEAD (in the working tree and index). The command takes
       # various options to customize what gets stashed.
       #
-      # @note `arguments` block audited against https://git-scm.com/docs/git-stash/2.53.0
-      #
-      # @see Git::Commands::Stash Git::Commands::Stash for usage examples
-      #
-      # @see https://git-scm.com/docs/git-stash git-stash documentation
-      #
-      # @api private
-      #
       # @example Save all changes with a message
       #   Git::Commands::Stash::Push.new(execution_context).call(message: 'WIP: feature work')
       #
@@ -31,6 +23,14 @@ module Git
       # @example Include untracked files
       #   Git::Commands::Stash::Push.new(execution_context).call(include_untracked: true)
       #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-stash/2.53.0
+      #
+      # @see Git::Commands::Stash Git::Commands::Stash for usage examples
+      #
+      # @see https://git-scm.com/docs/git-stash git-stash documentation
+      #
+      # @api private
+      #
       class Push < Git::Commands::Base
         arguments do
           literal 'stash'
@@ -48,7 +48,12 @@ module Git
           operand :pathspec, repeatable: true
         end
 
-        # @!method call(*, **)
+        # @!method call(*, **options)
+        #
+        #   @param options [Hash] command options
+        #
+        #   @option options [Boolean, nil] :patch (nil) command option key; see overload docs
+        #     for the full option list
         #
         #   @overload call(*pathspec, **options)
         #
@@ -93,9 +98,13 @@ module Git
         #
         #     @option options [Boolean, nil] :pathspec_file_nul (nil) pathspecs in the file are NUL-separated
         #
-        #     @return [Git::CommandLineResult] the result of calling `git stash push`
+        #     @return [Git::CommandLine::Result] the result of calling `git stash push`
+        #
+        #   @raise [ArgumentError] if unsupported options are provided
+        #
+        #   @raise [Git::FailedError] if git exits with a non-zero exit status
         #
-        #     @raise [Git::FailedError] if git exits with a non-zero exit status
+        #   @api public
         #
       end
     end

data/lib/git/commands/stash/show.rb

@@ -11,14 +11,6 @@ module Git
       # stashed contents and the commit back when the stash entry was first
       # created.
       #
-      # @note `arguments` block audited against https://git-scm.com/docs/git-stash/2.53.0
-      #
-      # @see Git::Commands::Stash Git::Commands::Stash for usage examples
-      #
-      # @see https://git-scm.com/docs/git-stash git-stash documentation
-      #
-      # @api private
-      #
       # @example Show numstat for the latest stash
       #   Git::Commands::Stash::Show.new(ctx).call(numstat: true, shortstat: true)
       #
@@ -29,6 +21,14 @@ module Git
       #   Git::Commands::Stash::Show.new(ctx).call(numstat: true, shortstat: true, dirstat: true)
       #   Git::Commands::Stash::Show.new(ctx).call(numstat: true, shortstat: true, dirstat: 'lines,cumulative')
       #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-stash/2.53.0
+      #
+      # @see Git::Commands::Stash Git::Commands::Stash for usage examples
+      #
+      # @see https://git-scm.com/docs/git-stash git-stash documentation
+      #
+      # @api private
+      #
       class Show < Git::Commands::Base
         arguments do
           literal 'stash'
@@ -50,9 +50,12 @@ module Git
           operand :stash
         end
 
-        # @!method call(*, **)
+        # @!method call(*, **options)
+        #
+        #   @param options [Hash] command options
         #
-        #   Show stash diff
+        #   @option options [Boolean, nil] :patch (nil) command option key; see overload docs
+        #     for the full option list
         #
         #   @overload call(**options)
         #
@@ -96,6 +99,8 @@ module Git
         #
         #       Pass `true` for default, or a string like `'lines,cumulative'` for options.
         #
+        #     @return [Git::CommandLine::Result] the result of calling `git stash show`
+        #
         #   @overload call(stash, **options)
         #
         #     Show diff for a specific stash
@@ -140,9 +145,13 @@ module Git
         #
         #       Pass `true` for default, or a string like `'lines,cumulative'` for options.
         #
-        #   @return [Git::CommandLineResult] the result of calling `git stash show`
+        #     @return [Git::CommandLine::Result] the result of calling `git stash show`
+        #
+        #   @raise [ArgumentError] if unsupported options are provided
+        #
+        #   @raise [Git::FailedError] if git exits with a non-zero exit status
         #
-        #   @raise [Git::FailedError] if git returns a non-zero exit status
+        #   @api public
       end
     end
   end

data/lib/git/commands/stash/store.rb

@@ -13,6 +13,12 @@ module Git
       # This command is typically used after {Create} to actually record
       # the stash in the reflog.
       #
+      # @example Store a stash commit
+      #   Git::Commands::Stash::Store.new(execution_context).call('abc123def456')
+      #
+      # @example Store with a custom message
+      #   Git::Commands::Stash::Store.new(execution_context).call('abc123def456', message: 'WIP: feature')
+      #
       # @note `arguments` block audited against https://git-scm.com/docs/git-stash/2.53.0
       #
       # @see Git::Commands::Stash Git::Commands::Stash for usage examples
@@ -21,12 +27,6 @@ module Git
       #
       # @api private
       #
-      # @example Store a stash commit
-      #   Git::Commands::Stash::Store.new(execution_context).call('abc123def456')
-      #
-      # @example Store with a custom message
-      #   Git::Commands::Stash::Store.new(execution_context).call('abc123def456', message: 'WIP: feature')
-      #
       class Store < Git::Commands::Base
         arguments do
           literal 'stash'
@@ -36,12 +36,17 @@ module Git
           operand :commit, required: true
         end
 
-        # @!method call(*, **)
+        # @!method call(*, **options)
         #
-        #   Store a commit in the stash reflog
+        #   @param options [Hash] command options
+        #
+        #   @option options [String] :message (nil) command option key; see overload docs for
+        #     the full option list
         #
         #   @overload call(commit, **options)
         #
+        #     Store a commit in the stash reflog
+        #
         #     @param commit [String] the commit SHA to store in the stash (required)
         #
         #     @param options [Hash] command options
@@ -54,9 +59,13 @@ module Git
         #
         #       Alias: :q
         #
-        #     @return [Git::CommandLineResult] the result of calling `git stash store`
+        #     @return [Git::CommandLine::Result] the result of calling `git stash store`
+        #
+        #   @raise [ArgumentError] if unsupported options are provided
+        #
+        #   @raise [Git::FailedError] if git exits with a non-zero exit status
         #
-        #     @raise [Git::FailedError] if the commit is not a valid stash commit
+        #   @api public
       end
     end
   end

data/lib/git/commands/stash.rb

@@ -28,10 +28,10 @@ module Git
     # - {Stash::Create} — create a stash object without storing it
     # - {Stash::Store} — store a stash object created with `create`
     #
-    # @api private
-    #
     # @see https://git-scm.com/docs/git-stash git-stash documentation
     #
+    # @api private
+    #
     module Stash
     end
   end

data/lib/git/commands/status.rb

@@ -77,7 +77,12 @@ module Git
         operand :pathspec, repeatable: true
       end
 
-      # @!method call(*, **)
+      # @!method call(*, **options)
+      #
+      #   @param options [Hash] command options
+      #
+      #   @option options [Boolean, nil] :short (nil) command option key; see overload docs
+      #     for the full option list
       #
       #   @overload call(*pathspecs, **options)
       #
@@ -157,7 +162,7 @@ module Git
       #       When `true`, enables rename detection without a threshold. When a string
       #       (e.g. `'50'`), adds `--find-renames=<n>`.
       #
-      #     @return [Git::CommandLineResult] the result of calling `git status`
+      #     @return [Git::CommandLine::Result] the result of calling `git status`
       #
       #     @raise [ArgumentError] if unsupported options are provided
       #

data/lib/git/commands/symbolic_ref/delete.rb

@@ -38,30 +38,34 @@ module Git
           operand :name, required: true
         end
 
-        # @!method call(*, **)
+        # Executes the git symbolic-ref --delete command
         #
-        #   @overload call(name, **options)
+        # @overload call(name, **options)
         #
-        #     Execute the `git symbolic-ref --delete` command
+        #   @param name [String] the symbolic ref name to delete
+        #     (e.g. `HEAD`)
         #
-        #     @param name [String] the symbolic ref name to delete
-        #       (e.g. `HEAD`)
+        #   @param options [Hash] command options
         #
-        #     @param options [Hash] command options
+        #   @option options [Boolean, nil] :quiet (nil) suppress error message
+        #     when the name is not a symbolic ref
         #
-        #     @option options [Boolean, nil] :quiet (nil) suppress error message
-        #       when the name is not a symbolic ref
+        #     Alias: :q
         #
-        #       Alias: :q
+        #   @return [Git::CommandLine::Result] the result of calling
+        #     `git symbolic-ref --delete`
         #
-        #     @return [Git::CommandLineResult] the result of calling
-        #       `git symbolic-ref --delete`
+        #   @raise [ArgumentError] if unsupported options are provided
         #
-        #     @raise [ArgumentError] if unsupported options are provided
+        #   @raise [ArgumentError] if the name operand is missing
         #
-        #     @raise [ArgumentError] if the name operand is missing
+        #   @raise [Git::FailedError] if git exits with a non-zero exit status
         #
-        #     @raise [Git::FailedError] if git exits with a non-zero exit status
+        #   @api public
+        #
+        def call(*, **)
+          super
+        end
       end
     end
   end

data/lib/git/commands/symbolic_ref/read.rb

@@ -56,39 +56,43 @@ module Git
         # (e.g. detached HEAD) — this is not an error
         allow_exit_status 0..1
 
-        # @!method call(*, **)
+        # Executes the git symbolic-ref command to read a symbolic ref
         #
-        #   @overload call(name, **options)
+        # @overload call(name, **options)
         #
-        #     Execute the `git symbolic-ref` command to read a symbolic ref
+        #   @param name [String] the symbolic ref name to read
+        #     (e.g. `HEAD`)
         #
-        #     @param name [String] the symbolic ref name to read
-        #       (e.g. `HEAD`)
+        #   @param options [Hash] command options
         #
-        #     @param options [Hash] command options
+        #   @option options [Boolean, nil] :quiet (nil) suppress error message
+        #     when the name is not a symbolic ref
         #
-        #     @option options [Boolean, nil] :quiet (nil) suppress error message
-        #       when the name is not a symbolic ref
+        #     Alias: :q
         #
-        #       Alias: :q
+        #   @option options [Boolean, nil] :short (nil) shorten the ref output
+        #     (e.g. `refs/heads/main` → `main`)
         #
-        #     @option options [Boolean, nil] :short (nil) shorten the ref output
-        #       (e.g. `refs/heads/main` → `main`)
+        #   @option options [Boolean, nil] :recurse (nil) follow chain of symbolic refs
+        #     until result no longer points at a symbolic ref (`--recurse`)
         #
-        #     @option options [Boolean, nil] :recurse (nil) follow chain of symbolic refs
-        #       until result no longer points at a symbolic ref (`--recurse`)
+        #   @option options [Boolean, nil] :no_recurse (nil) stop after a single level
+        #     of dereferencing (`--no-recurse`)
         #
-        #     @option options [Boolean, nil] :no_recurse (nil) stop after a single level
-        #       of dereferencing (`--no-recurse`)
+        #   @return [Git::CommandLine::Result] the result of calling
+        #     `git symbolic-ref`
         #
-        #     @return [Git::CommandLineResult] the result of calling
-        #       `git symbolic-ref`
+        #   @raise [ArgumentError] if unsupported options are provided
         #
-        #     @raise [ArgumentError] if unsupported options are provided
+        #   @raise [ArgumentError] if the name operand is missing
         #
-        #     @raise [ArgumentError] if the name operand is missing
+        #   @raise [Git::FailedError] if git exits outside the allowed range (exit code > 1)
         #
-        #     @raise [Git::FailedError] if git exits outside the allowed range (exit code > 1)
+        #   @api public
+        #
+        def call(*, **)
+          super
+        end
       end
     end
   end

data/lib/git/commands/symbolic_ref/update.rb

@@ -42,34 +42,37 @@ module Git
           operand :ref, required: true
         end
 
-        # @!method call(*, **)
+        # Executes the git symbolic-ref command to create or update a symbolic ref
         #
-        #   @overload call(name, ref, **options)
+        # @overload call(name, ref, **options)
         #
-        #     Execute the `git symbolic-ref` command to create or update a
-        #     symbolic ref
+        #   @param name [String] the symbolic ref name to update
+        #     (e.g. `HEAD`)
         #
-        #     @param name [String] the symbolic ref name to update
-        #       (e.g. `HEAD`)
+        #   @param ref [String] the target ref to point to
+        #     (e.g. `refs/heads/main`)
         #
-        #     @param ref [String] the target ref to point to
-        #       (e.g. `refs/heads/main`)
+        #   @param options [Hash] command options
         #
-        #     @param options [Hash] command options
+        #   @option options [String] :m (nil) a reflog message for
+        #     the update
         #
-        #     @option options [String] :m (nil) a reflog message for
-        #       the update
+        #   @return [Git::CommandLine::Result] the result of calling
+        #     `git symbolic-ref`
         #
-        #     @return [Git::CommandLineResult] the result of calling
-        #       `git symbolic-ref`
+        #   @raise [ArgumentError] if unsupported options are provided
         #
-        #     @raise [ArgumentError] if unsupported options are provided
+        #   @raise [ArgumentError] if the name operand is missing
         #
-        #     @raise [ArgumentError] if the name operand is missing
+        #   @raise [ArgumentError] if the ref operand is missing
         #
-        #     @raise [ArgumentError] if the ref operand is missing
+        #   @raise [Git::FailedError] if git exits with a non-zero exit status
         #
-        #     @raise [Git::FailedError] if git exits with a non-zero exit status
+        #   @api public
+        #
+        def call(*, **)
+          super
+        end
       end
     end
   end

data/lib/git/commands/symbolic_ref.rb

@@ -16,10 +16,6 @@ module Git
     #   at a given branch
     # - {SymbolicRef::Delete} — delete a symbolic ref
     #
-    # @api private
-    #
-    # @see https://git-scm.com/docs/git-symbolic-ref git-symbolic-ref documentation
-    #
     # @example Read the current HEAD
     #   cmd = Git::Commands::SymbolicRef::Read.new(lib)
     #   cmd.call('HEAD')
@@ -32,6 +28,10 @@ module Git
     #   cmd = Git::Commands::SymbolicRef::Delete.new(lib)
     #   cmd.call('HEAD')
     #
+    # @see https://git-scm.com/docs/git-symbolic-ref git-symbolic-ref documentation
+    #
+    # @api private
+    #
     module SymbolicRef
     end
   end

data/lib/git/commands/tag/create.rb

@@ -54,85 +54,88 @@ module Git
           operand :commit
         end
 
-        # @!method call(*, **)
+        # Executes the git tag command to create a new tag
         #
-        #   Execute the git tag command to create a new tag
+        # @overload call(tagname, commit = nil, **options)
         #
-        #   @overload call(tagname, commit = nil, **options)
+        #   @param tagname [String] the name of the tag to create
         #
-        #     @param tagname [String] the name of the tag to create
+        #   @param commit [String, nil] the commit, branch, or object to tag
         #
-        #     @param commit [String, nil] the commit, branch, or object to tag
+        #     Defaults to HEAD when omitted.
         #
-        #       Defaults to HEAD when omitted.
+        #   @param options [Hash] command options
         #
-        #     @param options [Hash] command options
+        #   @option options [Boolean, nil] :annotate (nil) make an unsigned, annotated tag object
         #
-        #     @option options [Boolean, nil] :annotate (nil) make an unsigned, annotated tag object
+        #     Requires a message via `:message` or `:file`.
         #
-        #       Requires a message via `:message` or `:file`.
+        #     Alias: :a
         #
-        #       Alias: :a
+        #   @option options [Boolean, nil] :sign (nil) make a GPG-signed tag using the default signing
+        #     key (`--sign`)
         #
-        #     @option options [Boolean, nil] :sign (nil) make a GPG-signed tag using the default signing
-        #       key (`--sign`)
+        #     Requires a message via `:message` or `:file`.
         #
-        #       Requires a message via `:message` or `:file`.
+        #     Alias: :s
         #
-        #       Alias: :s
+        #   @option options [Boolean, nil] :no_sign (nil) override `tag.gpgSign` config to disable
+        #     signing (`--no-sign`)
         #
-        #     @option options [Boolean, nil] :no_sign (nil) override `tag.gpgSign` config to disable
-        #       signing (`--no-sign`)
+        #   @option options [String] :local_user (nil) make a cryptographically signed tag using the given key
         #
-        #     @option options [String] :local_user (nil) make a cryptographically signed tag using the given key
+        #     Requires a message via `:message` or `:file`.
         #
-        #       Requires a message via `:message` or `:file`.
+        #     Alias: :u
         #
-        #       Alias: :u
+        #   @option options [Boolean, nil] :force (nil) replace an existing tag with the given name instead of failing
         #
-        #     @option options [Boolean, nil] :force (nil) replace an existing tag with the given name instead of failing
+        #     Alias: :f
         #
-        #       Alias: :f
+        #   @option options [String] :message (nil) use the given message as the tag message
         #
-        #     @option options [String] :message (nil) use the given message as the tag message
+        #     Implies `--annotate` if none of `--annotate`, `--sign`, or `--local-user` is given.
         #
-        #       Implies `--annotate` if none of `--annotate`, `--sign`, or `--local-user` is given.
+        #     Alias: :m
         #
-        #       Alias: :m
+        #   @option options [String] :file (nil) take the tag message from the given file
         #
-        #     @option options [String] :file (nil) take the tag message from the given file
+        #     Use `-` to read from standard input. Implies `--annotate` if none of
+        #     `--annotate`, `--sign`, or `--local-user` is given.
         #
-        #       Use `-` to read from standard input. Implies `--annotate` if none of
-        #       `--annotate`, `--sign`, or `--local-user` is given.
+        #     Alias: :F
         #
-        #       Alias: :F
+        #   @option options [Boolean, nil] :edit (nil) open an editor to further edit the tag message (`--edit`)
         #
-        #     @option options [Boolean, nil] :edit (nil) open an editor to further edit the tag message (`--edit`)
+        #     Alias: :e
         #
-        #       Alias: :e
+        #   @option options [Boolean, nil] :no_edit (nil) suppress the editor (`--no-edit`)
         #
-        #     @option options [Boolean, nil] :no_edit (nil) suppress the editor (`--no-edit`)
+        #   @option options [Hash, Array<Array>] :trailer (nil) add trailers to the tag message
         #
-        #     @option options [Hash, Array<Array>] :trailer (nil) add trailers to the tag message
+        #     Can be a Hash `{ 'Key' => 'value' }` or Array of pairs `[['Key', 'value']]`.
+        #     Multiple trailers can be specified.
         #
-        #       Can be a Hash `{ 'Key' => 'value' }` or Array of pairs `[['Key', 'value']]`.
-        #       Multiple trailers can be specified.
+        #   @option options [String] :cleanup (nil) set how the tag message is cleaned up
         #
-        #     @option options [String] :cleanup (nil) set how the tag message is cleaned up
+        #     Must be one of: `verbatim` (no changes), `whitespace` (remove leading/trailing
+        #     whitespace lines), or `strip` (remove whitespace and commentary). Default is `strip`.
         #
-        #       Must be one of: `verbatim` (no changes), `whitespace` (remove leading/trailing
-        #       whitespace lines), or `strip` (remove whitespace and commentary). Default is `strip`.
+        #   @option options [Boolean, nil] :create_reflog (nil) create a reflog for the tag
         #
-        #     @option options [Boolean, nil] :create_reflog (nil) create a reflog for the tag
+        #     Enables date-based sha1 expressions such as `tag@{yesterday}`.
         #
-        #       Enables date-based sha1 expressions such as `tag@{yesterday}`.
+        #   @return [Git::CommandLine::Result] the result of calling `git tag`
         #
-        #     @return [Git::CommandLineResult] the result of calling `git tag`
+        #   @raise [ArgumentError] if unsupported options are provided
         #
-        #     @raise [ArgumentError] if unsupported options are provided
+        #   @raise [Git::FailedError] if git exits with a non-zero exit status
         #
-        #     @raise [Git::FailedError] if git exits with a non-zero exit status
+        #   @api public
         #
+        def call(*, **)
+          super
+        end
       end
     end
   end

data/lib/git/commands/tag/delete.rb

@@ -35,7 +35,7 @@ module Git
         # git tag --delete exits with status 1 when a tag does not exist, which is acceptable
         allow_exit_status 0..1
 
-        # @!method call(*, **)
+        # @!method call(*)
         #
         #   @overload call(*tagname)
         #
@@ -43,12 +43,14 @@ module Git
         #
         #     @param tagname [Array<String>] one or more tag names to delete
         #
-        #     @return [Git::CommandLineResult] the result of calling `git tag --delete`
+        #     @return [Git::CommandLine::Result] the result of calling `git tag --delete`
         #
-        #     @raise [ArgumentError] if no tag names are provided or unsupported options are provided
+        #     @raise [ArgumentError] if no tag names are provided
         #
         #     @raise [Git::FailedError] if git exits outside the allowed range (exit code > 1)
         #
+        #     @api public
+        #
       end
     end
   end