git 1.19.1 → 5.5.0

data/lib/git/command_line/base.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+require 'git/command_line/result'
+require 'git/errors'
+require 'process_executer'
+
+module Git
+  module CommandLine
+    # Abstract base class for git command-line execution strategies
+    #
+    # Concrete subclasses must implement {#run} to execute a git command and
+    # return a {Git::CommandLine::Result}. Two implementations are provided:
+    #
+    # * {Git::CommandLine::Capturing} — buffers stdout and stderr in memory
+    # * {Git::CommandLine::Streaming} — streams stdout to a caller-supplied IO
+    #
+    # @example Instantiate a concrete subclass
+    #   env = { 'GIT_DIR' => '/path/to/git/dir' }
+    #   binary_path = '/usr/bin/git'
+    #   global_opts = %w[--git-dir /path/to/git/dir]
+    #   logger = Logger.new($stdout)
+    #   cli = Git::CommandLine::Capturing.new(env, binary_path, global_opts, logger)
+    #   cli.run('version') #=> #<Git::CommandLine::Result ...>
+    #
+    # @abstract Subclass and implement {#run}
+    #
+    # @api private
+    #
+    class Base
+      # Create a Base (or subclass) object
+      #
+      # @param env [Hash{String => String, nil}] environment variables to set or
+      #   unset. String values set the variable; `nil` values unset it.
+      #
+      # @param binary_path [String] the path to the git binary
+      #
+      # @param global_opts [Array<String>] global options to pass to git
+      #
+      # @param logger [Logger] used to log git commands and their results
+      #
+      def initialize(env, binary_path, global_opts, logger)
+        @env = env
+        @binary_path = binary_path
+        @global_opts = global_opts
+        @logger = logger
+      end
+
+      # Execute a git command and return the result
+      #
+      # Concrete subclasses must override this method.
+      #
+      # @raise [NotImplementedError] always — must be implemented by subclasses
+      #
+      def run(*)
+        raise NotImplementedError, "#{self.class}#run is not implemented"
+      end
+
+      # Variables to set (or unset) in the git command's environment
+      #
+      # @example
+      #   env = { 'GIT_DIR' => '/path/to/git/dir' }
+      #   cli = Git::CommandLine::Capturing.new(env, '/usr/bin/git', [], Logger.new(nil))
+      #   cli.env #=> { 'GIT_DIR' => '/path/to/git/dir' }
+      #
+      # @return [Hash{String => String, nil}]
+      #
+      # @see https://ruby-doc.org/3.2.1/Process.html#method-c-spawn Process.spawn
+      #   for details on how to set environment variables using the `env` parameter
+      #
+      attr_reader :env
+
+      # The path to the command line binary to run
+      #
+      # @example
+      #   cli = Git::CommandLine::Capturing.new({}, '/usr/bin/git', [], Logger.new(nil))
+      #   cli.binary_path #=> '/usr/bin/git'
+      #
+      # @return [String]
+      #
+      attr_reader :binary_path
+
+      # The global options to pass to git
+      #
+      # These are options that are passed to git before the command name and
+      # arguments. For example, in `git --git-dir /path/to/git/dir version`, the
+      # global options are %w[--git-dir /path/to/git/dir].
+      #
+      # @example
+      #   global_opts = %w[--git-dir /path/to/git/dir]
+      #   cli = Git::CommandLine::Capturing.new({}, '/usr/bin/git', global_opts, Logger.new(nil))
+      #   cli.global_opts #=> %w[--git-dir /path/to/git/dir]
+      #
+      # @return [Array<String>]
+      #
+      attr_reader :global_opts
+
+      # The logger to use for logging git commands and results
+      #
+      # @example
+      #   logger = Logger.new(nil)
+      #   cli = Git::CommandLine::Capturing.new({}, '/usr/bin/git', [], logger)
+      #   cli.logger == logger #=> true
+      #
+      # @return [Logger]
+      #
+      attr_reader :logger
+
+      private
+
+      # Merge caller-supplied options into `defaults` and raise if any unknown keys are present
+      #
+      # @param defaults [Hash] the allowed keys and their default values (e.g. RUN_OPTION_DEFAULTS)
+      #
+      # @param options_hash [Hash] caller-supplied options
+      #
+      # @return [Hash] defaults with any supplied values overridden
+      #
+      # @raise [ArgumentError] if options_hash contains keys not present in defaults
+      #
+      # @api private
+      #
+      def merge_and_validate_options(defaults, options_hash)
+        merged = defaults.merge(options_hash)
+        extra = merged.keys - defaults.keys
+        raise ArgumentError, "Unknown options: #{extra.join(', ')}" if extra.any?
+
+        merged
+      end
+
+      # Merge the instance-level env with any per-call overrides in options_hash[:env]
+      #
+      # @param options_hash [Hash] options that may include an :env override
+      #
+      # @return [Hash{String => String, nil}]
+      #
+      # @api private
+      #
+      def merged_env(options_hash)
+        env.merge(options_hash[:env] || {})
+      end
+
+      # 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
+      #   failed to launch)
+      #
+      # @raise [Git::ProcessIOError] in place of ProcessExecuter::ProcessIOError
+      #
+      # @raise [Git::ProcessIOError] when a timeout race causes Errno::ESRCH. On Ruby 4.0+,
+      #   `Process.kill` raises `Errno::ESRCH` when the spawned process exits between the
+      #   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.
+      #
+      # @api private
+      #
+      def run_process_executer
+        yield
+      rescue ProcessExecuter::ArgumentError => e
+        raise ::ArgumentError, e.message
+      rescue ProcessExecuter::SpawnError => e
+        raise Git::Error, e.message, cause: e.cause
+      rescue ProcessExecuter::ProcessIOError => e
+        raise Git::ProcessIOError, e.message, cause: e.cause
+      rescue Errno::ESRCH => e
+        # Ruby 4.0+: Process.kill raises Errno::ESRCH when the spawned process exits
+        # in the narrow window between the timeout firing and the kill signal being sent.
+        # This is a known race in process_executer's timeout handling.
+        raise Git::ProcessIOError, "Git process no longer exists (timeout race): #{e.message}", cause: e
+      end
+
+      # Build the git command line from the available sources to send to `Process.spawn`
+      #
+      # @param args [Array<String>] command-line arguments to append after global options
+      #
+      # @return [Array<String>]
+      #
+      # @raise [ArgumentError] if any element of args is itself an Array
+      #
+      # @api private
+      #
+      def build_git_cmd(args)
+        raise ArgumentError, 'The args array can not contain an array' if args.any?(Array)
+
+        [binary_path, *global_opts, *args].map(&:to_s)
+      end
+
+      # Log the result of a git command at info/debug level
+      #
+      # @param result [ProcessExecuter::Result] the raw process result
+      #
+      # @param command [Array<String>] the full command that was run
+      #
+      # @param processed_out [String] the post-processed stdout string
+      #
+      # @param processed_err [String] the post-processed stderr string
+      #
+      # @return [void]
+      #
+      # @api private
+      #
+      def log_result(result, command, processed_out, processed_err)
+        logger.info { "#{command} exited with status #{result}" }
+        logger.debug { "stdout:\n#{processed_out.inspect}\nstderr:\n#{processed_err.inspect}" }
+      end
+
+      # Build a {Git::CommandLine::Result} and raise on timeout, signal, or failure
+      #
+      # @param command [Array<String>] the full command that was run
+      #
+      # @param result [ProcessExecuter::Result] the raw process result
+      #
+      # @param processed_out [String] processed stdout string
+      #
+      # @param processed_err [String] processed stderr string
+      #
+      # @param timeout [Numeric, nil] the timeout value (for error context)
+      #
+      # @param raise_on_failure [Boolean] whether to raise on non-zero exit status
+      #
+      # @return [Git::CommandLine::Result]
+      #
+      # @raise [Git::TimeoutError] if the command timed out
+      #
+      # @raise [Git::SignaledError] if the command was terminated by a signal
+      #
+      # @raise [Git::FailedError] if the command failed and raise_on_failure is true
+      #
+      # @api private
+      #
+      # rubocop:disable-next Metrics/ParameterLists
+      def command_line_result(command, result, processed_out, processed_err, timeout, raise_on_failure)
+        Git::CommandLine::Result.new(command, result, processed_out, processed_err).tap do |processed_result|
+          raise Git::TimeoutError.new(processed_result, timeout) if result.timed_out?
+
+          raise Git::SignaledError, processed_result if result.signaled?
+
+          raise Git::FailedError, processed_result if raise_on_failure && !result.success?
+        end
+      end
+    end
+  end
+end

data/lib/git/command_line/capturing.rb

@@ -0,0 +1,308 @@
+# frozen_string_literal: true
+
+require 'git/command_line/base'
+require 'git/encoding_utils'
+
+module Git
+  module CommandLine
+    # Executes a git command and captures both stdout and stderr in memory
+    #
+    # {Git::CommandLine::Capturing} is the buffering strategy: it calls
+    # `ProcessExecuter.run_with_capture`, which reads all subprocess output into
+    # `String` objects before returning.  Use this class (via
+    # {Git::ExecutionContext#command_capturing}) for the vast majority of git subcommands whose
+    # output fits comfortably in memory.
+    #
+    # {Git::CommandLine::Streaming} is the complementary strategy for commands
+    # (such as `cat-file -p <blob>`) whose stdout may be too large to buffer.
+    #
+    # @example
+    #   capturing = Git::CommandLine::Capturing.new(
+    #     {}, '/usr/bin/git', %w[--git-dir /repo/.git], Logger.new($stdout)
+    #   )
+    #   result = capturing.run('log', '--oneline', '-5')
+    #   result.stdout   # => "abc1234 Initial commit\n..."
+    #   result.stderr   # => ""
+    #
+    # @see Git::ExecutionContext#command_capturing
+    #
+    # @see Git::CommandLine::Streaming
+    #
+    # @api private
+    #
+    class Capturing < Git::CommandLine::Base
+      # Default options accepted by {#run}
+      #
+      # @api private
+      RUN_OPTION_DEFAULTS = {
+        in: nil,
+        out: nil,
+        err: nil,
+        chdir: nil,
+        timeout: nil,
+        raise_on_failure: true,
+        env: {},
+        normalize: false,
+        chomp: false,
+        merge: false
+      }.freeze
+
+      # Execute a git command, capture stdout and stderr, and return the result
+      #
+      # Non-option command-line arguments to pass to git. If you collect the
+      # arguments in an array, splat the array into the parameter list.
+      #
+      # NORMALIZATION
+      #
+      # The command output is returned as a Unicode string containing the binary
+      # output from the command.  If the binary output is not valid UTF-8, the
+      # output will cause problems because the encoding will be invalid.
+      #
+      # Normalization is a process that tries to convert the binary output to a
+      # valid UTF-8 string.  It uses the `rchardet` gem to detect the encoding of
+      # the binary output and then converts it to UTF-8.
+      #
+      # Normalization is not enabled by default.  Pass `normalize: true` to enable
+      # it. When enabled, normalization is applied to both stdout and stderr in
+      # the returned result object, regardless of the `out:` or `err:` options.
+      # Only the captured in-memory strings are normalized; any external IO you
+      # provide will receive the raw subprocess output.
+      #
+      # @example Run a command and return the output
+      #   result = capturing.run('version')
+      #   result.stdout #=> "git version 2.39.1\n"
+      #
+      # @example The args array should be splatted into the parameter list
+      #   args = %w[log -n 1 --oneline]
+      #   result = capturing.run(*args)
+      #   result.stdout #=> "f5baa11 beginning of Ruby/Git project\n"
+      #
+      # @example Run a command and return the chomped output
+      #   result = capturing.run('version', chomp: true)
+      #   result.stdout #=> "git version 2.39.1"
+      #
+      # @example Run a command without normalizing the output
+      #   capturing.run('version', normalize: false) #=> "git version 2.39.1\n"
+      #
+      # @example Capture stdout in a temporary file
+      #   require 'tempfile'
+      #   Tempfile.create('git') do |file|
+      #     capturing.run('version', out: file)
+      #     file.rewind
+      #     file.read #=> "git version 2.39.1\n"
+      #   end
+      #
+      # @example Capture stderr in a StringIO object
+      #   require 'stringio'
+      #   stderr = StringIO.new
+      #   begin
+      #     capturing.run('log', 'nonexistent-branch', err: stderr)
+      #   rescue Git::FailedError => e
+      #     stderr.string #=> "unknown revision or path not in the working tree.\n"
+      #   end
+      #
+      # @param options_hash [Hash] the options to pass to the command
+      #
+      # @option options_hash [IO, nil] :in the IO object to use as stdin for the
+      #   command, or nil to inherit the parent process stdin.  Must be a real IO
+      #   object with a file descriptor (not StringIO).
+      #
+      # @option options_hash [#write, nil] :out the object to write stdout to, or
+      #   nil to capture stdout in the returned result.
+      #
+      #   If this is a `StringIO` object, `stdout_writer.string` will be returned.
+      #
+      #   In general, only specify a `stdout_writer` when you want to redirect
+      #   stdout to a file or other `#write`-responding object.  The default
+      #   behaviour returns the command output.
+      #
+      # @option options_hash [#write, nil] :err the object to write stderr to, or
+      #   nil to capture stderr in the returned result.
+      #
+      # @option options_hash [Boolean] :normalize (false) whether to normalize the
+      #   encoding of stdout and stderr output
+      #
+      # @option options_hash [Boolean] :chomp (false) whether to chomp both stdout
+      #   and stderr output
+      #
+      # @option options_hash [Boolean] :merge (false) whether to merge stdout and
+      #   stderr in the returned string
+      #
+      # @option options_hash [String, nil] :chdir the directory to run the command in
+      #
+      # @option options_hash [Numeric, nil] :timeout the maximum seconds to wait for
+      #   the command to complete.  Zero means no timeout.  A timeout kills the
+      #   process via `SIGKILL` and raises {Git::TimeoutError}.
+      #
+      # @option options_hash [Boolean] :raise_on_failure (true) whether to raise
+      #   {Git::FailedError} on non-zero exit status.
+      #   {Git::TimeoutError} and {Git::SignaledError} are always raised regardless.
+      #
+      # @option options_hash [Hash] :env ({}) additional environment variable
+      #   overrides for this command.  String keys map to String values (to set) or
+      #   `nil` (to unset).
+      #
+      # @return [Git::CommandLine::Result] the result of the command
+      #
+      # @raise [ArgumentError] if `args` contains an array or an unknown option is
+      #   passed
+      #
+      # @raise [Git::SignaledError] if the command was terminated by an uncaught signal
+      #
+      # @raise [Git::FailedError] if the command returned a non-zero exit status
+      #
+      # @raise [Git::ProcessIOError] if an exception was raised while collecting
+      #   subprocess output, or (Ruby 4.0+) if a timeout-handling race causes
+      #   `Errno::ESRCH` when the spawned process exits between the timeout
+      #   firing and the kill signal being delivered
+      #
+      # @raise [Git::TimeoutError] if the command times out
+      #
+      def run(*, **options_hash)
+        options = merge_and_validate_options(RUN_OPTION_DEFAULTS, options_hash)
+
+        result = execute(*, **options)
+        process_result(result, options)
+      end
+
+      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 = execution_options(**options_hash)
+        run_process_executer do
+          ProcessExecuter.run_with_capture(merged_env(options_hash), *git_cmd, **options)
+        end
+      end
+
+      # 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 execution_options(**options_hash)
+        chdir = options_hash[:chdir] || :not_set
+        timeout_after = options_hash[:timeout]
+        merge_output = options_hash[:merge] || false
+
+        { chdir:, timeout_after:, merge_output:, raise_errors: false }.tap do |options|
+          redirect_options(options_hash).each { |k, v| options[k] = v }
+        end
+      end
+
+      # Extract non-nil redirect options (`:in`, `:out`, `:err`) from `options`
+      #
+      # @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)
+        %i[in out err].filter_map do |key|
+          val = options[key]
+          [key, val] unless val.nil?
+        end.to_h
+      end
+
+      # Post-process and return the stdout/stderr strings from the captured result,
+      # then log and raise on failure if required.
+      #
+      # @param result [ProcessExecuter::ResultWithCapture] the raw result
+      #
+      # @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::CommandLine::Result]
+      #
+      # @raise [Git::FailedError] if the command failed and raise_on_failure is true
+      #
+      # @raise [Git::SignaledError] if the command was signaled
+      #
+      # @raise [Git::TimeoutError] if the command timed out
+      #
+      # @api private
+      def process_result(result, options)
+        command = result.command
+        processed_out, processed_err = post_process_output(result, options[:normalize], options[:chomp])
+        log_result(result, command, processed_out, processed_err)
+        command_line_result(
+          command, result, processed_out, processed_err, options[:timeout], options[:raise_on_failure]
+        )
+      end
+
+      # Normalize and/or chomp the raw stdout and stderr strings.
+      #
+      # @param result [ProcessExecuter::ResultWithCapture] the raw result
+      #
+      # @param normalize [Boolean]
+      #
+      # @param chomp [Boolean]
+      #
+      # @return [Array<String>] two-element array: [processed_stdout, processed_stderr]
+      #
+      # @api private
+      def post_process_output(result, normalize, chomp)
+        [result.stdout, result.stderr].map do |raw_output|
+          output = raw_output.dup
+          output = output.lines.map { |l| Git::EncodingUtils.normalize_encoding(l) }.join if normalize
+          output.chomp! if chomp
+          output
+        end
+      end
+    end
+  end
+end

data/lib/git/command_line/result.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Git
+  module CommandLine
+    # The result of running a git command
+    #
+    # This object stores the Git command executed and its status, stdout, and stderr.
+    #
+    # @api public
+    #
+    class Result
+      # Create a Result object
+      #
+      # @example
+      #   git_cmd = %w[git version]
+      #   status = instance_double(ProcessExecuter::Result)
+      #   stdout = "git version 2.39.1\n"
+      #   stderr = ""
+      #   result = Git::CommandLine::Result.new(git_cmd, status, stdout, stderr)
+      #
+      # @param git_cmd [Array<String>] the git command that was executed
+      #
+      # @param status [ProcessExecuter::Result] the process result object returned
+      #   by `ProcessExecuter.run` or `ProcessExecuter.run_with_capture`.
+      #   Responds to `timed_out?`, `signaled?`, and `success?`.
+      #
+      # @param stdout [String] the processed stdout of the process
+      #
+      # @param stderr [String] the processed stderr of the process
+      #
+      def initialize(git_cmd, status, stdout, stderr)
+        @git_cmd = git_cmd
+        @status = status
+        @stdout = stdout
+        @stderr = stderr
+      end
+
+      # The git command that was executed
+      #
+      # @example
+      #   git_cmd = %w[git version]
+      #   result = Git::CommandLine::Result.new(git_cmd, nil, '', '')
+      #   result.git_cmd #=> ["git", "version"]
+      #
+      # @return [Array<String>]
+      #
+      attr_reader :git_cmd
+
+      # The process result object returned by ProcessExecuter
+      #
+      # In practice this is a `ProcessExecuter::ResultWithCapture` (from
+      # {Git::CommandLine::Capturing}) or a `ProcessExecuter::Result` (from
+      # {Git::CommandLine::Streaming}). Both respond to `success?`, `timed_out?`,
+      # and `signaled?`.
+      #
+      # @example
+      #   status = instance_double(ProcessExecuter::Result, success?: true)
+      #   result = Git::CommandLine::Result.new(%w[git version], status, '', '')
+      #   result.status == status #=> true
+      #
+      # @return [ProcessExecuter::Result]
+      #
+      attr_reader :status
+
+      # The output of the process
+      #
+      # @example
+      #   stdout = "git version 2.39.1\n"
+      #   result = Git::CommandLine::Result.new([], nil, stdout, '')
+      #   result.stdout #=> "git version 2.39.1\n"
+      #
+      # @return [String]
+      #
+      attr_reader :stdout
+
+      # The error output of the process
+      #
+      # @example
+      #   stderr = "Tag not found\n"
+      #   result = Git::CommandLine::Result.new([], nil, '', stderr)
+      #   result.stderr #=> "Tag not found\n"
+      #
+      # @return [String]
+      #
+      attr_reader :stderr
+    end
+  end
+end