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

data/lib/git/branch.rb

@@ -139,17 +139,37 @@ module Git
     # Archives this branch and writes the result to a file
     #
     # @example Archive to a tar file
-    #   git.branch('main').archive('/tmp/main.tar')
+    #   git.branch('main').archive('/tmp/main.tar', format: 'tar')
     #
     # @example Archive to a zip file
     #   git.branch('main').archive('/tmp/main.zip', format: 'zip')
     #
+    # @example Archive a remote branch to a tgz file
+    #   git.remote('origin').branch('main').archive('/tmp/main.tgz', format: 'tgz')
+    #
     # @param file [String] path to the destination archive file
     #
     # @param opts [Hash] archive options (see {Git::Repository#archive})
     #
+    # @option opts [String] :format ('zip') archive format for this wrapper:
+    #   `'tar'`, `'zip'`, or `'tgz'`
+    #
+    # @option opts [String] :prefix (nil) prefix prepended to every filename
+    #   in the archive
+    #
+    # @option opts [String] :path (nil) path within the tree to include in the
+    #   archive
+    #
+    # @option opts [String] :remote (nil) retrieve the archive from a remote
+    #   repository
+    #
+    # @option opts [Boolean, nil] :add_gzip (nil) apply gzip compression after
+    #   writing the archive; set automatically when `format: 'tgz'` is given
+    #
     # @return [String] the path to the written archive file
     #
+    # @raise [ArgumentError] when archive options or destination path are invalid
+    #
     # @raise [Git::FailedError] if `git archive` fails
     #
     def archive(file, opts = {})
@@ -175,14 +195,14 @@ module Git
     #
     # @param message [String] commit message used when the block returns truthy
     #
-    # @yield Executes the block with this branch checked out
-    #
-    # @yieldreturn [Object] return a truthy value to commit all changes, a falsy value to hard-reset
-    #
     # @return [String] git's stdout from the final checkout back to the original branch
     #
     # @raise [Git::FailedError] if any of the underlying git operations (checkout, commit, reset) fail
     #
+    # @yield Executes the block with this branch checked out
+    #
+    # @yieldreturn [Object] return a truthy value to commit all changes, a falsy value to hard-reset
+    #
     def in_branch(message = 'in branch work')
       old_current = branch_repository.current_branch
       checkout
@@ -327,7 +347,7 @@ module Git
     #
     # @param commit [String] the commit SHA to point this branch at
     #
-    # @return [Git::CommandLineResult] the result of calling `git update-ref`
+    # @return [Git::CommandLine::Result] the result of calling `git update-ref`
     #
     # @raise [Git::FailedError] if git exits with a non-zero exit status
     #

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