git 1.19.1 → 4.4.5

data/lib/git/command_line.rb

@@ -0,0 +1,330 @@
+# frozen_string_literal: true
+
+require 'git/base'
+require 'git/command_line_result'
+require 'git/errors'
+require 'stringio'
+
+module Git
+  # Runs a git command and returns the result
+  #
+  # @api public
+  #
+  class CommandLine
+    # Create a Git::CommandLine object
+    #
+    # @example
+    #   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 = CommandLine.new(env, binary_path, global_opts, logger)
+    #   cli.run('version') #=> #<Git::CommandLineResult:0x00007f9b0c0b0e00
+    #
+    # @param env [Hash<String, String>] environment variables to set
+    # @param global_opts [Array<String>] global options to pass to git
+    # @param logger [Logger] the logger to use
+    #
+    def initialize(env, binary_path, global_opts, logger)
+      @env = env
+      @binary_path = binary_path
+      @global_opts = global_opts
+      @logger = logger
+    end
+
+    # @attribute [r] env
+    #
+    # Variables to set (or unset) in the git command's environment
+    #
+    # @example
+    #   env = { 'GIT_DIR' => '/path/to/git/dir' }
+    #   command_line = Git::CommandLine.new(env, '/usr/bin/git', [], Logger.new(STDOUT))
+    #   command_line.env #=> { 'GIT_DIR' => '/path/to/git/dir' }
+    #
+    # @return [Hash<String, String>]
+    #
+    # @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
+
+    # @attribute [r] binary_path
+    #
+    # The path to the command line binary to run
+    #
+    # @example
+    #   binary_path = '/usr/bin/git'
+    #   command_line = Git::CommandLine.new({}, binary_path, ['version'], Logger.new(STDOUT))
+    #   command_line.binary_path #=> '/usr/bin/git'
+    #
+    # @return [String]
+    #
+    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
+    # arguments. For example, in `git --git-dir /path/to/git/dir version`, the
+    # global options are %w[--git-dir /path/to/git/dir].
+    #
+    # @example
+    #   env = {}
+    #   global_opts = %w[--git-dir /path/to/git/dir]
+    #   logger = Logger.new(nil)
+    #   cli = CommandLine.new(env, '/usr/bin/git', global_opts, logger)
+    #   cli.global_opts #=> %w[--git-dir /path/to/git/dir]
+    #
+    # @return [Array<String>]
+    #
+    attr_reader :global_opts
+
+    # @attribute [r] logger
+    #
+    # The logger to use for logging git commands and results
+    #
+    # @example
+    #   env = {}
+    #   global_opts = %w[]
+    #   logger = Logger.new(STDOUT)
+    #   cli = CommandLine.new(env, '/usr/bin/git', global_opts, logger)
+    #   cli.logger == logger #=> true
+    #
+    # @return [Logger]
+    #
+    attr_reader :logger
+
+    # Execute a git command, wait for it to finish, and return the result
+    #
+    # Non-option the command line arguements to pass to git. If you collect
+    # the command line arguments in an array, make sure you splat the array
+    # into the parameter list.
+    #
+    # NORMALIZATION
+    #
+    # The command output is returned as a Unicde 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 trys 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 Git::CommandLine#run
+    # to enable it. Normalization will only be performed on stdout and only if the `out:`` option
+    # is nil or is a StringIO object. If the out: option is set to a file or other IO object,
+    # the normalize option will be ignored.
+    #
+    # @example Run a command and return the output
+    #   cli.run('version') #=> "git version 2.39.1\n"
+    #
+    # @example The args array should be splatted into the parameter list
+    #   args = %w[log -n 1 --oneline]
+    #   cli.run(*args) #=> "f5baa11 beginning of Ruby/Git project\n"
+    #
+    # @example Run a command and return the chomped output
+    #   cli.run('version', chomp: true) #=> "git version 2.39.1"
+    #
+    # @example Run a command and without normalizing the output
+    #   cli.run('version', normalize: false) #=> "git version 2.39.1\n"
+    #
+    # @example Capture stdout in a temporary file
+    #   require 'tempfile'
+    #   tempfile = Tempfile.create('git') do |file|
+    #     cli.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
+    #     cli.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 [#write, nil] :out the object to write stdout to or nil to ignore stdout
+    #
+    #   If this is a 'StringIO' object, then `stdout_writer.string` will be returned.
+    #
+    #   In general, only specify a `stdout_writer` object when you want to redirect
+    #   stdout to a file or some other object that responds to `#write`. The default
+    #   behavior will return the output of the command.
+    #
+    # @option options_hash [#write, nil] :err the object to write stderr to or nil to ignore stderr
+    #
+    #   If this is a 'StringIO' object and `merged_output` is `true`, then
+    #   `stderr_writer.string` will be merged into the output returned by this method.
+    #
+    # @option options_hash [Boolean] :normalize whether to normalize the output of stdout and stderr
+    #
+    # @option options_hash [Boolean] :chomp whether to chomp both stdout and stderr output
+    #
+    # @option options_hash [Boolean] :merge whether to merge stdout and stderr in the string returned
+    #
+    # @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
+    #
+    #   If timeout is zero, the timeout will not be enforced.
+    #
+    #   If the command times out, it is killed via a `SIGKILL` signal and `Git::TimeoutError` is raised.
+    #
+    #   If the command does not respond to SIGKILL, it will hang this method.
+    #
+    # @return [Git::CommandLineResult] the output of the command
+    #
+    #   This result of running the command.
+    #
+    # @raise [ArgumentError] if `args` is not an array of strings
+    #
+    # @raise [Git::SignaledError] if the command was terminated because of an uncaught signal
+    #
+    # @raise [Git::FailedError] if the command returned a non-zero exitstatus
+    #
+    # @raise [Git::ProcessIOError] if an exception was raised while collecting subprocess output
+    #
+    # @raise [Git::TimeoutError] if the command times out
+    #
+    def run(*, **options_hash)
+      options_hash = RUN_ARGS.merge(options_hash)
+      extra_options = options_hash.keys - RUN_ARGS.keys
+      raise ArgumentError, "Unknown options: #{extra_options.join(', ')}" if extra_options.any?
+
+      result = run_with_capture(*, **options_hash)
+      process_result(result, options_hash[:normalize], options_hash[:chomp], options_hash[:timeout])
+    end
+
+    # @return [Git::CommandLineResult] the result of running the command
+    #
+    # @api private
+    #
+    def run_with_capture(*args, **options_hash)
+      git_cmd = build_git_cmd(args)
+      options = run_with_capture_options(**options_hash)
+      ProcessExecuter.run_with_capture(env, *git_cmd, **options)
+    rescue ProcessExecuter::ProcessIOError => e
+      raise Git::ProcessIOError.new(e.message), cause: e.exception.cause
+    end
+
+    def run_with_capture_options(**options_hash)
+      chdir = options_hash[:chdir] || :not_set
+      timeout_after = options_hash[:timeout]
+      out = options_hash[:out]
+      err = options_hash[:err]
+      merge_output = options_hash[:merge] || false
+
+      { chdir:, timeout_after:, merge_output:, raise_errors: false }.tap do |options|
+        options[:out] = out unless out.nil?
+        options[:err] = err unless err.nil?
+      end
+    end
+
+    RUN_ARGS = {
+      normalize: false,
+      chomp: false,
+      merge: false,
+      out: nil,
+      err: nil,
+      chdir: nil,
+      timeout: nil
+    }.freeze
+
+    private
+
+    # Build the git command line from the available sources to send to `Process.spawn`
+    # @return [Array<String>]
+    # @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
+
+    # Process the result of the command and return a Git::CommandLineResult
+    #
+    # Post process output, log the command and result, and raise an error if the
+    # command failed.
+    #
+    # @param result [ProcessExecuter::Command::Result] the result it is a
+    #   Process::Status and include command, stdout, and stderr
+    #
+    # @param normalize [Boolean] whether to normalize the output of each writer
+    #
+    # @param chomp [Boolean] whether to chomp the output of each writer
+    #
+    # @param timeout [Numeric, nil] the maximum seconds to wait for the command to
+    #   complete
+    #
+    # @return [Git::CommandLineResult] the result of the command to return to the
+    #   caller
+    #
+    # @raise [Git::FailedError] if the command failed
+    #
+    # @raise [Git::SignaledError] if the command was signaled
+    #
+    # @raise [Git::TimeoutError] if the command times out
+    #
+    # @raise [Git::ProcessIOError] if an exception was raised while collecting
+    #   subprocess output
+    #
+    # @api private
+    #
+    def process_result(result, normalize, chomp, timeout)
+      command = result.command
+      processed_out, processed_err = post_process_output(result, normalize, chomp)
+      log_result(result, command, processed_out, processed_err)
+      command_line_result(command, result, processed_out, processed_err, timeout)
+    end
+
+    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
+
+    def command_line_result(command, result, processed_out, processed_err, timeout)
+      Git::CommandLineResult.new(command, result, processed_out, processed_err).tap do |processed_result|
+        raise Git::TimeoutError.new(processed_result, timeout) if result.timeout?
+
+        raise Git::SignaledError, processed_result if result.signaled?
+
+        raise Git::FailedError, processed_result unless result.success?
+      end
+    end
+
+    # Post-process and return an array of raw output strings
+    #
+    # For each raw output string:
+    #
+    # * If normalize: is true, normalize the encoding by transcoding each line from
+    #   the detected encoding to UTF-8.
+    # * If chomp: is true chomp the output after normalization.
+    #
+    # Even if no post-processing is done based on the options, the strings returned
+    # are a copy of the raw output strings. The raw output strings are not modified.
+    #
+    # @param result [ProcessExecuter::ResultWithCapture] the command's output to post-process
+    #
+    # @param normalize [Boolean] whether to normalize the output of each writer
+    # @param chomp [Boolean] whether to chomp the output of each writer
+    #
+    # @return [Array<String>]
+    #
+    # @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

data/lib/git/command_line_result.rb

@@ -19,15 +19,21 @@ module Git
     #   result = Git::CommandLineResult.new(git_cmd, status, stdout, stderr)
     #
     # @param git_cmd [Array<String>] the git command that was executed
-    # @param status [Process::Status] the status of the process
-    # @param stdout [String] the output of the process
-    # @param stderr [String] the error output of the process
+    # @param status [ProcessExecuter::ResultWithCapture] the status of the process
+    # @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
+
+      # ProcessExecuter::ResultWithCapture changed the timeout? method to timed_out?
+      # in version 4.x. This is a compatibility layer to maintain the old method name
+      # for backward compatibility.
+      #
+      status.define_singleton_method(:timeout?) { timed_out? }
     end
 
     # @attribute [r] git_cmd

data/lib/git/config.rb

@@ -1,22 +1,26 @@
-module Git
+# frozen_string_literal: true
 
+module Git
+  # The global configuration for this gem
   class Config
-
-    attr_writer :binary_path, :git_ssh
+    attr_writer :binary_path, :git_ssh, :timeout
 
     def initialize
       @binary_path = nil
       @git_ssh = nil
+      @timeout = nil
     end
 
     def binary_path
-      @binary_path || ENV['GIT_PATH'] && File.join(ENV['GIT_PATH'], 'git') || 'git'
+      @binary_path || (ENV.fetch('GIT_PATH', nil) && File.join(ENV.fetch('GIT_PATH', nil), 'git')) || 'git'
     end
 
     def git_ssh
-      @git_ssh || ENV['GIT_SSH']
+      @git_ssh || ENV.fetch('GIT_SSH', nil)
     end
 
+    def timeout
+      @timeout || (ENV.fetch('GIT_TIMEOUT', nil) && ENV['GIT_TIMEOUT'].to_i)
+    end
   end
-
 end

data/lib/git/diff.rb

@@ -1,78 +1,110 @@
-module Git
+# frozen_string_literal: true
+
+require_relative 'diff_path_status'
+require_relative 'diff_stats'
 
-  # object that holds the last X commits on given branch
+module Git
+  # object that holds the diff between two commits
   class Diff
     include Enumerable
 
     def initialize(base, from = nil, to = nil)
       @base = base
-      @from = from && from.to_s
-      @to = to && to.to_s
+      @from = from&.to_s
+      @to = to&.to_s
 
       @path = nil
-      @full_diff = nil
       @full_diff_files = nil
-      @stats = nil
     end
     attr_reader :from, :to
 
-    def name_status
-      cache_name_status
+    # Limits the diff to the specified path(s)
+    #
+    # When called with no arguments (or only nil arguments), removes any existing
+    # path filter, showing all files in the diff. Internally stores a single path
+    # as a String and multiple paths as an Array for efficiency.
+    #
+    # @example Limit diff to a single path
+    #   git.diff('HEAD~3', 'HEAD').path('lib/')
+    #
+    # @example Limit diff to multiple paths
+    #   git.diff('HEAD~3', 'HEAD').path('src/', 'docs/', 'README.md')
+    #
+    # @example Remove path filtering (show all files)
+    #   diff.path  # or diff.path(nil)
+    #
+    # @param paths [String, Pathname] one or more paths to filter the diff. Pass no arguments to remove filtering.
+    # @return [self] returns self for method chaining
+    # @raise [ArgumentError] if any path is an Array (use splatted arguments instead)
+    #
+    def path(*paths)
+      validate_paths_not_arrays(paths)
+
+      cleaned_paths = paths.compact
+
+      @path = if cleaned_paths.empty?
+                nil
+              elsif cleaned_paths.length == 1
+                cleaned_paths.first
+              else
+                cleaned_paths
+              end
+
+      self
     end
 
-    def path(path)
-      @path = path
-      return self
+    def patch
+      @base.lib.diff_full(@from, @to, { path_limiter: @path })
     end
+    alias to_s patch
 
-    def size
-      cache_stats
-      @stats[:total][:files]
+    def [](key)
+      process_full
+      @full_diff_files.assoc(key)[1]
     end
 
-    def lines
-      cache_stats
-      @stats[:total][:lines]
+    def each(&)
+      process_full
+      @full_diff_files.map { |file| file[1] }.each(&)
     end
 
-    def deletions
-      cache_stats
-      @stats[:total][:deletions]
+    def size
+      stats_provider.total[:files]
     end
 
-    def insertions
-      cache_stats
-      @stats[:total][:insertions]
-    end
+    #
+    # DEPRECATED METHODS
+    #
 
-    def stats
-      cache_stats
-      @stats
+    def name_status
+      path_status_provider.to_h
     end
 
-    # if file is provided and is writable, it will write the patch into the file
-    def patch(file = nil)
-      cache_full
-      @full_diff
+    def lines
+      stats_provider.lines
     end
-    alias_method :to_s, :patch
 
-    # enumerable methods
+    def deletions
+      stats_provider.deletions
+    end
 
-    def [](key)
-      process_full
-      @full_diff_files.assoc(key)[1]
+    def insertions
+      stats_provider.insertions
     end
 
-    def each(&block) # :yields: each Git::DiffFile in turn
-      process_full
-      @full_diff_files.map { |file| file[1] }.each(&block)
+    def stats
+      {
+        files: stats_provider.files,
+        total: stats_provider.total
+      }
     end
 
+    # The changes for a single file within a diff
     class DiffFile
       attr_accessor :patch, :path, :mode, :src, :dst, :type
+
       @base = nil
-      NIL_BLOB_REGEXP = /\A0{4,40}\z/.freeze
+      NIL_BLOB_REGEXP = /\A0{4,40}\z/
 
       def initialize(base, hash)
         @base = base
@@ -100,56 +132,92 @@ module Git
 
     private
 
-      def cache_full
-        @full_diff ||= @base.lib.diff_full(@from, @to, {:path_limiter => @path})
+    def validate_paths_not_arrays(paths)
+      return unless paths.any?(Array)
+
+      raise ArgumentError,
+            'path expects individual arguments, not arrays. ' \
+            "Use path('lib/', 'docs/') not path(['lib/', 'docs/'])"
+    end
+
+    def process_full
+      return if @full_diff_files
+
+      @full_diff_files = process_full_diff
+    end
+
+    def path_status_provider
+      @path_status_provider ||= Git::DiffPathStatus.new(@base, @from, @to, @path)
+    end
+
+    def stats_provider
+      @stats_provider ||= Git::DiffStats.new(@base, @from, @to, @path)
+    end
+
+    def process_full_diff
+      FullDiffParser.new(@base, patch).parse
+    end
+
+    # A private parser class to process the output of `git diff`
+    # @api private
+    class FullDiffParser
+      def initialize(base, patch_text)
+        @base = base
+        @patch_text = patch_text
+        @final_files = {}
+        @current_file_data = nil
+        @defaults = { mode: '', src: '', dst: '', type: 'modified', binary: false }
       end
 
-      def process_full
-        return if @full_diff_files
-        cache_full
-        @full_diff_files = process_full_diff
+      def parse
+        @patch_text.split("\n").each { |line| process_line(line) }
+        @final_files.map { |filename, data| [filename, DiffFile.new(@base, data)] }
       end
 
-      def cache_stats
-        @stats ||=  @base.lib.diff_stats(@from, @to, {:path_limiter => @path})
+      private
+
+      def process_line(line)
+        if (new_file_match = line.match(%r{\Adiff --git ("?)a/(.+?)\1 ("?)b/(.+?)\3\z}))
+          start_new_file(new_file_match, line)
+        else
+          append_to_current_file(line)
+        end
       end
 
-      def cache_name_status
-        @name_status ||= @base.lib.diff_name_status(@from, @to, {:path => @path})
+      def start_new_file(match, line)
+        filename = Git::EscapedPath.new(match[2]).unescape
+        @current_file_data = @defaults.merge({ patch: line, path: filename })
+        @final_files[filename] = @current_file_data
       end
 
-      # break up @diff_full
-      def process_full_diff
-        defaults = {
-          :mode => '',
-          :src => '',
-          :dst => '',
-          :type => 'modified'
-        }
-        final = {}
-        current_file = nil
-        @full_diff.split("\n").each do |line|
-          if m = %r{\Adiff --git ("?)a/(.+?)\1 ("?)b/(.+?)\3\z}.match(line)
-            current_file = Git::EscapedPath.new(m[2]).unescape
-            final[current_file] = defaults.merge({:patch => line, :path => current_file})
-          else
-            if m = /^index ([0-9a-f]{4,40})\.\.([0-9a-f]{4,40})( ......)*/.match(line)
-              final[current_file][:src] = m[1]
-              final[current_file][:dst] = m[2]
-              final[current_file][:mode] = m[3].strip if m[3]
-            end
-            if m = /^([[:alpha:]]*?) file mode (......)/.match(line)
-              final[current_file][:type] = m[1]
-              final[current_file][:mode] = m[2]
-            end
-            if m = /^Binary files /.match(line)
-              final[current_file][:binary] = true
-            end
-            final[current_file][:patch] << "\n" + line
-          end
-        end
-        final.map { |e| [e[0], DiffFile.new(@base, e[1])] }
+      def append_to_current_file(line)
+        return unless @current_file_data
+
+        parse_index_line(line)
+        parse_file_mode_line(line)
+        check_for_binary(line)
+
+        @current_file_data[:patch] << "\n#{line}"
       end
 
+      def parse_index_line(line)
+        return unless (match = line.match(/^index ([0-9a-f]{4,40})\.\.([0-9a-f]{4,40})( ......)*/))
+
+        @current_file_data[:src] = match[1]
+        @current_file_data[:dst] = match[2]
+        @current_file_data[:mode] = match[3].strip if match[3]
+      end
+
+      def parse_file_mode_line(line)
+        return unless (match = line.match(/^([[:alpha:]]*?) file mode (......)/))
+
+        @current_file_data[:type] = match[1]
+        @current_file_data[:mode] = match[2]
+      end
+
+      def check_for_binary(line)
+        @current_file_data[:binary] = true if line.match?(/^Binary files /)
+      end
+    end
   end
 end