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

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

@@ -62,80 +62,83 @@ module Git
           operand :pattern, repeatable: true
         end
 
-        # @!method call(*, **)
+        # @!method call(*pattern, **options)
         #
-        #   Execute the git tag --list command
+        #   Execute the `git tag --list` command
         #
-        #   @overload call(*pattern, **options)
+        #   @param pattern [Array<String>] shell wildcard patterns to filter tags
         #
-        #     @param pattern [Array<String>] Shell wildcard patterns to filter tags
+        #     Multiple patterns can be provided; a tag is shown if it matches any pattern.
         #
-        #       Multiple patterns can be provided; a tag is shown if it matches any pattern.
+        #   @param options [Hash] command options
         #
-        #     @param options [Hash] command options
+        #   @option options [Boolean, Integer, nil] :n (nil) number of annotation lines to print
         #
-        #     @option options [Boolean, Integer, nil] :n (nil) Number of annotation lines to print
+        #     Pass `true` to print the first annotation line, or an integer to print that
+        #     many lines. If the tag is not annotated, the commit message is displayed instead.
         #
-        #       Pass `true` to print the first annotation line, or an integer to print that
-        #       many lines. If the tag is not annotated, the commit message is displayed instead.
+        #   @option options [String, Array<String>] :sort (nil) sort tags by the specified
+        #     key(s)
         #
-        #     @option options [String, Array<String>] :sort (nil) Sort tags by the specified
-        #       key(s)
+        #     Prefix `-` to sort in descending order. Common keys: 'refname',
+        #     '-refname', 'creatordate', '-creatordate', and 'version:refname'.
         #
-        #       Prefix `-` to sort in descending order. Common keys: 'refname',
-        #       '-refname', 'creatordate', '-creatordate', 'version:refname' (for semantic
-        #       version sorting).
+        #   @option options [Boolean, String, nil] :color (nil) colorize output per colors
+        #     specified in `--format`
         #
-        #     @option options [Boolean, String, nil] :color (nil) Colorize output per colors
-        #       specified in `--format`
+        #     Pass `true` for `--color`, or one of `'always'`, `'never'`, `'auto'`.
         #
-        #       Pass `true` for `--color`, or one of `'always'`, `'never'`, `'auto'`.
+        #   @option options [Boolean, nil] :ignore_case (nil) sort and filter tags without
+        #     case sensitivity
         #
-        #     @option options [Boolean, nil] :ignore_case (nil) Sorting and filtering tags are
-        #       case insensitive
+        #     Alias: :i
         #
-        #       Alias: :i
+        #   @option options [Boolean, nil] :omit_empty (nil) skip trailing newlines for
+        #     refs whose formatted output is empty
         #
-        #     @option options [Boolean, nil] :omit_empty (nil) Do not print a newline after
-        #       formatted refs where the format expands to the empty string
+        #   @option options [Boolean, String, nil] :column (nil) display tag listing in
+        #     columns
         #
-        #     @option options [Boolean, String, nil] :column (nil) Display tag listing in columns
+        #     Pass `true` for `--column` or a comma-separated options string for
+        #     `--column=<options>`.
         #
-        #       Pass `true` for `--column` or a comma-separated options string
-        #       (see `column.tag` configuration for syntax) for `--column=<options>`.
+        #   @option options [Boolean, nil] :no_column (nil) disable column output
+        #     (`--no-column`)
         #
-        #     @option options [Boolean, nil] :no_column (nil) disable column output (`--no-column`)
+        #   @option options [Boolean, String, nil] :contains (nil) list only tags that
+        #     contain the specified commit
         #
-        #     @option options [Boolean, String, nil] :contains (nil) List only tags that contain the
-        #       specified commit
+        #     Pass `true` to use HEAD, or a commit reference string.
         #
-        #       Pass `true` to use HEAD, or a commit reference string.
+        #   @option options [Boolean, String, nil] :no_contains (nil) list only tags that do
+        #     not contain the specified commit
         #
-        #     @option options [Boolean, String, nil] :no_contains (nil) List only tags that don't contain
-        #       the specified commit
+        #     Pass `true` to use HEAD, or a commit reference string.
         #
-        #       Pass `true` to use HEAD, or a commit reference string.
+        #   @option options [Boolean, String, nil] :merged (nil) list only tags whose commits
+        #     are reachable from the specified commit
         #
-        #     @option options [Boolean, String, nil] :merged (nil) List only tags whose commits are
-        #       reachable from the specified commit
+        #     Pass `true` to use HEAD, or a commit reference string.
         #
-        #       Pass `true` to use HEAD, or a commit reference string.
+        #   @option options [Boolean, String, nil] :no_merged (nil) list only tags whose
+        #     commits are not reachable from the specified commit
         #
-        #     @option options [Boolean, String, nil] :no_merged (nil) List only tags whose commits are
-        #       not reachable from the specified commit
+        #     Pass `true` to use HEAD, or a commit reference string.
         #
-        #       Pass `true` to use HEAD, or a commit reference string.
+        #   @option options [Boolean, String, nil] :points_at (nil) list only tags that point
+        #     at the specified object
         #
-        #     @option options [Boolean, String, nil] :points_at (nil) List only tags that point at the
-        #       specified object
+        #     Pass `true` to use HEAD, or an object reference string.
         #
-        #       Pass `true` to use HEAD, or an object reference string.
+        #   @option options [String] :format (nil) output format string for each tag
         #
-        #     @option options [String] :format (nil) Output format string for each tag
+        #   @return [Git::CommandLine::Result] the result of calling `git tag --list`
         #
-        #     @return [Git::CommandLineResult] the result of calling `git tag --list`
+        #   @raise [ArgumentError] if unsupported options are provided
         #
-        #     @raise [Git::FailedError] if git returns a non-zero exit code
+        #   @raise [Git::FailedError] if git exits with a non-zero exit status
+        #
+        #   @api public
         #
       end
     end

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

@@ -42,28 +42,28 @@ module Git
           operand :tagname, repeatable: true, required: true
         end
 
-        # @!method call(*, **)
+        # @!method call(*tagname, **options)
         #
-        #   Execute the git tag --verify command to verify tag signatures
+        #   Execute the `git tag --verify` command to verify tag signatures
         #
-        #   @overload call(*tagname, **options)
+        #   @param tagname [Array<String>] one or more tag names to verify
         #
-        #     @param tagname [Array<String>] one or more tag names to verify
+        #   @param options [Hash] command options
         #
-        #     @param options [Hash] command options
+        #   @option options [String] :format (nil) a format string interpolating
+        #     `%(fieldname)` from the tag ref being shown and the object it points at
         #
-        #     @option options [String] :format (nil) a format string interpolating
-        #       `%(fieldname)` from the tag ref being shown and the object it points at
+        #     The format is the same as that of git-for-each-ref(1)
         #
-        #       The format is the same as that of git-for-each-ref(1).
+        #   @return [Git::CommandLine::Result] the result of calling `git tag --verify`
         #
-        #     @return [Git::CommandLineResult] the result of calling `git tag --verify`
+        #   @raise [ArgumentError] if unsupported options are provided
         #
-        #     @raise [ArgumentError] if unsupported options are provided
+        #   @raise [ArgumentError] if no tagname operands are provided
         #
-        #     @raise [ArgumentError] if no tagname operands 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/tag.rb

@@ -16,10 +16,10 @@ module Git
     # - {Tag::List} — list tags with optional filtering (`--list`)
     # - {Tag::Verify} — verify GPG signatures of tags (`--verify`)
     #
-    # @api private
-    #
     # @see https://git-scm.com/docs/git-tag git-tag documentation
     #
+    # @api private
+    #
     module Tag
     end
   end

data/lib/git/commands/update_ref/batch.rb

@@ -108,7 +108,7 @@ module Git
         #
         #   @option options [Numeric] :timeout (nil) abort the command after this many seconds
         #
-        #   @return [Git::CommandLineResult] the result of calling
+        #   @return [Git::CommandLine::Result] the result of calling
         #     `git update-ref --stdin`
         #
         #   @raise [ArgumentError] if unsupported options are provided
@@ -130,6 +130,11 @@ module Git
 
         private
 
+        # Build stdin payload for `git update-ref --stdin`
+        #
+        # @param bound [Git::Commands::Arguments::Bound] bound command arguments
+        #
+        # @return [String] instruction stream with delimiter applied per `z:`
         def build_stdin(bound)
           delimiter = bound.z? ? "\0" : "\n"
           Array(bound.instructions).map { |i| "#{i}#{delimiter}" }.join

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

@@ -52,40 +52,38 @@ module Git
           operand :oldvalue
         end
 
-        # @!method call(*, **)
+        # @!method call(ref, oldvalue = nil, **options)
         #
-        #   @overload call(ref, oldvalue = nil, **options)
+        #   Execute the `git update-ref -d` command
         #
-        #     Execute the `git update-ref -d` command
+        #   @param ref [String] the ref to delete
+        #     (e.g. `refs/heads/old-branch`)
         #
-        #     @param ref [String] the ref to delete
-        #       (e.g. `refs/heads/old-branch`)
+        #   @param oldvalue [String, nil] (nil) expected current value of the ref
         #
-        #     @param oldvalue [String, nil] (nil) expected current value of
-        #       the ref
+        #     When provided, the delete is rejected unless the ref currently points to this
+        #     object.
         #
-        #       When provided, the delete is rejected unless the ref
-        #       currently points to this object.
+        #   @param options [Hash] command options
         #
-        #     @param options [Hash] command options
+        #   @option options [String] :m (nil) a reflog message for the deletion
         #
-        #     @option options [String] :m (nil) a reflog message for
-        #       the deletion
+        #   @option options [Boolean, nil] :no_deref (nil) overwrite the ref itself rather
+        #     than following symbolic refs
         #
-        #     @option options [Boolean, nil] :no_deref (nil) overwrite the ref
-        #       itself rather than following symbolic refs
+        #   @option options [Numeric] :timeout (nil) abort the command after this many
+        #     seconds
         #
-        #     @option options [Numeric] :timeout (nil) abort the command after this many
-        #       seconds
+        #   @return [Git::CommandLine::Result] the result of calling `git update-ref -d`
         #
-        #     @return [Git::CommandLineResult] the result of calling
-        #       `git update-ref -d`
+        #   @raise [ArgumentError] if unsupported options are provided
         #
-        #     @raise [ArgumentError] if unsupported options are provided
+        #   @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
+        #
+        #   @api public
         #
-        #     @raise [Git::FailedError] if git exits with a non-zero exit status
       end
     end
   end

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

@@ -60,46 +60,43 @@ module Git
           operand :oldvalue
         end
 
-        # @!method call(*, **)
+        # @!method call(ref, newvalue, oldvalue = nil, **options)
         #
-        #   @overload call(ref, newvalue, oldvalue = nil, **options)
+        #   Execute the `git update-ref` command
         #
-        #     Execute the `git update-ref` command
+        #   @param ref [String] the ref to update (e.g. `refs/heads/main`)
         #
-        #     @param ref [String] the ref to update (e.g. `refs/heads/main`)
+        #   @param newvalue [String] the new object name to store
         #
-        #     @param newvalue [String] the new object name to store
+        #   @param oldvalue [String, nil] (nil) expected current value of the ref
         #
-        #     @param oldvalue [String, nil] (nil) expected current value of
-        #       the ref
+        #     When provided, the update is rejected unless the ref currently points to this
+        #     object. Use 40 `"0"` characters or an empty string to assert the ref does
+        #     not yet exist.
         #
-        #       When provided, the update is rejected unless the ref
-        #       currently points to this object. Use 40 `"0"` characters
-        #       or an empty string to assert the ref does not yet exist.
+        #   @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
+        #   @option options [Boolean, nil] :no_deref (nil) overwrite the ref itself rather
+        #     than following symbolic refs
         #
-        #     @option options [Boolean, nil] :no_deref (nil) overwrite the ref
-        #       itself rather than following symbolic refs
+        #   @option options [Boolean, nil] :create_reflog (nil) create a reflog even if one
+        #     would not ordinarily be created
         #
-        #     @option options [Boolean, nil] :create_reflog (nil) create a reflog
-        #       even if one would not ordinarily be created
+        #   @option options [Numeric] :timeout (nil) abort the command after this many
+        #     seconds
         #
-        #     @option options [Numeric] :timeout (nil) abort the command after this many
-        #       seconds
+        #   @return [Git::CommandLine::Result] the result of calling `git update-ref`
         #
-        #     @return [Git::CommandLineResult] the result of calling
-        #       `git update-ref`
+        #   @raise [ArgumentError] if unsupported options are provided
         #
-        #     @raise [ArgumentError] if unsupported options are provided
+        #   @raise [ArgumentError] if the ref or newvalue operand is missing
         #
-        #     @raise [ArgumentError] if the ref or newvalue operand is
-        #       missing
+        #   @raise [Git::FailedError] if git exits with a non-zero exit status
+        #
+        #   @api public
         #
-        #     @raise [Git::FailedError] if git exits with a non-zero exit status
       end
     end
   end

data/lib/git/commands/update_ref.rb

@@ -17,10 +17,6 @@ module Git
     # - {UpdateRef::Batch} — read update/create/delete/verify instructions
     #   from stdin (`--stdin`); all modifications are applied atomically
     #
-    # @api private
-    #
-    # @see https://git-scm.com/docs/git-update-ref git-update-ref documentation
-    #
     # @example Update a branch ref to a new commit SHA
     #   cmd = Git::Commands::UpdateRef::Update.new(lib)
     #   cmd.call('refs/heads/main', 'abc1234')
@@ -36,6 +32,10 @@ module Git
     #     'delete refs/heads/old'
     #   )
     #
+    # @see https://git-scm.com/docs/git-update-ref git-update-ref documentation
+    #
+    # @api private
+    #
     module UpdateRef
     end
   end

data/lib/git/commands/version.rb

@@ -33,25 +33,28 @@ module Git
         flag_option :build_options
       end
 
-      # @!method call(*, **)
+      # @overload call(**options)
       #
-      #   @overload call(**options)
+      #   Execute the `git version` command
       #
-      #     Execute the `git version` command.
+      #   @param options [Hash] command options
       #
-      #     @param options [Hash] command options
+      #   @option options [Numeric, nil] :timeout (nil) the number of seconds to wait
+      #     for the command to complete; if nil, uses the global timeout from
+      #     {Git::Config}; if 0, no timeout is enforced
       #
-      #     @option options [Boolean, nil] :build_options (nil) include build options in the output
+      #   @option options [Boolean, nil] :build_options (nil) include build options in
+      #     the output
       #
-      #     @option options [Numeric, nil] :timeout (nil) the number of seconds to wait
-      #       for the command to complete; if nil, uses the global timeout from
-      #       {Git::Config}; if 0, no timeout is enforced
+      #   @return [Git::CommandLine::Result] the result of calling `git version`
       #
-      #     @return [Git::CommandLineResult] the result of calling `git version`
+      # @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 # rubocop:disable Lint/UselessMethodDefinition
     end
   end
 end

data/lib/git/commands/worktree/add.rb

@@ -49,91 +49,90 @@ module Git
           operand :commit_ish
         end
 
-        # @!method call(*, **)
+        # @overload call(path, commit_ish = nil, **options)
         #
-        #   @overload call(path, commit_ish = nil, **options)
+        #   Create a new linked worktree and check out `commit_ish` into it
         #
-        #     Create a new linked worktree and check out `commit_ish` into it
+        #   @param path [String] filesystem path for the new worktree
         #
-        #     @param path [String] filesystem path for the new worktree
+        #   @param commit_ish [String, nil] (nil) branch, tag, or commit to check out
         #
-        #     @param commit_ish [String, nil] (nil) branch, tag, or commit to check out
+        #     When omitted, git creates a new branch named after the final path
+        #     component and checks it out
         #
-        #       When omitted, git creates a new branch named after the final path
-        #       component and checks it out.
+        #   @param options [Hash] command options
         #
-        #     @param options [Hash] command options
+        #   @option options [Boolean, Integer, nil] :force (nil) override safety guards
         #
-        #     @option options [Boolean, Integer, nil] :force (nil) override safety guards
+        #     Pass `true` or `1` to emit `--force` once. Pass `2` to emit
+        #     `--force --force`, which also allows adding worktrees for locked branches.
         #
-        #       Pass `true` or `1` to emit `--force` once. Pass `2` to emit
-        #       `--force --force`, which also allows adding worktrees for locked branches.
+        #     Alias: :f
         #
-        #       Alias: :f
+        #   @option options [String] :b (nil) create a new branch with this name and
+        #     check it out
         #
-        #     @option options [String] :b (nil) create a new branch with this name
-        #       and check it out
+        #   @option options [String] :B (nil) create or reset a branch with this name and
+        #     check it out
         #
-        #     @option options [String] :B (nil) create or reset a branch with this
-        #       name and check it out
+        #   @option options [Boolean, nil] :detach (nil) check out in detached-HEAD state
         #
-        #     @option options [Boolean, nil] :detach (nil) check out in
-        #       detached-HEAD state
+        #     Alias: :d
         #
-        #       Alias: :d
+        #   @option options [Boolean, nil] :checkout (nil) control whether the working
+        #     tree is checked out after creation (`--checkout`)
         #
-        #     @option options [Boolean, nil] :checkout (nil) control whether the working
-        #       tree is checked out after creation (`--checkout`)
+        #   @option options [Boolean, nil] :no_checkout (nil) suppress the initial
+        #     checkout after worktree creation (`--no-checkout`)
         #
-        #     @option options [Boolean, nil] :no_checkout (nil) suppress the initial
-        #       checkout after worktree creation (`--no-checkout`)
+        #   @option options [Boolean, nil] :guess_remote (nil) base new branch on a
+        #     matching remote-tracking branch (`--guess-remote`)
         #
-        #     @option options [Boolean, nil] :guess_remote (nil) base new branch on a
-        #       matching remote-tracking branch (`--guess-remote`)
+        #     Applied when no `commit_ish` argument is provided.
         #
-        #       Applied when no `commit_ish` argument is provided.
+        #   @option options [Boolean, nil] :no_guess_remote (nil) disable guess-remote
+        #     behavior (`--no-guess-remote`)
         #
-        #     @option options [Boolean, nil] :no_guess_remote (nil) disable guess-remote
-        #       behavior (`--no-guess-remote`)
+        #   @option options [Boolean, nil] :relative_paths (nil) link worktrees using
+        #     relative paths (`--relative-paths`)
         #
-        #     @option options [Boolean, nil] :relative_paths (nil) link worktrees using
-        #       relative paths (`--relative-paths`)
+        #     Overrides the `worktree.useRelativePaths` config option.
         #
-        #       Overrides the `worktree.useRelativePaths` config option.
+        #   @option options [Boolean, nil] :no_relative_paths (nil) use absolute paths for
+        #     worktree links (`--no-relative-paths`)
         #
-        #     @option options [Boolean, nil] :no_relative_paths (nil) use absolute paths
-        #       for worktree links (`--no-relative-paths`)
+        #     Overrides the `worktree.useRelativePaths` config option.
         #
-        #       Overrides the `worktree.useRelativePaths` config option.
+        #   @option options [Boolean, nil] :track (nil) mark the upstream branch for
+        #     tracking (`--track`)
         #
-        #     @option options [Boolean, nil] :track (nil) mark the upstream branch for
-        #       tracking (`--track`)
+        #   @option options [Boolean, nil] :no_track (nil) do not mark the upstream
+        #     branch for tracking (`--no-track`)
         #
-        #     @option options [Boolean, nil] :no_track (nil) do not mark the upstream
-        #       branch for tracking (`--no-track`)
+        #   @option options [Boolean, nil] :lock (nil) lock the worktree immediately after
+        #     creation
         #
-        #     @option options [Boolean, nil] :lock (nil) lock the worktree immediately
-        #       after creation
+        #   @option options [Boolean, nil] :orphan (nil) create an empty worktree
+        #     associated with a new unborn branch
         #
-        #     @option options [Boolean, nil] :orphan (nil) create an empty worktree
-        #       associated with a new unborn branch
+        #   @option options [Boolean, nil] :quiet (nil) suppress informational messages
         #
-        #     @option options [Boolean, nil] :quiet (nil) suppress informational messages
+        #     Alias: :q
         #
-        #       Alias: :q
+        #   @option options [String] :reason (nil) explanation for why the worktree is
+        #     locked
         #
-        #     @option options [String] :reason (nil) explanation for why the worktree
-        #       is locked
+        #     Only meaningful when used with `:lock`.
         #
-        #       Only meaningful when used with `:lock`.
+        #   @return [Git::CommandLine::Result] the result of calling `git worktree add`
         #
-        #     @return [Git::CommandLineResult] the result of calling `git worktree add`
+        # @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
         #
-        #     @api public
+        def call(...) = super # rubocop:disable Lint/UselessMethodDefinition
       end
     end
   end

data/lib/git/commands/worktree/list.rb

@@ -29,35 +29,35 @@ module Git
           value_option :expire
         end
 
-        # @!method call(*, **)
+        # @overload call(**options)
         #
-        #   @overload call(**options)
+        #   List all worktrees attached to the repository
         #
-        #     List all worktrees attached to the repository
+        #   @param options [Hash] command options
         #
-        #     @param options [Hash] command options
+        #   @option options [Boolean, nil] :porcelain (nil) produce machine-readable
+        #     output
         #
-        #     @option options [Boolean, nil] :porcelain (nil) produce machine-readable
-        #       output
+        #   @option options [Boolean, nil] :z (nil) terminate output lines with NUL
+        #     bytes (use with `:porcelain`)
         #
-        #     @option options [Boolean, nil] :z (nil) terminate output lines with NUL
-        #       bytes (use with `:porcelain`)
+        #   @option options [Boolean, nil] :verbose (nil) output additional information
+        #     about worktrees
         #
-        #     @option options [Boolean, nil] :verbose (nil) output additional information
-        #       about worktrees
+        #     Alias: :v
         #
-        #       Alias: :v
+        #   @option options [String] :expire (nil) annotate missing worktrees as
+        #     prunable if older than this time expression
         #
-        #     @option options [String] :expire (nil) annotate missing worktrees as
-        #       prunable if older than this time expression
+        #   @return [Git::CommandLine::Result] the result of calling `git worktree list`
         #
-        #     @return [Git::CommandLineResult] the result of calling `git worktree list`
+        # @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
         #
-        #     @api public
+        def call(...) = super # rubocop:disable Lint/UselessMethodDefinition
       end
     end
   end