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

data/lib/git/branch_delete_failure.rb

@@ -15,16 +15,19 @@ module Git
   #   failure.error_message #=> "branch 'nonexistent' not found."
   #
   # @see Git::BranchDeleteResult
+  #
   # @see Git::Commands::Branch::Delete
   #
   # @api public
   #
   # @!attribute [r] name
   #   The name of the branch that failed to be deleted
+  #
   #   @return [String]
   #
   # @!attribute [r] error_message
   #   The error message from git explaining why the branch could not be deleted
+  #
   #   @return [String]
   #
   BranchDeleteFailure = Data.define(:name, :error_message)

data/lib/git/branch_delete_result.rb

@@ -29,25 +29,27 @@ module Git
   #   result.not_deleted.first.error_message #=> "branch 'nonexistent' not found."
   #
   # @see Git::BranchInfo
+  #
   # @see Git::BranchDeleteFailure
+  #
   # @see Git::Commands::Branch::Delete
   #
   # @api public
   #
   # @!attribute [r] deleted
   #   Branches that were successfully deleted
+  #
   #   @return [Array<Git::BranchInfo>]
   #
   # @!attribute [r] not_deleted
   #   Branches that could not be deleted, with the reason for each failure
+  #
   #   @return [Array<Git::BranchDeleteFailure>]
   #
   BranchDeleteResult = Data.define(:deleted, :not_deleted) do
     # Returns true if all requested branches were successfully deleted
     #
-    # @return [Boolean] true if no branches failed to delete, false otherwise
-    #
-    # @example
+    # @example Check if the delete operation succeeded
     #   result = branch_delete.call('feature-branch')
     #   if result.success?
     #     puts "All branches deleted successfully"
@@ -56,6 +58,7 @@ module Git
     #     result.not_deleted.each { |f| puts "  #{f.name}: #{f.error_message}" }
     #   end
     #
+    # @return [Boolean] true if no branches failed to delete, false otherwise
     def success?
       not_deleted.empty?
     end

data/lib/git/branch_info.rb

@@ -7,6 +7,12 @@ module Git
   #   - remote_name: the remote name (e.g., 'origin') for remote branches, nil for local
   #   - branch_name: the branch name without the remote prefix
   #
+  # @example Parse branch refnames
+  #   'main' => { remote_name: nil, branch_name: 'main' }
+  #   'remotes/origin/main' => { remote_name: 'origin', branch_name: 'main' }
+  #   'feature/foo' => { remote_name: nil, branch_name: 'feature/foo' }
+  #   'remotes/origin/feature/bar' => { remote_name: 'origin', branch_name: 'feature/bar' }
+  #
   # @note This regex is similar to Git::Branch::BRANCH_NAME_REGEXP but uses \A/\z anchors
   #   instead of ^/$ for stricter matching. As part of the architectural redesign,
   #   Git::Branch will eventually be refactored to use BranchInfo internally, at which
@@ -18,12 +24,6 @@ module Git
   #   ambiguity in git refnames that can only be resolved with knowledge of configured
   #   remotes. See: https://github.com/ruby-git/ruby-git/issues/919
   #
-  # @example
-  #   'main' => { remote_name: nil, branch_name: 'main' }
-  #   'remotes/origin/main' => { remote_name: 'origin', branch_name: 'main' }
-  #   'feature/foo' => { remote_name: nil, branch_name: 'feature/foo' }
-  #   'remotes/origin/feature/bar' => { remote_name: 'origin', branch_name: 'feature/bar' }
-  #
   # @api private
   BRANCH_REFNAME_REGEXP = %r{
     \A                              # start of string

data/lib/git/command_line/base.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
-require 'git/command_line'
+require 'git/command_line/result'
 require 'git/errors'
+require 'process_executer'
 
 module Git
   module CommandLine
@@ -23,7 +24,7 @@ module Git
     #
     # @abstract Subclass and implement {#run}
     #
-    # @api public
+    # @api private
     #
     class Base
       # Create a Base (or subclass) object
@@ -35,7 +36,7 @@ module Git
       #
       # @param global_opts [Array<String>] global options to pass to git
       #
-      # @param logger [Logger] the logger to use
+      # @param logger [Logger] used to log git commands and their results
       #
       def initialize(env, binary_path, global_opts, logger)
         @env = env
@@ -54,8 +55,6 @@ module Git
         raise NotImplementedError, "#{self.class}#run is not implemented"
       end
 
-      # @attribute [r] env
-      #
       # Variables to set (or unset) in the git command's environment
       #
       # @example
@@ -70,8 +69,6 @@ module Git
       #
       attr_reader :env
 
-      # @attribute [r] binary_path
-      #
       # The path to the command line binary to run
       #
       # @example
@@ -82,8 +79,6 @@ module Git
       #
       attr_reader :binary_path
 
-      # @attribute [r] global_opts
-      #
       # The global options to pass to git
       #
       # These are options that are passed to git before the command name and
@@ -99,8 +94,6 @@ module Git
       #
       attr_reader :global_opts
 
-      # @attribute [r] logger
-      #
       # The logger to use for logging git commands and results
       #
       # @example
@@ -149,6 +142,8 @@ module Git
       # Yield to a block that calls ProcessExecuter and translate any ProcessExecuter
       # errors to their ruby-git equivalents
       #
+      # @return [Object] the return value of the block
+      #
       # @raise [ArgumentError] in place of ProcessExecuter::ArgumentError
       #
       # @raise [Git::Error] in place of ProcessExecuter::SpawnError (binary not found or
@@ -161,8 +156,6 @@ module Git
       #   timeout firing and the kill signal being delivered. This is a race in
       #   process_executer's timeout handling and is semantically equivalent to a timeout.
       #
-      # @return [Object] the return value of the block
-      #
       # @api private
       #
       def run_process_executer

data/lib/git/command_line/capturing.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
-require 'git/command_line'
+require 'git/command_line/base'
+require 'git/encoding_utils'
 
 module Git
   module CommandLine
@@ -27,6 +28,8 @@ module Git
     #
     # @see Git::CommandLine::Streaming
     #
+    # @api private
+    #
     class Capturing < Git::CommandLine::Base
       # Default options accepted by {#run}
       #
@@ -139,7 +142,7 @@ module Git
       #   overrides for this command.  String keys map to String values (to set) or
       #   `nil` (to unset).
       #
-      # @return [Git::CommandLineResult] the result of the command
+      # @return [Git::CommandLine::Result] the result of the command
       #
       # @raise [ArgumentError] if `args` contains an array or an unknown option is
       #   passed
@@ -164,12 +167,36 @@ module Git
 
       private
 
+      # Execute the git command with the given arguments and options, capturing the output
+      #
+      # @param args [Array<String>] the git command arguments
+      #
+      # @param options_hash [Hash] the merged run options forwarded from {#run}
+      #
+      #   Only the keys consumed by this method are listed below; remaining keys
+      #   from {RUN_OPTION_DEFAULTS} (`:normalize`, `:chomp`, `:raise_on_failure`)
+      #   are present in the hash but are not used here.
+      #
+      # @option options_hash [IO, nil] :in stdin IO object for the subprocess
+      #
+      # @option options_hash [#write, nil] :out stdout redirect target
+      #
+      # @option options_hash [#write, nil] :err stderr redirect target
+      #
+      # @option options_hash [String, nil] :chdir working directory for the subprocess
+      #
+      # @option options_hash [Numeric, nil] :timeout execution timeout in seconds
+      #
+      # @option options_hash [Boolean] :merge (false) merge stdout into stderr
+      #
+      # @option options_hash [Hash] :env ({}) environment variable overrides
+      #
       # @return [ProcessExecuter::ResultWithCapture] the process result with captured output
       #
       # @api private
       def execute(*args, **options_hash)
         git_cmd = build_git_cmd(args)
-        options = execute_options(**options_hash)
+        options = execution_options(**options_hash)
         run_process_executer do
           ProcessExecuter.run_with_capture(merged_env(options_hash), *git_cmd, **options)
         end
@@ -177,10 +204,24 @@ module Git
 
       # Build the ProcessExecuter options hash for a capturing run
       #
+      # @param options_hash [Hash] the merged run options forwarded from {#run}
+      #
+      # @option options_hash [IO, nil] :in stdin IO object for the subprocess
+      #
+      # @option options_hash [#write, nil] :out stdout redirect target
+      #
+      # @option options_hash [#write, nil] :err stderr redirect target
+      #
+      # @option options_hash [String, nil] :chdir working directory for the subprocess
+      #
+      # @option options_hash [Numeric, nil] :timeout execution timeout in seconds
+      #
+      # @option options_hash [Boolean] :merge (false) merge stdout into stderr
+      #
       # @return [Hash]
       #
       # @api private
-      def execute_options(**options_hash)
+      def execution_options(**options_hash)
         chdir = options_hash[:chdir] || :not_set
         timeout_after = options_hash[:timeout]
         merge_output = options_hash[:merge] || false
@@ -190,14 +231,22 @@ module Git
         end
       end
 
-      # Extract non-nil redirect options (`:in`, `:out`, `:err`) from options_hash
+      # Extract non-nil redirect options (`:in`, `:out`, `:err`) from `options`
       #
-      # @return [Hash]
+      # @param options [Hash] the options hash containing potential redirect options
+      #
+      # @option options [IO, nil] :in the input IO stream
+      #
+      # @option options [#write, nil] :out the output IO stream
+      #
+      # @option options [#write, nil] :err the error IO stream
+      #
+      # @return [Hash] the non-nil redirect options
       #
       # @api private
-      def redirect_options(options_hash)
+      def redirect_options(options)
         %i[in out err].filter_map do |key|
-          val = options_hash[key]
+          val = options[key]
           [key, val] unless val.nil?
         end.to_h
       end
@@ -207,9 +256,17 @@ module Git
       #
       # @param result [ProcessExecuter::ResultWithCapture] the raw result
       #
-      # @param options [Hash] the merged run options
+      # @param options [Hash] the merged run options forwarded from {#run}
+      #
+      # @option options [Boolean] :normalize (false) normalize encoding of captured output
+      #
+      # @option options [Boolean] :chomp (false) chomp trailing newlines from captured output
+      #
+      # @option options [Numeric, nil] :timeout execution timeout used to construct the result
+      #
+      # @option options [Boolean] :raise_on_failure (true) raise {Git::FailedError} on non-zero exit
       #
-      # @return [Git::CommandLineResult]
+      # @return [Git::CommandLine::Result]
       #
       # @raise [Git::FailedError] if the command failed and raise_on_failure is true
       #

data/lib/git/command_line/result.rb

@@ -35,8 +35,6 @@ module Git
         @stderr = stderr
       end
 
-      # @attribute [r] git_cmd
-      #
       # The git command that was executed
       #
       # @example
@@ -48,8 +46,6 @@ module Git
       #
       attr_reader :git_cmd
 
-      # @attribute [r] status
-      #
       # The process result object returned by ProcessExecuter
       #
       # In practice this is a `ProcessExecuter::ResultWithCapture` (from
@@ -66,8 +62,6 @@ module Git
       #
       attr_reader :status
 
-      # @attribute [r] stdout
-      #
       # The output of the process
       #
       # @example
@@ -79,8 +73,6 @@ module Git
       #
       attr_reader :stdout
 
-      # @attribute [r] stderr
-      #
       # The error output of the process
       #
       # @example

data/lib/git/command_line/streaming.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'git/command_line'
+require 'git/command_line/base'
 require 'stringio'
 
 module Git
@@ -30,6 +30,8 @@ module Git
     #
     # @see Git::CommandLine::Capturing
     #
+    # @api private
+    #
     class Streaming < Git::CommandLine::Base
       # Default options accepted by {#run}
       #
@@ -89,7 +91,7 @@ module Git
       #   overrides for this command.  String keys map to String values (to set) or
       #   `nil` (to unset).
       #
-      # @return [Git::CommandLineResult] the result of the command
+      # @return [Git::CommandLine::Result] the result of the command
       #
       #   `result.stdout` will always be `''` (empty) — stdout was streamed to `out:`.
       #   `result.stderr` contains any stderr output captured for diagnostics.
@@ -122,6 +124,28 @@ module Git
 
       private
 
+      # Execute the git command in streaming mode
+      #
+      # @param args [Array<String>] the git command arguments
+      #
+      # @param err_io [StringIO, #write] the internal stderr destination
+      #
+      # @param options_hash [Hash] the merged run options forwarded from {#run}
+      #
+      #   Only the keys consumed by this method are listed below; `:err` and
+      #   `:raise_on_failure` are present in the hash but not used here (`:err`
+      #   is handled via the separate `err_io:` argument).
+      #
+      # @option options_hash [IO, nil] :in stdin IO object for the subprocess
+      #
+      # @option options_hash [#write, nil] :out stdout streaming destination
+      #
+      # @option options_hash [String, nil] :chdir working directory for the subprocess
+      #
+      # @option options_hash [Numeric, nil] :timeout execution timeout in seconds
+      #
+      # @option options_hash [Hash] :env ({}) environment variable overrides
+      #
       # @return [ProcessExecuter::Result] the result of running the command (non-capturing)
       #
       # @api private
@@ -135,6 +159,18 @@ module Git
 
       # Build the ProcessExecuter options hash for a streaming run
       #
+      # @param err_io [StringIO, #write] the stderr destination (internal buffer or tee)
+      #
+      # @param options_hash [Hash] the merged run options forwarded from {#run}
+      #
+      # @option options_hash [IO, nil] :in stdin IO object for the subprocess
+      #
+      # @option options_hash [#write, nil] :out stdout streaming destination
+      #
+      # @option options_hash [String, nil] :chdir working directory for the subprocess
+      #
+      # @option options_hash [Numeric, nil] :timeout execution timeout in seconds
+      #
       # @return [Hash]
       #
       # @api private
@@ -170,7 +206,7 @@ module Git
         end
       end
 
-      # Process the result of a streaming command and return a Git::CommandLineResult
+      # Process the result of a streaming command and return a Git::CommandLine::Result
       #
       # Constructs stdout as `''` (not captured) and stderr from the internal StringIO.
       #
@@ -178,9 +214,13 @@ module Git
       #
       # @param err_io [StringIO] the internal StringIO that captured stderr
       #
-      # @param options [Hash] the merged run options
+      # @param options [Hash] the merged run options forwarded from {#run}
+      #
+      # @option options [Numeric, nil] :timeout execution timeout used to construct the result
+      #
+      # @option options [Boolean] :raise_on_failure (true) raise {Git::FailedError} on non-zero exit
       #
-      # @return [Git::CommandLineResult]
+      # @return [Git::CommandLine::Result]
       #
       # @api private
       def process_result(result, err_io, options)

data/lib/git/command_line.rb

@@ -19,9 +19,7 @@ module Git
   # {Git::ExecutionContext#command_streaming}.
   #
   # Results are returned as {Git::CommandLine::Result} objects (also accessible
-  # as {Git::CommandLineResult} for backward compatibility).
-  #
-  # @api public
+  # as {Git::CommandLine::Result} for backward compatibility).
   #
   # @example Buffered command via Git::CommandLine::Capturing
   #   cli = Git::CommandLine::Capturing.new(
@@ -39,8 +37,11 @@ module Git
   #   end
   #
   # @see Git::CommandLine::Base
+  #
   # @see Git::CommandLine::Result
   #
+  # @api private
+  #
   module CommandLine
   end
 end

data/lib/git/commands/add.rb

@@ -9,6 +9,12 @@ module Git
     # This command updates the index using the current content found in the working tree,
     # to prepare the content staged for the next commit.
     #
+    # @example Basic usage
+    #   add = Git::Commands::Add.new(execution_context)
+    #   add.call('path/to/file')
+    #   add.call('file1.rb', 'file2.rb')
+    #   add.call(all: true)
+    #
     # @note `arguments` block audited against https://git-scm.com/docs/git-add/2.53.0
     #
     # @see https://git-scm.com/docs/git-add git-add
@@ -17,12 +23,6 @@ module Git
     #
     # @api private
     #
-    # @example Basic usage
-    #   add = Git::Commands::Add.new(execution_context)
-    #   add.call('path/to/file')
-    #   add.call('file1.rb', 'file2.rb')
-    #   add.call(all: true)
-    #
     class Add < Git::Commands::Base
       arguments do
         literal 'add'
@@ -46,86 +46,94 @@ module Git
         operand :pathspec, repeatable: true
       end
 
-      # @!method call(*, **)
+      # @overload call(*pathspec, **options)
       #
-      #   @overload call(*pathspec, **options)
+      #   Execute the `git add` command
       #
-      #     Execute the `git add` command
+      #   @param pathspec [Array<String>] files to be added to the repository
+      #     (relative to the worktree root)
       #
-      #     @param pathspec [Array<String>] files to be added to the repository
-      #       (relative to the worktree root)
+      #   @param options [Hash] command options
       #
-      #     @param options [Hash] command options
+      #   @option options [Boolean, nil] :verbose (nil) be verbose
       #
-      #     @option options [Boolean, nil] :verbose (nil) be verbose
+      #     Alias: :v
       #
-      #       Alias: :v
+      #   @option options [Boolean, nil] :dry_run (nil) don't actually add files;
+      #     show what would be added
       #
-      #     @option options [Boolean, nil] :dry_run (nil) don't actually add files; show what would be added
+      #     Alias: :n
       #
-      #       Alias: :n
+      #   @option options [Boolean, nil] :force (nil) allow adding otherwise ignored
+      #     files
       #
-      #     @option options [Boolean, nil] :force (nil) allow adding otherwise ignored files
+      #     Alias: :f
       #
-      #       Alias: :f
+      #   @option options [Boolean, nil] :all (nil) add, modify, and remove index
+      #     entries to match the worktree (--all)
       #
-      #     @option options [Boolean, nil] :all (nil) add, modify, and remove index entries to
-      #       match the worktree (--all)
+      #     Alias: :A
       #
-      #       Alias: :A
+      #   @option options [Boolean, nil] :no_all (nil) add and modify index entries
+      #     without staging removals (--no-all)
       #
-      #     @option options [Boolean, nil] :no_all (nil) add and modify index entries without staging
-      #       removals (--no-all)
+      #   @option options [Boolean, nil] :ignore_removal (nil) add and modify files;
+      #     ignore removals (--ignore-removal)
       #
-      #     @option options [Boolean, nil] :ignore_removal (nil) add and modify files; ignore removals
-      #       (--ignore-removal)
+      #   @option options [Boolean, nil] :no_ignore_removal (nil) include file removals
+      #     (--no-ignore-removal)
       #
-      #     @option options [Boolean, nil] :no_ignore_removal (nil) include file removals (--no-ignore-removal)
+      #   @option options [Boolean, nil] :update (nil) update tracked files only; does
+      #     not add new files
       #
-      #     @option options [Boolean, nil] :update (nil) update tracked files only; does not add new files
+      #     Alias: :u
       #
-      #       Alias: :u
+      #   @option options [Boolean, nil] :sparse (nil) allow updating index entries
+      #     outside the sparse-checkout cone
       #
-      #     @option options [Boolean, nil] :sparse (nil) allow updating index entries outside the
-      #       sparse-checkout cone
+      #   @option options [Boolean, nil] :intent_to_add (nil) record that the path
+      #     will be added later, placing an empty entry in the index
       #
-      #     @option options [Boolean, nil] :intent_to_add (nil) record that the path will be added later,
-      #       placing an empty entry in the index
+      #     Alias: :N
       #
-      #       Alias: :N
+      #   @option options [Boolean, nil] :refresh (nil) refresh stat() information in
+      #     the index without adding files
       #
-      #     @option options [Boolean, nil] :refresh (nil) refresh stat() information in the index without
-      #       adding files
+      #   @option options [Boolean, nil] :ignore_errors (nil) continue adding other
+      #     files if some files cannot be added due to indexing errors
       #
-      #     @option options [Boolean, nil] :ignore_errors (nil) continue adding other files if some files
-      #       cannot be added due to indexing errors
+      #   @option options [Boolean, nil] :ignore_missing (nil) check whether any given
+      #     files would be ignored
       #
-      #     @option options [Boolean, nil] :ignore_missing (nil) check whether any given files would be
-      #       ignored
+      #   @option options [Boolean, nil] :renormalize (nil) apply the "clean" process
+      #     freshly to all tracked files to forcibly re-add them with correct line
+      #     endings
       #
-      #     @option options [Boolean, nil] :renormalize (nil) apply the "clean" process freshly to all tracked
-      #       files to forcibly re-add them with correct line endings
+      #   @option options [Boolean, nil] :no_warn_embedded_repo (nil) suppress warning
+      #     when adding an embedded repository without using `git submodule add`
       #
-      #     @option options [Boolean, nil] :no_warn_embedded_repo (nil) suppress warning when adding an
-      #       embedded repository without using `git submodule add`
+      #   @option options [String] :chmod (nil) override the executable bit of added
+      #     files in the index
       #
-      #     @option options [String] :chmod (nil) override the executable bit of added files in the index
+      #     Value must be `'+x'` or `'-x'`
       #
-      #       Value must be `'+x'` or `'-x'`
+      #   @option options [String] :pathspec_from_file (nil) read pathspec from the
+      #     given file (use `'-'` for stdin)
       #
-      #     @option options [String] :pathspec_from_file (nil) read pathspec from the given file
-      #       (use `'-'` for stdin)
+      #   @option options [Boolean, nil] :pathspec_file_nul (nil) separate pathspec
+      #     elements with NUL when reading from a file
       #
-      #     @option options [Boolean, nil] :pathspec_file_nul (nil) separate pathspec elements with NUL
-      #       when reading from a file
+      #   @return [Git::CommandLine::Result] the result of calling `git add`
       #
-      #     @return [Git::CommandLineResult] the result of calling `git 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
+      end
     end
   end
 end

data/lib/git/commands/am/abort.rb

@@ -28,13 +28,13 @@ module Git
           literal '--abort'
         end
 
-        # @!method call(*, **)
+        # @!method call()
         #
         #   @overload call()
         #
         #     Abort the in-progress am session and restore the branch
         #
-        #     @return [Git::CommandLineResult] the result of calling `git am --abort`
+        #     @return [Git::CommandLine::Result] the result of calling `git am --abort`
         #
         #     @raise [Git::FailedError] if git exits with a non-zero exit status
       end