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

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

@@ -57,105 +57,121 @@ module Git
           operand :pattern, repeatable: true
         end
 
-        # @!method call(*, **)
+        # @overload call(*pattern, **options)
         #
-        #   @overload call(*pattern, **options)
+        #   Execute the `git branch --list` command
         #
-        #     Execute the `git branch --list` command
+        #   @param pattern [Array<String>] shell wildcard patterns to filter branches
         #
-        #     @param pattern [Array<String>] shell wildcard patterns to filter branches
+        #     If multiple patterns are given, a branch is shown if it matches any
+        #     of the patterns
         #
-        #       If multiple patterns are given, a branch is shown if it matches any of the patterns.
+        #   @param options [Hash] command options
         #
-        #     @param options [Hash] command options
+        #   @option options [Boolean, String, nil] :color (nil) color branches output
         #
-        #     @option options [Boolean, String, nil] :color (nil) color branches output
+        #     Pass `true` for `--color` or a string (`'always'`, `'never'`,
+        #     `'auto'`) for `--color=<when>`
         #
-        #       Pass `true` for `--color` or a string (`'always'`, `'never'`, `'auto'`) for `--color=<when>`.
+        #   @option options [Boolean, nil] :no_color (nil) suppress colored output
+        #     (`--no-color`)
         #
-        #     @option options [Boolean, nil] :no_color (nil) suppress colored output (`--no-color`)
+        #   @option options [Boolean, Integer, nil] :verbose (nil) show sha1 and
+        #     commit subject for each branch
         #
-        #     @option options [Boolean, Integer, nil] :verbose (nil) show sha1 and commit
-        #       subject for each branch
+        #     Pass `true` for `--verbose` (show sha1 and subject); pass `2` for
+        #     `--verbose --verbose` (also show the linked worktree path and
+        #     upstream branch name)
         #
-        #       Pass `true` for `--verbose` (show sha1 and subject); pass `2` for
-        #       `--verbose --verbose` (also show the linked worktree path and upstream
-        #       branch name).
+        #     Alias: :v
         #
-        #       Alias: :v
+        #   @option options [Boolean, Integer, nil] :abbrev (nil) minimum sha1
+        #     display length when used with verbose mode
         #
-        #     @option options [Boolean, Integer, nil] :abbrev (nil) minimum sha1 display
-        #       length when used with verbose mode
+        #     Pass an integer for `--abbrev=<n>` or `true` for `--abbrev`
+        #     (default length)
         #
-        #       Pass an integer for `--abbrev=<n>` or `true` for `--abbrev` (default length).
+        #   @option options [Boolean, nil] :no_abbrev (nil) show full sha1s
+        #     (`--no-abbrev`)
         #
-        #     @option options [Boolean, nil] :no_abbrev (nil) show full sha1s (`--no-abbrev`)
+        #   @option options [Boolean, String, nil] :column (nil) display branch
+        #     listing in columns
         #
-        #     @option options [Boolean, String, nil] :column (nil) display branch listing in
-        #       columns
+        #     Pass `true` for `--column` or a string of options for
+        #     `--column=<options>`
         #
-        #       Pass `true` for `--column` or a string of options for `--column=<options>`.
-        #       Only applicable in non-verbose mode.
+        #     Only applicable in non-verbose mode
         #
-        #     @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 [String, Array<String>] :sort (nil) sort branches by the
-        #       specified key(s)
+        #   @option options [String, Array<String>] :sort (nil) sort branches by
+        #     the specified key(s)
         #
-        #       Give an array to add multiple --sort options. Prefix each key with '-' for
-        #       descending order. For example, sort: ['refname', '-committerdate'].
+        #     Give an array to add multiple --sort options
+        #     Prefix each key with '-' for descending order
+        #     For example, sort: ['refname', '-committerdate']
         #
-        #     @option options [Boolean, String, nil] :merged (nil) list only branches merged
-        #       into the specified commit
+        #   @option options [Boolean, String, nil] :merged (nil) list only branches
+        #     merged into the specified commit
         #
-        #       Pass `true` to default to HEAD or a commit ref string to filter by
-        #       that commit.
+        #     Pass `true` to default to HEAD or a commit ref string to filter by
+        #     that commit
         #
-        #     @option options [Boolean, String, nil] :no_merged (nil) list only branches not
-        #       merged into the specified commit
+        #   @option options [Boolean, String, nil] :no_merged (nil) list only
+        #     branches not merged into the specified commit
         #
-        #       Pass `true` to default to HEAD or a commit ref string to filter by
-        #       that commit.
+        #     Pass `true` to default to HEAD or a commit ref string to filter by
+        #     that commit
         #
-        #     @option options [Boolean, String, nil] :contains (nil) list only branches that
-        #       contain the specified commit
+        #   @option options [Boolean, String, nil] :contains (nil) list only
+        #     branches that contain the specified commit
         #
-        #       Pass `true` to default to HEAD or a commit ref string to filter by
-        #       that commit.
+        #     Pass `true` to default to HEAD or a commit ref string to filter by
+        #     that commit
         #
-        #     @option options [Boolean, String, nil] :no_contains (nil) list only branches
-        #       that don't contain the specified commit
+        #   @option options [Boolean, String, nil] :no_contains (nil) list only
+        #     branches that don't contain the specified commit
         #
-        #       Pass `true` to default to HEAD or a commit ref string to filter by
-        #       that commit.
+        #     Pass `true` to default to HEAD or a commit ref string to filter by
+        #     that commit
         #
-        #     @option options [String] :points_at (nil) list only branches that point
-        #       at the specified object
+        #   @option options [String] :points_at (nil) list only branches that
+        #     point at the specified object
         #
-        #     @option options [String] :format (nil) output format string for each branch
+        #   @option options [String] :format (nil) output format string for each
+        #     branch
         #
-        #     @option options [Boolean, nil] :remotes (nil) list only remote-tracking
-        #       branches
+        #   @option options [Boolean, nil] :remotes (nil) list only remote-tracking
+        #     branches
         #
-        #       Alias: :r
+        #     Alias: :r
         #
-        #     @option options [Boolean, nil] :all (nil) list both local and remote branches
+        #   @option options [Boolean, nil] :all (nil) list both local and remote
+        #     branches
         #
-        #       Alias: :a
+        #     Alias: :a
         #
-        #     @option options [Boolean, nil] :ignore_case (nil) sort and filter branches
-        #       case insensitively
+        #   @option options [Boolean, nil] :ignore_case (nil) sort and filter
+        #     branches case insensitively
         #
-        #       Alias: :i
+        #     Alias: :i
         #
-        #     @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, nil] :omit_empty (nil) do not print a
+        #     newline after formatted refs where the format expands to the empty
+        #     string
         #
-        #     @return [Git::CommandLineResult] the result of calling `git branch --list`
+        #   @return [Git::CommandLine::Result] the result of calling `git branch --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
+        #
+        def call(*, **)
+          super
+        end
       end
     end
   end

data/lib/git/commands/branch/move.rb

@@ -47,47 +47,55 @@ module Git
           operand :new_branch, required: true
         end
 
-        # @!method call(*, **)
+        # Executes the git branch --move command to rename a branch
         #
-        #   Execute the git branch --move command to rename a branch
+        # @overload call(new_branch, **options)
         #
-        #   @overload call(new_branch, **options)
+        #   Rename the current branch to new_branch
         #
-        #     Rename the current branch to new_branch
+        #   @param new_branch [String] the new name for the branch
         #
-        #     @param new_branch [String] the new name for the branch
+        #   @param options [Hash] command options
         #
-        #     @param options [Hash] command options
+        #   @option options [Boolean, nil] :force (nil) allow renaming even if new_branch already
+        #     exists
         #
-        #     @option options [Boolean, nil] :force (nil) allow renaming even if new_branch already exists
+        #     Alias: :f
         #
-        #       Alias: :f
+        #   @return [Git::CommandLine::Result] the result of calling `git branch --move`
         #
-        #     @return [Git::CommandLineResult] the result of calling `git branch --move`
+        #   @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
         #
-        #   @overload call(old_branch, new_branch, **options)
+        # @overload call(old_branch, new_branch, **options)
         #
-        #     Rename old_branch to new_branch
+        #   Rename old_branch to new_branch
         #
-        #     @param old_branch [String] the current name of the branch
+        #   @param old_branch [String] the current name of the branch
         #
-        #     @param new_branch [String] the new name for the branch
+        #   @param new_branch [String] the new name for the branch
         #
-        #     @param options [Hash] command options
+        #   @param options [Hash] command options
         #
-        #     @option options [Boolean, nil] :force (nil) allow renaming even if new_branch already exists
+        #   @option options [Boolean, nil] :force (nil) allow renaming even if new_branch already
+        #     exists
         #
-        #       Alias: :f
+        #     Alias: :f
         #
-        #     @return [Git::CommandLineResult] the result of calling `git branch --move`
+        #   @return [Git::CommandLine::Result] the result of calling `git branch --move`
         #
-        #     @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/branch/set_upstream.rb

@@ -39,21 +39,20 @@ module Git
           operand :branch_name
         end
 
-        # @!method call(*, **)
-        #
-        #   Execute the git branch --set-upstream-to command
+        # @!method call(*)
         #
         #   @overload call(**options)
         #
-        #     Sets upstream for the current branch
+        #     Set upstream for the current branch
         #
         #     @param options [Hash] command options
         #
-        #     @option options [String] :set_upstream_to (required) the upstream branch (e.g., 'origin/main')
+        #     @option options [String] :set_upstream_to (required)
+        #       upstream branch to set (e.g., `origin/main`)
         #
         #       Alias: :u
         #
-        #     @return [Git::CommandLineResult] the result of calling `git branch --set-upstream-to`
+        #     @return [Git::CommandLine::Result] the result of calling `git branch --set-upstream-to`
         #
         #     @raise [ArgumentError] if set_upstream_to is not provided
         #
@@ -69,11 +68,12 @@ module Git
         #
         #     @param options [Hash] command options
         #
-        #     @option options [String] :set_upstream_to (required) the upstream branch (e.g., 'origin/main')
+        #     @option options [String] :set_upstream_to (required)
+        #       upstream branch to set (e.g., `origin/main`)
         #
         #       Alias: :u
         #
-        #     @return [Git::CommandLineResult] the result of calling `git branch --set-upstream-to`
+        #     @return [Git::CommandLine::Result] the result of calling `git branch --set-upstream-to`
         #
         #     @raise [ArgumentError] if set_upstream_to is not provided
         #

data/lib/git/commands/branch/show_current.rb

@@ -34,13 +34,13 @@ module Git
           literal '--show-current'
         end
 
-        # @!method call(*, **)
+        # @!method call(*)
         #
         #   @overload call()
         #
-        #     Execute the git branch --show-current command.
+        #     Execute the `git branch --show-current` command
         #
-        #     @return [Git::CommandLineResult] the result of calling `git branch --show-current`
+        #     @return [Git::CommandLine::Result] the result of calling `git branch --show-current`
         #
         #     @raise [Git::FailedError] if git exits with a non-zero exit status
       end

data/lib/git/commands/branch/unset_upstream.rb

@@ -35,20 +35,16 @@ module Git
           operand :branch_name
         end
 
-        # @!method call(*, **)
+        # @!method call(*)
         #
-        #   @overload call(branch_name = nil, **options)
+        #   @overload call(branch_name = nil)
         #
-        #     Execute the `git branch --unset-upstream` command.
+        #     Execute the `git branch --unset-upstream` command
         #
         #     @param branch_name [String, nil] the branch to remove upstream tracking for
         #       (defaults to current branch if omitted)
         #
-        #     @param options [Hash] command options
-        #
-        #     @return [Git::CommandLineResult] the result of calling `git branch --unset-upstream`
-        #
-        #     @raise [ArgumentError] if unsupported options are provided
+        #     @return [Git::CommandLine::Result] the result of calling `git branch --unset-upstream`
         #
         #     @raise [Git::FailedError] if git exits with a non-zero exit status
       end

data/lib/git/commands/branch.rb

@@ -24,10 +24,10 @@ module Git
     # - {Branch::SetUpstream} — set upstream tracking (`--set-upstream-to`)
     # - {Branch::UnsetUpstream} — remove upstream tracking (`--unset-upstream`)
     #
-    # @api private
-    #
     # @see https://git-scm.com/docs/git-branch git-branch documentation
     #
+    # @api private
+    #
     module Branch
     end
   end

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

@@ -32,12 +32,12 @@ module Git
       # For single-object queries, use {CatFile::Raw}.
       # For filter-processed content, use {CatFile::Filtered}.
       #
+      # @note `arguments` block audited against https://git-scm.com/docs/git-cat-file/2.53.0
+      #
       # @see Git::Commands::CatFile
       #
       # @see https://git-scm.com/docs/git-cat-file git-cat-file documentation
       #
-      # @note `arguments` block audited against https://git-scm.com/docs/git-cat-file/2.53.0
-      #
       # @api private
       #
       class Batch < Base
@@ -47,56 +47,56 @@ module Git
           # Full content mode: header + raw bytes + newline separator per object;
           # accepts a format string to customise the per-object output header
           # (e.g. `"%(objectname) %(objecttype) %(objectsize)"`)
-          # @see https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt---batch
+          # See https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt---batch
           flag_or_value_option :batch, inline: true
 
           # Metadata-only mode: one `<sha> <type> <size>` line per object;
           # accepts a format string to customise the per-object output line
-          # @see https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt---batch-check
+          # See https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt---batch-check
           flag_or_value_option :batch_check, inline: true
 
           # Command-dispatch mode: stdin carries `contents`/`info`/`flush` verbs;
           # accepts a format string to customise the output of `info` and `contents` commands
-          # @see https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt---batch-command
+          # See https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt---batch-command
           flag_or_value_option :batch_command, inline: true
 
           # Enumerate all objects in the repository without reading stdin.
           # Incompatible with `batch_command:`.
-          # @see https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt---batch-all-objects
+          # See https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt---batch-all-objects
           flag_option :batch_all_objects
 
           # Use normal stdio buffering; enables explicit `flush` semantics when used
           # with `batch_command:` and improves throughput with `batch_check:`
-          # @see https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt---buffer
+          # See https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt---buffer
           flag_option :buffer
 
           # Follow symlinks inside the repository when traversing tree objects
-          # @see https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt---follow-symlinks
+          # See https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt---follow-symlinks
           flag_option :follow_symlinks
 
           # Allow `--batch-all-objects` to output objects in an arbitrary, potentially
           # faster order
-          # @see https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt---unordered
+          # See https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt---unordered
           flag_option :unordered
 
           # Apply textconv filters to blob content (combine with `batch_command:`)
-          # @see https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt---textconv
+          # See https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt---textconv
           flag_option :textconv
 
           # Apply the full working-tree filter pipeline (combine with `batch_command:`)
-          # @see https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt---filters
+          # See https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt---filters
           flag_option :filters
 
           # Map committer/author identities through mailmap for all batch modes
-          # @see https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt---use-mailmap
+          # See https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt---use-mailmap
           flag_option :use_mailmap, negatable: true
 
           # Omit objects matching the filter spec from the output (batched modes only)
-          # @see https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt---filterltfilter-specgt
+          # See https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt---filterltfilter-specgt
           value_option :filter, inline: true
 
           # Use NUL-delimited input/output instead of newline-delimited
-          # @see https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt--Z
+          # See https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt--Z
           flag_option :Z
 
           # Stream stdout to this IO object instead of buffering in memory.
@@ -154,7 +154,7 @@ module Git
         #   @option options [#write, nil] :out (nil) stream stdout to this IO object
         #     instead of buffering in memory; when given, `result.stdout` will be `''`
         #
-        #   @return [Git::CommandLineResult] the result of calling `git cat-file`
+        #   @return [Git::CommandLine::Result] the result of calling `git cat-file`
         #
         #     Stdout contains the batch output stream (or `''` when `out:` is given)
         #
@@ -196,7 +196,7 @@ module Git
         #   @option options [#write, nil] :out (nil) stream stdout to this IO object
         #     instead of buffering in memory; when given, `result.stdout` will be `''`
         #
-        #   @return [Git::CommandLineResult] the result of calling `git cat-file`
+        #   @return [Git::CommandLine::Result] the result of calling `git cat-file`
         #
         #     Stdout contains one metadata line per object (or `''` when `out:` is given)
         #
@@ -236,7 +236,7 @@ module Git
         #   @option options [#write, nil] :out (nil) stream stdout to this IO object
         #     instead of buffering in memory; when given, `result.stdout` will be `''`
         #
-        #   @return [Git::CommandLineResult] the result of calling `git cat-file`
+        #   @return [Git::CommandLine::Result] the result of calling `git cat-file`
         #
         #     Stdout contains the interleaved command output (or `''` when `out:` is given)
         #
@@ -270,7 +270,7 @@ module Git
         #   @option options [#write, nil] :out (nil) stream stdout to this IO object
         #     instead of buffering in memory; when given, `result.stdout` will be `''`
         #
-        #   @return [Git::CommandLineResult] the result of calling `git cat-file`
+        #   @return [Git::CommandLine::Result] the result of calling `git cat-file`
         #
         #     Stdout contains the full batch output (or `''` when `out:` is given)
         #
@@ -307,7 +307,7 @@ module Git
         #
         #   @option options [Numeric, nil] :timeout (nil) abort the command after this many seconds
         #
-        #   @return [Git::CommandLineResult] the result of calling `git cat-file`
+        #   @return [Git::CommandLine::Result] the result of calling `git cat-file`
         #
         #     Stdout contains one metadata line per object (or `''` when `out:` is given)
         #
@@ -332,7 +332,7 @@ module Git
         #
         # @param reader [IO] read end of the stdin pipe
         #
-        # @return [Git::CommandLineResult]
+        # @return [Git::CommandLine::Result]
         #
         def run_batch(bound, reader)
           result = if bound.execution_options.key?(:out)
@@ -344,6 +344,14 @@ module Git
           result
         end
 
+        # Run the bound command using the streaming execution path
+        #
+        # @param bound [Git::Commands::Arguments::Bound] bound argument list
+        #
+        # @param reader [IO] read end of the stdin pipe
+        #
+        # @return [Git::CommandLine::Result] the command result
+        #
         def run_batch_streaming(bound, reader)
           @execution_context.command_streaming(
             *bound,
@@ -353,6 +361,14 @@ module Git
           )
         end
 
+        # Run the bound command using the capturing execution path
+        #
+        # @param bound [Git::Commands::Arguments::Bound] bound argument list
+        #
+        # @param reader [IO] read end of the stdin pipe
+        #
+        # @return [Git::CommandLine::Result] the command result
+        #
         def run_batch_capturing(bound, reader)
           @execution_context.command_capturing(
             *bound,

data/lib/git/commands/cat_file/filtered.rb

@@ -37,16 +37,16 @@ module Git
           literal 'cat-file'
 
           # Apply only the textconv filter (binary-to-text conversion)
-          # @see https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt---textconv
+          # See https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt---textconv
           flag_option :textconv
 
           # Apply the full working-tree filter pipeline (smudge, EOL, textconv)
-          # @see https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt---filters
+          # See https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt---filters
           flag_option :filters
 
           # Specify the path separately when the rev is passed as a bare revision.
           # When used, the `rev` operand must be a plain revision (not `<rev>:<path>`).
-          # @see https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt---pathltpathgt
+          # See https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt---pathltpathgt
           value_option :path, inline: true
 
           end_of_options
@@ -56,9 +56,7 @@ module Git
           operand :rev, required: true
         end
 
-        # @!method call(*, **)
-        #
-        #   Execute `git cat-file --textconv` or `git cat-file --filters`.
+        # @!method call(*)
         #
         #   @overload call(rev, textconv: true, **options)
         #     Apply the textconv filter to a single object
@@ -70,15 +68,16 @@ module Git
         #
         #     @param options [Hash] command options
         #
-        #     @option options [String] :path (nil) Path to the blob when `rev` is a bare revision
+        #     @option options [String] :path (nil)
+        #       path to the blob when `rev` is a bare revision
         #
-        #     @return [Git::CommandLineResult] the result of calling `git cat-file`
+        #     @return [Git::CommandLine::Result] the result of calling `git cat-file`
         #
         #       Stdout contains the textconv-processed content
         #
         #     @raise [ArgumentError] if unsupported options are provided
         #
-        #     @raise [Git::FailedError] if the object does not exist or the path is missing
+        #     @raise [Git::FailedError] if git exits with a non-zero exit status
         #
         #   @overload call(rev, filters: true, **options)
         #     Apply the full working-tree filter pipeline to a single object
@@ -90,15 +89,16 @@ module Git
         #
         #     @param options [Hash] command options
         #
-        #     @option options [String] :path (nil) Path to the blob when `rev` is a bare revision
+        #     @option options [String] :path (nil)
+        #       path to the blob when `rev` is a bare revision
         #
-        #     @return [Git::CommandLineResult] the result of calling `git cat-file`
+        #     @return [Git::CommandLine::Result] the result of calling `git cat-file`
         #
         #       Stdout contains the filter-processed content
         #
         #     @raise [ArgumentError] if unsupported options are provided
         #
-        #     @raise [Git::FailedError] if the object does not exist or the path is missing
+        #     @raise [Git::FailedError] if git exits with a non-zero exit status
       end
     end
   end