git 1.19.1 → 2.0.0

data/lib/git/errors.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+module Git
+  # Base class for all custom git module errors
+  #
+  # The git gem will only raise an `ArgumentError` or an error that is a subclass of
+  # `Git::Error`. It does not explicitly raise any other types of errors.
+  #
+  # It is recommended to rescue `Git::Error` to catch any runtime error raised by
+  # this gem unless you need more specific error handling.
+  #
+  # Git's custom errors are arranged in the following class heirarchy:
+  #
+  # ```text
+  # StandardError
+  # └─> Git::Error
+  #     ├─> Git::CommandLineError
+  #     │   ├─> Git::FailedError
+  #     │   └─> Git::SignaledError
+  #     │       └─> Git::TimeoutError
+  #     ├─> Git::ProcessIOError
+  #     └─> Git::UnexpectedResultError
+  # ```
+  #
+  # | Error Class | Description |
+  # | --- | --- |
+  # | `Error` | This catch-all error serves as the base class for other custom errors raised by the git gem. |
+  # | `CommandLineError` | A subclass of this error is raised when there is a problem executing the git command line. |
+  # | `FailedError` | This error is raised when the git command line exits with a non-zero status code that is not expected by the git gem. |
+  # | `SignaledError` | This error is raised when the git command line is terminated as a result of receiving a signal. This could happen if the process is forcibly terminated or if there is a serious system error. |
+  # | `TimeoutError` | This is a specific type of `SignaledError` that is raised when the git command line operation times out and is killed via the SIGKILL signal. This happens if the operation takes longer than the timeout duration configured in `Git.config.timeout` or via the `:timeout` parameter given in git methods that support timeouts. |
+  # | `ProcessIOError` | An error was encountered reading or writing to a subprocess. |
+  # | `UnexpectedResultError` | The command line ran without error but did not return the expected results. |
+  #
+  # @example Rescuing a generic error
+  #   begin
+  #     # some git operation
+  #   rescue Git::Error => e
+  #     puts "An error occurred: #{e.message}"
+  #   end
+  #
+  # @example Rescuing a timeout error
+  #   begin
+  #     timeout_duration = 0.001 # seconds
+  #     repo = Git.clone('https://github.com/ruby-git/ruby-git', 'ruby-git-temp', timeout: timeout_duration)
+  #   rescue Git::TimeoutError => e # Catch the more specific error first!
+  #     puts "Git clone took too long and timed out #{e}"
+  #   rescue Git::Error => e
+  #     puts "Received the following error: #{e}"
+  #   end
+  #
+  # @see Git::CommandLineError
+  # @see Git::FailedError
+  # @see Git::SignaledError
+  # @see Git::TimeoutError
+  # @see Git::ProcessIOError
+  # @see Git::UnexpectedResultError
+  #
+  # @api public
+  #
+  class Error < StandardError; end
+
+  # An alias for Git::Error
+  #
+  # Git::GitExecuteError error class is an alias for Git::Error for backwards
+  # compatibility. It is recommended to use Git::Error directly.
+  #
+  # @deprecated Use Git::Error instead
+  #
+  GitExecuteError = ActiveSupport::Deprecation::DeprecatedConstantProxy.new('Git::GitExecuteError', 'Git::Error', Git::Deprecation)
+
+  # Raised when a git command fails or exits because of an uncaught signal
+  #
+  # The git command executed, status, stdout, and stderr are available from this
+  # object.
+  #
+  # The Gem will raise a more specific error for each type of failure:
+  #
+  # * {Git::FailedError}: when the git command exits with a non-zero status
+  # * {Git::SignaledError}: when the git command exits because of an uncaught signal
+  # * {Git::TimeoutError}: when the git command times out
+  #
+  # @api public
+  #
+  class CommandLineError < Git::Error
+    # Create a CommandLineError object
+    #
+    # @example
+    #   `exit 1` # set $? appropriately for this example
+    #   result = Git::CommandLineResult.new(%w[git status], $?, 'stdout', 'stderr')
+    #   error = Git::CommandLineError.new(result)
+    #   error.to_s #=> '["git", "status"], status: pid 89784 exit 1, stderr: "stderr"'
+    #
+    # @param result [Git::CommandLineResult] the result of the git command including
+    #   the git command, status, stdout, and stderr
+    #
+    def initialize(result)
+      @result = result
+      super(error_message)
+    end
+
+    # The human readable representation of this error
+    #
+    # @example
+    #   error.error_message #=> '["git", "status"], status: pid 89784 exit 1, stderr: "stderr"'
+    #
+    # @return [String]
+    #
+    def error_message = <<~MESSAGE.chomp
+      #{result.git_cmd}, status: #{result.status}, stderr: #{result.stderr.inspect}
+    MESSAGE
+
+    # @attribute [r] result
+    #
+    # The result of the git command including the git command and its status and output
+    #
+    # @example
+    #   error.result #=> #<Git::CommandLineResult:0x00000001046bd488 ...>
+    #
+    # @return [Git::CommandLineResult]
+    #
+    attr_reader :result
+  end
+
+  # This error is raised when a git command returns a non-zero exitstatus
+  #
+  # The git command executed, status, stdout, and stderr are available from this
+  # object.
+  #
+  # @api public
+  #
+  class FailedError < Git::CommandLineError; end
+
+  # This error is raised when a git command exits because of an uncaught signal
+  #
+  # @api public
+  #
+  class SignaledError < Git::CommandLineError; end
+
+  # This error is raised when a git command takes longer than the configured timeout
+  #
+  # The git command executed, status, stdout, and stderr, and the timeout duration
+  # are available from this object.
+  #
+  # result.status.timeout? will be `true`
+  #
+  # @api public
+  #
+  class TimeoutError < Git::SignaledError
+    # Create a TimeoutError object
+    #
+    # @example
+    #   command = %w[sleep 10]
+    #   timeout_duration = 1
+    #   status = ProcessExecuter.spawn(*command, timeout: timeout_duration)
+    #   result = Git::CommandLineResult.new(command, status, 'stdout', 'err output')
+    #   error = Git::TimeoutError.new(result, timeout_duration)
+    #   error.error_message #=> '["sleep", "10"], status: pid 70144 SIGKILL (signal 9), stderr: "err output", timed out after 1s'
+    #
+    # @param result [Git::CommandLineResult] the result of the git command including
+    #   the git command, status, stdout, and stderr
+    #
+    # @param timeout_duration [Numeric] the amount of time the subprocess was allowed
+    #   to run before being killed
+    #
+    def initialize(result, timeout_duration)
+      @timeout_duration = timeout_duration
+      super(result)
+    end
+
+    # The human readable representation of this error
+    #
+    # @example
+    #   error.error_message #=> '["sleep", "10"], status: pid 88811 SIGKILL (signal 9), stderr: "err output", timed out after 1s'
+    #
+    # @return [String]
+    #
+    def error_message = <<~MESSAGE.chomp
+      #{super}, timed out after #{timeout_duration}s
+    MESSAGE
+
+    # The amount of time the subprocess was allowed to run before being killed
+    #
+    # @example
+    #   `kill -9 $$` # set $? appropriately for this example
+    #   result = Git::CommandLineResult.new(%w[git status], $?, '', "killed")
+    #   error = Git::TimeoutError.new(result, 10)
+    #   error.timeout_duration #=> 10
+    #
+    # @return [Numeric]
+    #
+    attr_reader :timeout_duration
+  end
+
+  # Raised when the output of a git command can not be read
+  #
+  # @api public
+  #
+  class ProcessIOError < Git::Error; end
+
+  # Raised when the git command result was not as expected
+  #
+  # @api public
+  #
+  class UnexpectedResultError < Git::Error; end
+end

data/lib/git/lib.rb

@@ -1,14 +1,15 @@
-require 'git/failed_error'
+require 'git/command_line'
+require 'git/errors'
 require 'logger'
+require 'pp'
+require 'process_executer'
+require 'stringio'
 require 'tempfile'
 require 'zlib'
 require 'open3'
 
 module Git
   class Lib
-
-    @@semaphore = Mutex.new
-
     # The path to the Git working copy.  The default is '"./.git"'.
     #
     # @return [Pathname] the path to the Git working copy.
@@ -79,22 +80,34 @@ module Git
       command('init', *arr_opts)
     end
 
-    # tries to clone the given repo
+    # Clones a repository into a newly created directory
     #
-    # accepts options:
-    #  :bare::      no working directory
-    #  :branch::    name of branch to track (rather than 'master')
-    #  :depth::     the number of commits back to pull
-    #  :filter::    specify partial clone
-    #  :origin::    name of remote (same as remote)
-    #  :path::      directory where the repo will be cloned
-    #  :remote::    name of remote (rather than 'origin')
-    #  :recursive:: after the clone is created, initialize all submodules within, using their default settings.
+    # @param [String] repository_url the URL of the repository to clone
+    # @param [String, nil] directory the directory to clone into
+    #
+    #   If nil, the repository is cloned into a directory with the same name as
+    #   the repository.
+    #
+    # @param [Hash] opts the options for this command
     #
-    # TODO - make this work with SSH password or auth_key
+    # @option opts [Boolean] :bare (false) if true, clone as a bare repository
+    # @option opts [String] :branch the branch to checkout
+    # @option opts [String, Array] :config one or more configuration options to set
+    # @option opts [Integer] :depth the number of commits back to pull
+    # @option opts [String] :filter specify partial clone
+    # @option opts [String] :mirror set up a mirror of the source repository
+    # @option opts [String] :origin the name of the remote
+    # @option opts [String] :path an optional prefix for the directory parameter
+    # @option opts [String] :remote the name of the remote
+    # @option opts [Boolean] :recursive after the clone is created, initialize all submodules within, using their default settings
+    # @option opts [Numeric, nil] :timeout the number of seconds to wait for the command to complete
+    #
+    #   See {Git::Lib#command} for more information about :timeout
     #
     # @return [Hash] the options to pass to {Git::Base.new}
     #
+    # @todo make this work with SSH password or auth_key
+    #
     def clone(repository_url, directory, opts = {})
       @path = opts[:path] || '.'
       clone_dir = opts[:path] ? File.join(@path, directory) : directory
@@ -114,7 +127,7 @@ module Git
       arr_opts << repository_url
       arr_opts << clone_dir
 
-      command('clone', *arr_opts)
+      command('clone', *arr_opts, timeout: opts[:timeout])
 
       return_base_opts_from_clone(clone_dir, opts)
     end
@@ -142,7 +155,7 @@ module Git
       match_data = output.match(%r{^ref: refs/heads/(?<default_branch>[^\t]+)\tHEAD$})
       return match_data[:default_branch] if match_data
 
-      raise 'Unable to determine the default branch'
+      raise Git::UnexpectedResultError, 'Unable to determine the default branch'
     end
 
     ## READ COMMANDS ##
@@ -337,7 +350,19 @@ module Git
     end
 
     def object_contents(sha, &block)
-      command('cat-file', '-p', sha, &block)
+      if block_given?
+        Tempfile.create do |file|
+          # If a block is given, write the output from the process to a temporary
+          # file and then yield the file to the block
+          #
+          command('cat-file', "-p", sha, out: file, err: file)
+          file.rewind
+          yield file
+        end
+      else
+        # If a block is not given, return stdout
+        command('cat-file', '-p', sha)
+      end
     end
 
     def ls_tree(sha)
@@ -395,7 +420,7 @@ module Git
     def branches_all
       command_lines('branch', '-a').map do |line|
         match_data = line.match(BRANCH_LINE_REGEXP)
-        raise GitExecuteError, 'Unexpected branch line format' unless match_data
+        raise Git::UnexpectedResultError, 'Unexpected branch line format' unless match_data
         next nil if match_data[:not_a_branch] || match_data[:detached_ref]
         [
           match_data[:refname],
@@ -474,11 +499,15 @@ module Git
       grep_opts.push('--', *opts[:path_limiter]) if opts[:path_limiter].is_a?(Array)
 
       hsh = {}
-      command_lines('grep', *grep_opts).each do |line|
-        if m = /(.*?)\:(\d+)\:(.*)/.match(line)
-          hsh[m[1]] ||= []
-          hsh[m[1]] << [m[2].to_i, m[3]]
+      begin
+        command_lines('grep', *grep_opts).each do |line|
+          if m = /(.*?)\:(\d+)\:(.*)/.match(line)
+            hsh[m[1]] ||= []
+            hsh[m[1]] << [m[2].to_i, m[3]]
+          end
         end
+      rescue Git::FailedError => e
+        raise unless e.result.status.exitstatus == 1 && e.result.stderr == ''
       end
       hsh
     end
@@ -865,16 +894,17 @@ module Git
 
     def conflicts # :yields: file, your, their
       self.unmerged.each do |f|
-        your_tempfile = Tempfile.new("YOUR-#{File.basename(f)}")
-        your = your_tempfile.path
-        your_tempfile.close # free up file for git command process
-        command('show', ":2:#{f}", redirect: "> #{escape your}")
-
-        their_tempfile = Tempfile.new("THEIR-#{File.basename(f)}")
-        their = their_tempfile.path
-        their_tempfile.close # free up file for git command process
-        command('show', ":3:#{f}", redirect: "> #{escape their}")
-        yield(f, your, their)
+        Tempfile.create("YOUR-#{File.basename(f)}") do |your|
+          command('show', ":2:#{f}", out: your)
+          your.close
+
+          Tempfile.create("THEIR-#{File.basename(f)}") do |their|
+            command('show', ":3:#{f}", out: their)
+            their.close
+
+            yield(f, your.path, their.path)
+          end
+        end
       end
     end
 
@@ -915,7 +945,7 @@ module Git
       opts = opts.last.instance_of?(Hash) ? opts.last : {}
 
       if (opts[:a] || opts[:annotate]) && !(opts[:m] || opts[:message])
-        raise  "Can not create an [:a|:annotate] tag without the precense of [:m|:message]."
+        raise  ArgumentError, 'Cannot create an annotated tag without a message.'
       end
 
       arr_opts = []
@@ -948,7 +978,7 @@ module Git
       arr_opts << remote if remote
       arr_opts << opts[:ref] if opts[:ref]
 
-      command('fetch', *arr_opts)
+      command('fetch', *arr_opts, merge: true)
     end
 
     def push(remote = nil, branch = nil, opts = nil)
@@ -988,10 +1018,11 @@ module Git
       end
     end
 
-    def pull(remote = nil, branch = nil)
+    def pull(remote = nil, branch = nil, opts = {})
       raise ArgumentError, "You must specify a remote if a branch is specified" if remote.nil? && !branch.nil?
 
       arr_opts = []
+      arr_opts << '--allow-unrelated-histories' if opts[:allow_unrelated_histories]
       arr_opts << remote if remote
       arr_opts << branch if branch
       command('pull', *arr_opts)
@@ -1001,7 +1032,13 @@ module Git
       head = File.join(@git_dir, 'refs', 'tags', tag_name)
       return File.read(head).chomp if File.exist?(head)
 
-      command('show-ref',  '--tags', '-s', tag_name)
+      begin
+        command('show-ref',  '--tags', '-s', tag_name)
+      rescue Git::FailedError => e
+        raise unless e.result.status.exitstatus == 1 && e.result.stderr == ''
+
+        ''
+      end
     end
 
     def repack
@@ -1026,15 +1063,12 @@ module Git
 
     def commit_tree(tree, opts = {})
       opts[:message] ||= "commit tree #{tree}"
-      t = Tempfile.new('commit-message')
-      t.write(opts[:message])
-      t.close
-
       arr_opts = []
       arr_opts << tree
       arr_opts << '-p' << opts[:parent] if opts[:parent]
-      arr_opts += Array(opts[:parents]).map { |p| ['-p', p] }.flatten if opts[:parents]
-      command('commit-tree', *arr_opts, redirect: "< #{escape t.path}")
+      Array(opts[:parents]).each { |p| arr_opts << '-p' << p } if opts[:parents]
+      arr_opts << '-m' << opts[:message]
+      command('commit-tree', *arr_opts)
     end
 
     def update_ref(ref, commit)
@@ -1080,7 +1114,11 @@ module Git
       arr_opts << "--remote=#{opts[:remote]}" if opts[:remote]
       arr_opts << sha
       arr_opts << '--' << opts[:path] if opts[:path]
-      command('archive', *arr_opts, redirect: " > #{escape file}")
+
+      f = File.open(file, 'wb')
+      command('archive', *arr_opts, out: f)
+      f.close
+
       if opts[:add_gzip]
         file_content = File.read(file)
         Zlib::GzipWriter.open(file) do |gz|
@@ -1115,7 +1153,7 @@ module Git
     end
 
     def required_command_version
-      [1, 6]
+      [2, 28]
     end
 
     def meets_required_version?
@@ -1133,11 +1171,6 @@ module Git
 
     private
 
-    # Systen ENV variables involved in the git commands.
-    #
-    # @return [<String>] the names of the EVN variables involved in the git commands
-    ENV_VARIABLE_NAMES = ['GIT_DIR', 'GIT_WORK_TREE', 'GIT_INDEX_FILE', 'GIT_SSH']
-
     def command_lines(cmd, *opts, chdir: nil)
       cmd_op = command(cmd, *opts, chdir: chdir)
       if cmd_op.encoding.name != "UTF-8"
@@ -1148,84 +1181,82 @@ module Git
       op.split("\n")
     end
 
-    # Takes the current git's system ENV variables and store them.
-    def store_git_system_env_variables
-      @git_system_env_variables = {}
-      ENV_VARIABLE_NAMES.each do |env_variable_name|
-        @git_system_env_variables[env_variable_name] = ENV[env_variable_name]
-      end
+    def env_overrides
+      {
+        'GIT_DIR' => @git_dir,
+        'GIT_WORK_TREE' => @git_work_dir,
+        'GIT_INDEX_FILE' => @git_index_file,
+        'GIT_SSH' => Git::Base.config.git_ssh
+      }
     end
 
-    # Takes the previously stored git's ENV variables and set them again on ENV.
-    def restore_git_system_env_variables
-      ENV_VARIABLE_NAMES.each do |env_variable_name|
-        ENV[env_variable_name] = @git_system_env_variables[env_variable_name]
+    def global_opts
+      Array.new.tap do |global_opts|
+        global_opts << "--git-dir=#{@git_dir}" if !@git_dir.nil?
+        global_opts << "--work-tree=#{@git_work_dir}" if !@git_work_dir.nil?
+        global_opts << '-c' << 'core.quotePath=true'
+        global_opts << '-c' << 'color.ui=false'
       end
     end
 
-    # Sets git's ENV variables to the custom values for the current instance.
-    def set_custom_git_env_variables
-      ENV['GIT_DIR'] = @git_dir
-      ENV['GIT_WORK_TREE'] = @git_work_dir
-      ENV['GIT_INDEX_FILE'] = @git_index_file
-      ENV['GIT_SSH'] = Git::Base.config.git_ssh
+    def command_line
+      @command_line ||=
+        Git::CommandLine.new(env_overrides, Git::Base.config.binary_path, global_opts, @logger)
     end
 
-    # Runs a block inside an environment with customized ENV variables.
-    # It restores the ENV after execution.
+    # Runs a git command and returns the output
     #
-    # @param [Proc] block block to be executed within the customized environment
-    def with_custom_env_variables(&block)
-      @@semaphore.synchronize do
-        store_git_system_env_variables()
-        set_custom_git_env_variables()
-        return block.call()
-      end
-    ensure
-      restore_git_system_env_variables()
-    end
-
-    def command(*cmd, redirect: '', chomp: true, chdir: nil, &block)
-      Git::Lib.warn_if_old_command(self)
-
-      raise 'cmd can not include a nested array' if cmd.any? { |o| o.is_a? Array }
-
-      global_opts = []
-      global_opts << "--git-dir=#{@git_dir}" if !@git_dir.nil?
-      global_opts << "--work-tree=#{@git_work_dir}" if !@git_work_dir.nil?
-      global_opts << '-c' << 'core.quotePath=true'
-      global_opts << '-c' << 'color.ui=false'
-
-      escaped_cmd = cmd.map { |part| escape(part) }.join(' ')
-
-      global_opts = global_opts.map { |s| escape(s) }.join(' ')
-
-      git_cmd = "#{Git::Base.config.binary_path} #{global_opts} #{escaped_cmd} #{redirect} 2>&1"
-
-      output = nil
-
-      command_thread = nil;
-
-      status = nil
-
-      with_custom_env_variables do
-        command_thread = Thread.new do
-          output, status = run_command(git_cmd, chdir, &block)
-        end
-        command_thread.join
-      end
-
-      @logger.info(git_cmd)
-      @logger.debug(output)
-
-      if status.exitstatus > 1 || (status.exitstatus == 1 && output != '')
-        result = Git::CommandLineResult.new(git_cmd, status, output, '')
-        raise Git::FailedError.new(result)
-      end
-
-      output.chomp! if output && chomp && !block_given?
-
-      output
+    # @param args [Array] the git command to run and its arguments
+    #
+    #   This should exclude the 'git' command itself and global options.
+    #
+    #   For example, to run `git log --pretty=oneline`, you would pass `['log',
+    #   '--pretty=oneline']`
+    #
+    # @param out [String, nil] the path to a file or an IO to write the command's
+    #   stdout to
+    #
+    # @param err [String, nil] the path to a file or an IO to write the command's
+    #   stdout to
+    #
+    # @param normalize [Boolean] true to normalize the output encoding
+    #
+    # @param chomp [Boolean] true to remove trailing newlines from the output
+    #
+    # @param merge [Boolean] true to merge stdout and stderr
+    #
+    # @param chdir [String, nil] the directory to run the command in
+    #
+    # @param timeout [Numeric, nil] the maximum seconds to wait for the command to complete
+    #
+    #   If timeout is nil, the global timeout from {Git::Config} is used.
+    #
+    #   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.
+    #
+    # @see Git::CommandLine#run
+    #
+    # @return [String] the command's stdout (or merged stdout and stderr if `merge`
+    # is true)
+    #
+    # @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
+    #
+    #   The exception's `result` attribute is a {Git::CommandLineResult} which will
+    #   contain the result of the command including the exit status, stdout, and
+    #   stderr.
+    #
+    # @api private
+    #
+    def command(*args, out: nil, err: nil, normalize: true, chomp: true, merge: false, chdir: nil, timeout: nil)
+      timeout = timeout || Git.config.timeout
+      result = command_line.run(*args, out: out, err: err, normalize: normalize, chomp: chomp, merge: merge, chdir: chdir, timeout: timeout)
+      result.stdout
     end
 
     # Takes the diff command line output (as Array) and parse it into a Hash
@@ -1291,38 +1322,5 @@ module Git
       end
       arr_opts
     end
-
-    def run_command(git_cmd, chdir=nil, &block)
-      block ||= Proc.new do |io|
-        io.readlines.map { |l| Git::EncodingUtils.normalize_encoding(l) }.join
-      end
-
-      opts = {}
-      opts[:chdir] = File.expand_path(chdir) if chdir
-
-      Open3.popen2(git_cmd, opts) do |stdin, stdout, wait_thr|
-        [block.call(stdout), wait_thr.value]
-      end
-    end
-
-    def escape(s)
-      windows_platform? ? escape_for_windows(s) : escape_for_sh(s)
-    end
-
-    def escape_for_sh(s)
-      "'#{s && s.to_s.gsub('\'','\'"\'"\'')}'"
-    end
-
-    def escape_for_windows(s)
-      # Escape existing double quotes in s and then wrap the result with double quotes
-      escaped_string = s.to_s.gsub('"','\\"')
-      %Q{"#{escaped_string}"}
-    end
-
-    def windows_platform?
-      # Check if on Windows via RUBY_PLATFORM (CRuby) and RUBY_DESCRIPTION (JRuby)
-      win_platform_regex = /mingw|mswin/
-      RUBY_PLATFORM =~ win_platform_regex || RUBY_DESCRIPTION =~ win_platform_regex
-    end
   end
 end