git 1.19.1 → 2.1.1

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.
@@ -37,14 +38,23 @@ module Git
 
     # Create a new Git::Lib object
     #
-    # @param [Git::Base, Hash] base An object that passes in values for
-    #   @git_work_dir, @git_dir, and @git_index_file
+    # @overload initialize(base, logger)
+    #
+    #   @param base [Hash] the hash containing paths to the Git working copy,
+    #     the Git repository directory, and the Git index file.
+    #
+    #   @option base [Pathname] :working_directory
+    #   @option base [Pathname] :repository
+    #   @option base [Pathname] :index
     #
-    # @param [Logger] logger
+    #   @param [Logger] logger
     #
-    # @option base [Pathname] :working_directory
-    # @option base [Pathname] :repository
-    # @option base [Pathname] :index
+    # @overload initialize(base, logger)
+    #
+    #   @param base [#dir, #repo, #index] an object with methods to get the Git worktree (#dir),
+    #     the Git repository directory (#repo), and the Git index file (#index).
+    #
+    #   @param [Logger] logger
     #
     def initialize(base = nil, logger = nil)
       @git_dir = nil
@@ -79,22 +89,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
     #
-    # TODO - make this work with SSH password or auth_key
+    #   If nil, the repository is cloned into a directory with the same name as
+    #   the repository.
+    #
+    # @param [Hash] opts the options for this command
+    #
+    # @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 +136,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 +164,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 +359,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 +429,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 +508,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
@@ -536,18 +574,52 @@ module Git
       diff_as_hash('diff-index', treeish)
     end
 
+    # List all files that are in the index
+    #
+    # @param location [String] the location to list the files from
+    #
+    # @return [Hash<String, Hash>] a hash of files in the index
+    #   * key: file [String] the file path
+    #   * value: file_info [Hash] the file information containing the following keys:
+    #     * :path [String] the file path
+    #     * :mode_index [String] the file mode
+    #     * :sha_index [String] the file sha
+    #     * :stage [String] the file stage
+    #
     def ls_files(location=nil)
       location ||= '.'
-      hsh = {}
-      command_lines('ls-files', '--stage', location).each do |line|
-        (info, file) = line.split("\t")
-        (mode, sha, stage) = info.split
-        if file.start_with?('"') && file.end_with?('"')
-          file = Git::EscapedPath.new(file[1..-2]).unescape
+      {}.tap do |files|
+        command_lines('ls-files', '--stage', location).each do |line|
+          (info, file) = line.split("\t")
+          (mode, sha, stage) = info.split
+          files[unescape_quoted_path(file)] = {
+            :path => file, :mode_index => mode, :sha_index => sha, :stage => stage
+          }
         end
-        hsh[file] = {:path => file, :mode_index => mode, :sha_index => sha, :stage => stage}
       end
-      hsh
+    end
+
+    # Unescape a path if it is quoted
+    #
+    # Git commands that output paths (e.g. ls-files, diff), will escape unusual
+    # characters.
+    #
+    # @example
+    #   lib.unescape_if_quoted('"quoted_file_\\342\\230\\240"') # => 'quoted_file_☠'
+    #   lib.unescape_if_quoted('unquoted_file')   # => 'unquoted_file'
+    #
+    # @param path [String] the path to unescape if quoted
+    #
+    # @return [String] the unescaped path if quoted otherwise the original path
+    #
+    # @api private
+    #
+    def unescape_quoted_path(path)
+      if path.start_with?('"') && path.end_with?('"')
+        Git::EscapedPath.new(path[1..-2]).unescape
+      else
+        path
+      end
     end
 
     def ls_remote(location=nil, opts={})
@@ -568,9 +640,12 @@ module Git
     end
 
     def ignored_files
-      command_lines('ls-files', '--others', '-i', '--exclude-standard')
+      command_lines('ls-files', '--others', '-i', '--exclude-standard').map { |f| unescape_quoted_path(f) }
     end
 
+    def untracked_files
+      command_lines('ls-files', '--others', '--exclude-standard', chdir: @git_work_dir)
+    end
 
     def config_remote(name)
       hsh = {}
@@ -638,18 +713,20 @@ module Git
       command('config', '--global', name, value)
     end
 
-    # updates the repository index using the working directory content
-    #
-    #    lib.add('path/to/file')
-    #    lib.add(['path/to/file1','path/to/file2'])
-    #    lib.add(:all => true)
+
+    # Update the index from the current worktree to prepare the for the next commit
     #
-    # options:
-    #   :all => true
-    #   :force => true
+    # @example
+    #   lib.add('path/to/file')
+    #   lib.add(['path/to/file1','path/to/file2'])
+    #   lib.add(:all => true)
     #
-    # @param [String,Array] paths files paths to be added to the repository
+    # @param [String, Array<String>] paths files to be added to the repository (relative to the worktree root)
     # @param [Hash] options
+    #
+    # @option options [Boolean] :all Add, modify, and remove index entries to match the worktree
+    # @option options [Boolean] :force Allow adding otherwise ignored files
+    #
     def add(paths='.',options={})
       arr_opts = []
 
@@ -675,6 +752,19 @@ module Git
       command('rm', *arr_opts)
     end
 
+    # Returns true if the repository is empty (meaning it has no commits)
+    #
+    # @return [Boolean]
+    #
+    def empty?
+      command('rev-parse', '--verify', 'HEAD')
+      false
+    rescue Git::FailedError => e
+      raise unless e.result.status.exitstatus == 128 &&
+        e.result.stderr == 'fatal: Needed a single revision'
+      true
+    end
+
     # Takes the commit message with the options and executes the commit command
     #
     # accepts options:
@@ -865,16 +955,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 +1006,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 +1039,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 +1079,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 +1093,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 +1124,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 +1175,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 +1214,7 @@ module Git
     end
 
     def required_command_version
-      [1, 6]
+      [2, 28]
     end
 
     def meets_required_version?
@@ -1133,11 +1232,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 +1242,90 @@ 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'
+        global_opts << '-c' << 'color.advice=false'
+        global_opts << '-c' << 'color.diff=false'
+        global_opts << '-c' << 'color.grep=false'
+        global_opts << '-c' << 'color.push=false'
+        global_opts << '-c' << 'color.remote=false'
+        global_opts << '-c' << 'color.showBranch=false'
+        global_opts << '-c' << 'color.status=false'
+        global_opts << '-c' << 'color.transport=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 +1391,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