git 1.19.1 → 3.1.1

data/lib/git/lib.rb

@@ -1,14 +1,17 @@
-require 'git/failed_error'
+# frozen_string_literal: true
+
+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 +40,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.
     #
-    # @param [Logger] logger
+    #   @option base [Pathname] :working_directory
+    #   @option base [Pathname] :repository
+    #   @option base [Pathname] :index
     #
-    # @option base [Pathname] :working_directory
-    # @option base [Pathname] :repository
-    # @option base [Pathname] :index
+    #   @param [Logger] logger
+    #
+    # @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 +91,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
@@ -102,7 +126,7 @@ module Git
       arr_opts = []
       arr_opts << '--bare' if opts[:bare]
       arr_opts << '--branch' << opts[:branch] if opts[:branch]
-      arr_opts << '--depth' << opts[:depth].to_i if opts[:depth] && opts[:depth].to_i > 0
+      arr_opts << '--depth' << opts[:depth].to_i if opts[:depth]
       arr_opts << '--filter' << opts[:filter] if opts[:filter]
       Array(opts[:config]).each { |c| arr_opts << '--config' << c }
       arr_opts << '--origin' << opts[:remote] || opts[:origin] if opts[:remote] || opts[:origin]
@@ -114,7 +138,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,32 +166,38 @@ 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 ##
 
+    # Finds most recent tag that is reachable from a commit
     #
-    # Returns most recent tag that is reachable from a commit
+    # @see https://git-scm.com/docs/git-describe git-describe
     #
-    # accepts options:
-    #  :all
-    #  :tags
-    #  :contains
-    #  :debug
-    #  :exact_match
-    #  :dirty
-    #  :abbrev
-    #  :candidates
-    #  :long
-    #  :always
-    #  :math
-    #
-    #  @param [String|NilClass] committish target commit sha or object name
-    #  @param [{Symbol=>Object}] opts the given options
-    #  @return [String] the tag name
-    #
-    def describe(committish=nil, opts={})
+    # @param commit_ish [String, nil] target commit sha or object name
+    #
+    # @param opts [Hash] the given options
+    #
+    # @option opts :all [Boolean]
+    # @option opts :tags [Boolean]
+    # @option opts :contains [Boolean]
+    # @option opts :debug [Boolean]
+    # @option opts :long [Boolean]
+    # @option opts :always [Boolean]
+    # @option opts :exact_match [Boolean]
+    # @option opts :dirty [true, String]
+    # @option opts :abbrev [String]
+    # @option opts :candidates [String]
+    # @option opts :match [String]
+    #
+    # @return [String] the tag name
+    #
+    # @raise [ArgumentError] if the commit_ish is a string starting with a hyphen
+    #
+    def describe(commit_ish = nil, opts = {})
+      assert_args_are_not_options('commit-ish object', commit_ish)
+
       arr_opts = []
 
       arr_opts << '--all' if opts[:all]
@@ -185,12 +215,42 @@ module Git
       arr_opts << "--candidates=#{opts[:candidates]}" if opts[:candidates]
       arr_opts << "--match=#{opts[:match]}" if opts[:match]
 
-      arr_opts << committish if committish
+      arr_opts << commit_ish if commit_ish
 
       return command('describe', *arr_opts)
     end
 
-    def log_commits(opts={})
+    # Return the commits that are within the given revision range
+    #
+    # @see https://git-scm.com/docs/git-log git-log
+    #
+    # @param opts [Hash] the given options
+    #
+    # @option opts :count [Integer] the maximum number of commits to return (maps to max-count)
+    # @option opts :all [Boolean]
+    # @option opts :cherry [Boolean]
+    # @option opts :since [String]
+    # @option opts :until [String]
+    # @option opts :grep [String]
+    # @option opts :author [String]
+    # @option opts :between [Array<String>] an array of two commit-ish strings to specify a revision range
+    #
+    #   Only :between or :object options can be used, not both.
+    #
+    # @option opts :object [String] the revision range for the git log command
+    #
+    #   Only :between or :object options can be used, not both.
+    #
+    # @option opts :path_limiter [Array<String>, String] only include commits that impact files from the specified paths
+    #
+    # @return [Array<String>] the log output
+    #
+    # @raise [ArgumentError] if the resulting revision range is a string starting with a hyphen
+    #
+    def log_commits(opts = {})
+      assert_args_are_not_options('between', opts[:between]&.first)
+      assert_args_are_not_options('object', opts[:object])
+
       arr_opts = log_common_options(opts)
 
       arr_opts << '--pretty=oneline'
@@ -200,11 +260,53 @@ module Git
       command_lines('log', *arr_opts).map { |l| l.split.first }
     end
 
-    def full_log_commits(opts={})
+    # Return the commits that are within the given revision range
+    #
+    # @see https://git-scm.com/docs/git-log git-log
+    #
+    # @param opts [Hash] the given options
+    #
+    # @option opts :count [Integer] the maximum number of commits to return (maps to max-count)
+    # @option opts :all [Boolean]
+    # @option opts :cherry [Boolean]
+    # @option opts :since [String]
+    # @option opts :until [String]
+    # @option opts :grep [String]
+    # @option opts :author [String]
+    # @option opts :between [Array<String>] an array of two commit-ish strings to specify a revision range
+    #
+    #   Only :between or :object options can be used, not both.
+    #
+    # @option opts :object [String] the revision range for the git log command
+    #
+    #   Only :between or :object options can be used, not both.
+    #
+    # @option opts :path_limiter [Array<String>, String] only include commits that impact files from the specified paths
+    # @option opts :skip [Integer]
+    #
+    # @return [Array<Hash>] the log output parsed into an array of hashs for each commit
+    #
+    #   Each hash contains the following keys:
+    #   * 'sha' [String] the commit sha
+    #   * 'author' [String] the author of the commit
+    #   * 'message' [String] the commit message
+    #   * 'parent' [Array<String>] the commit shas of the parent commits
+    #   * 'tree' [String] the tree sha
+    #   * 'author' [String] the author of the commit and timestamp of when the changes were created
+    #   * 'committer' [String] the committer of the commit and timestamp of when the commit was applied
+    #   * 'merges' [Boolean] if truthy, only include merge commits (aka commits with 2 or more parents)
+    #
+    # @raise [ArgumentError] if the revision range (specified with :between or :object) is a string starting with a hyphen
+    #
+    def full_log_commits(opts = {})
+      assert_args_are_not_options('between', opts[:between]&.first)
+      assert_args_are_not_options('object', opts[:object])
+
       arr_opts = log_common_options(opts)
 
       arr_opts << '--pretty=raw'
       arr_opts << "--skip=#{opts[:skip]}" if opts[:skip]
+      arr_opts << '--merges' if opts[:merges]
 
       arr_opts += log_path_options(opts)
 
@@ -213,36 +315,147 @@ module Git
       process_commit_log_data(full_log)
     end
 
-    def revparse(string)
-      return string if string =~ /^[A-Fa-f0-9]{40}$/  # passing in a sha - just no-op it
-      rev = ['head', 'remotes', 'tags'].map do |d|
-        File.join(@git_dir, 'refs', d, string)
-      end.find do |path|
-        File.file?(path)
-      end
-      return File.read(rev).chomp if rev
-      command('rev-parse', string)
+    # Verify and resolve a Git revision to its full SHA
+    #
+    # @see https://git-scm.com/docs/git-rev-parse git-rev-parse
+    # @see https://git-scm.com/docs/git-rev-parse#_specifying_revisions Valid ways to specify revisions
+    # @see https://git-scm.com/docs/git-rev-parse#Documentation/git-rev-parse.txt-emltrefnamegtemegemmasterememheadsmasterememrefsheadsmasterem Ref disambiguation rules
+    #
+    # @example
+    #   lib.rev_parse('HEAD') # => '9b9b31e704c0b85ffdd8d2af2ded85170a5af87d'
+    #   lib.rev_parse('9b9b31e') # => '9b9b31e704c0b85ffdd8d2af2ded85170a5af87d'
+    #
+    # @param revision [String] the revision to resolve
+    #
+    # @return [String] the full commit hash
+    #
+    # @raise [Git::FailedError] if the revision cannot be resolved
+    # @raise [ArgumentError] if the revision is a string starting with a hyphen
+    #
+    def rev_parse(revision)
+      assert_args_are_not_options('rev', revision)
+
+      command('rev-parse', '--revs-only', '--end-of-options', revision, '--')
+    end
+
+    # For backwards compatibility with the old method name
+    alias :revparse :rev_parse
+
+    # Find the first symbolic name for given commit_ish
+    #
+    # @param commit_ish [String] the commit_ish to find the symbolic name of
+    #
+    # @return [String, nil] the first symbolic name or nil if the commit_ish isn't found
+    #
+    # @raise [ArgumentError] if the commit_ish is a string starting with a hyphen
+    #
+    def name_rev(commit_ish)
+      assert_args_are_not_options('commit_ish', commit_ish)
+
+      command('name-rev', commit_ish).split[1]
     end
 
-    def namerev(string)
-      command('name-rev', string).split[1]
+    alias :namerev :name_rev
+
+    # Output the contents or other properties of one or more objects.
+    #
+    # @see https://git-scm.com/docs/git-cat-file git-cat-file
+    #
+    # @example Get the contents of a file without a block
+    #   lib.cat_file_contents('README.md') # => "This is a README file\n"
+    #
+    # @example Get the contents of a file with a block
+    #  lib.cat_file_contents('README.md') { |f| f.read } # => "This is a README file\n"
+    #
+    # @param object [String] the object whose contents to return
+    #
+    # @return [String] the object contents
+    #
+    # @raise [ArgumentError] if object is a string starting with a hyphen
+    #
+    def cat_file_contents(object, &block)
+      assert_args_are_not_options('object', object)
+
+      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", object, out: file, err: file)
+          file.rewind
+          yield file
+        end
+      else
+        # If a block is not given, return the file contents as a string
+        command('cat-file', '-p', object)
+      end
     end
 
-    def object_type(sha)
-      command('cat-file', '-t', sha)
+    alias :object_contents :cat_file_contents
+
+    # Get the type for the given object
+    #
+    # @see https://git-scm.com/docs/git-cat-file git-cat-file
+    #
+    # @param object [String] the object to get the type
+    #
+    # @return [String] the object type
+    #
+    # @raise [ArgumentError] if object is a string starting with a hyphen
+    #
+    def cat_file_type(object)
+      assert_args_are_not_options('object', object)
+
+      command('cat-file', '-t', object)
     end
 
-    def object_size(sha)
-      command('cat-file', '-s', sha).to_i
+    alias :object_type :cat_file_type
+
+    # Get the size for the given object
+    #
+    # @see https://git-scm.com/docs/git-cat-file git-cat-file
+    #
+    # @param object [String] the object to get the type
+    #
+    # @return [String] the object type
+    #
+    # @raise [ArgumentError] if object is a string starting with a hyphen
+    #
+    def cat_file_size(object)
+      assert_args_are_not_options('object', object)
+
+      command('cat-file', '-s', object).to_i
     end
 
-    # returns useful array of raw commit object data
-    def commit_data(sha)
-      sha = sha.to_s
-      cdata = command_lines('cat-file', 'commit', sha)
-      process_commit_data(cdata, sha)
+    alias :object_size :cat_file_size
+
+    # Return a hash of commit data
+    #
+    # @see https://git-scm.com/docs/git-cat-file git-cat-file
+    #
+    # @param object [String] the object to get the type
+    #
+    # @return [Hash] commit data
+    #
+    # The returned commit data has the following keys:
+    #    * tree [String]
+    #    * parent [Array<String>]
+    #    * author [String] the author name, email, and commit timestamp
+    #    * committer [String] the committer name, email, and merge timestamp
+    #    * message [String] the commit message
+    #    * gpgsig [String] the public signing key of the commit (if signed)
+    #
+    # @raise [ArgumentError] if object is a string starting with a hyphen
+    #
+    def cat_file_commit(object)
+      assert_args_are_not_options('object', object)
+
+      cdata = command_lines('cat-file', 'commit', object)
+      process_commit_data(cdata, object)
     end
 
+    alias :commit_data :cat_file_commit
+
     def process_commit_data(data, sha)
       hsh = {
         'sha'    => sha,
@@ -277,12 +490,50 @@ module Git
       end
     end
 
-    def tag_data(name)
-      sha = sha.to_s
-      tdata = command_lines('cat-file', 'tag', name)
-      process_tag_data(tdata, name)
+    # Return a hash of annotated tag data
+    #
+    # Does not work with lightweight tags. List all annotated tags in your repository with the following command:
+    #
+    # ```sh
+    # git for-each-ref --format='%(refname:strip=2)' refs/tags | while read tag; do git cat-file tag $tag >/dev/null 2>&1 && echo $tag; done
+    # ```
+    #
+    # @see https://git-scm.com/docs/git-cat-file git-cat-file
+    #
+    # @param object [String] the tag to retrieve
+    #
+    # @return [Hash] tag data
+    #
+    #   Example tag data returned:
+    #   ```ruby
+    #   {
+    #     "name" => "annotated_tag",
+    #     "object" => "46abbf07e3c564c723c7c039a43ab3a39e5d02dd",
+    #     "type" => "commit",
+    #     "tag" => "annotated_tag",
+    #     "tagger" => "Scott Chacon <schacon@gmail.com> 1724799270 -0700",
+    #     "message" => "Creating an annotated tag\n"
+    #   }
+    #   ```
+    #
+    # The returned commit data has the following keys:
+    #   * object [String] the sha of the tag object
+    #   * type [String]
+    #   * tag [String] tag name
+    #   * tagger [String] the name and email of the user who created the tag and the timestamp of when the tag was created
+    #   * message [String] the tag message
+    #
+    # @raise [ArgumentError] if object is a string starting with a hyphen
+    #
+    def cat_file_tag(object)
+      assert_args_are_not_options('object', object)
+
+      tdata = command_lines('cat-file', 'tag', object)
+      process_tag_data(tdata, object)
     end
 
+    alias :tag_data :cat_file_tag
+
     def process_tag_data(data, name)
       hsh = { 'name' => name }
 
@@ -323,7 +574,7 @@ module Git
         case key
           when 'commit'
             hsh_array << hsh if hsh
-            hsh = {'sha' => value, 'message' => '', 'parent' => []}
+            hsh = {'sha' => value, 'message' => +'', 'parent' => []}
           when 'parent'
             hsh['parent'] << value
           else
@@ -336,14 +587,15 @@ module Git
       return hsh_array
     end
 
-    def object_contents(sha, &block)
-      command('cat-file', '-p', sha, &block)
-    end
-
-    def ls_tree(sha)
+    def ls_tree(sha, opts = {})
       data = { 'blob' => {}, 'tree' => {}, 'commit' => {} }
 
-      command_lines('ls-tree', sha).each do |line|
+      ls_tree_opts = []
+      ls_tree_opts << '-r' if opts[:recursive]
+      # path must be last arg
+      ls_tree_opts << opts[:path] if opts[:path]
+
+      command_lines('ls-tree', sha, *ls_tree_opts).each do |line|
         (info, filenm) = line.split("\t")
         (mode, type, sha) = info.split
         data[type][filenm] = {:mode => mode, :sha => sha}
@@ -393,10 +645,13 @@ module Git
     /x
 
     def branches_all
-      command_lines('branch', '-a').map do |line|
+      lines = command_lines('branch', '-a')
+      lines.each_with_index.map do |line, line_index|
         match_data = line.match(BRANCH_LINE_REGEXP)
-        raise GitExecuteError, 'Unexpected branch line format' unless match_data
+
+        raise Git::UnexpectedResultError, unexpected_branch_line_error(lines, line, line_index) unless match_data
         next nil if match_data[:not_a_branch] || match_data[:detached_ref]
+
         [
           match_data[:refname],
           !match_data[:current].nil?,
@@ -406,6 +661,18 @@ module Git
       end.compact
     end
 
+    def unexpected_branch_line_error(lines, line, index)
+      <<~ERROR
+        Unexpected line in output from `git branch -a`, line #{index + 1}
+
+        Full output:
+          #{lines.join("\n  ")}
+
+        Line #{index + 1}:
+          "#{line}"
+      ERROR
+    end
+
     def worktrees_all
       arr = []
       directory = ''
@@ -449,8 +716,54 @@ module Git
       files
     end
 
+    # The state and name of branch pointed to by `HEAD`
+    #
+    # HEAD can be in the following states:
+    #
+    # **:active**: `HEAD` points to a branch reference which in turn points to a
+    # commit representing the tip of that branch. This is the typical state when
+    # working on a branch.
+    #
+    # **:unborn**: `HEAD` points to a branch reference that does not yet exist
+    # because no commits have been made on that branch. This state occurs in two
+    # scenarios:
+    #
+    # * When a repository is newly initialized, and no commits have been made on the
+    #   initial branch.
+    # * When a new branch is created using `git checkout --orphan <branch>`, starting
+    #   a new branch with no history.
+    #
+    # **:detached**: `HEAD` points directly to a specific commit (identified by its
+    # SHA) rather than a branch reference. This state occurs when you check out a
+    # commit, a tag, or any state that is not directly associated with a branch. The
+    # branch name in this case is `HEAD`.
+    #
+    HeadState = Struct.new(:state, :name)
+
+    # The current branch state which is the state of `HEAD`
+    #
+    # @return [HeadState] the state and name of the current branch
+    #
+    def current_branch_state
+      branch_name = command('branch', '--show-current')
+      return HeadState.new(:detached, 'HEAD') if branch_name.empty?
+
+      state =
+        begin
+          command('rev-parse', '--verify', '--quiet', branch_name)
+          :active
+        rescue Git::FailedError => e
+          raise unless e.result.status.exitstatus == 1 && e.result.stderr.empty?
+
+          :unborn
+        end
+
+      return HeadState.new(state, branch_name)
+    end
+
     def branch_current
-      branches_all.select { |b| b[1] }.first[0] rescue nil
+      branch_name = command('branch', '--show-current')
+      branch_name.empty? ? 'HEAD' : branch_name
     end
 
     def branch_contains(commit, branch_name="")
@@ -474,16 +787,37 @@ 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
 
+    # Validate that the given arguments cannot be mistaken for a command-line option
+    #
+    # @param arg_name [String] the name of the arguments to mention in the error message
+    # @param args [Array<String, nil>] the arguments to validate
+    #
+    # @raise [ArgumentError] if any of the parameters are a string starting with a hyphen
+    # @return [void]
+    #
+    def assert_args_are_not_options(arg_name, *args)
+      invalid_args = args.select { |arg| arg&.start_with?('-') }
+      if invalid_args.any?
+        raise ArgumentError, "Invalid #{arg_name}: '#{invalid_args.join("', '")}'"
+      end
+    end
+
     def diff_full(obj1 = 'HEAD', obj2 = nil, opts = {})
+      assert_args_are_not_options('commit or commit range', obj1, obj2)
+
       diff_opts = ['-p']
       diff_opts << obj1
       diff_opts << obj2 if obj2.is_a?(String)
@@ -493,6 +827,8 @@ module Git
     end
 
     def diff_stats(obj1 = 'HEAD', obj2 = nil, opts = {})
+      assert_args_are_not_options('commit or commit range', obj1, obj2)
+
       diff_opts = ['--numstat']
       diff_opts << obj1
       diff_opts << obj2 if obj2.is_a?(String)
@@ -513,6 +849,8 @@ module Git
     end
 
     def diff_name_status(reference1 = nil, reference2 = nil, opts = {})
+      assert_args_are_not_options('commit or commit range', reference1, reference2)
+
       opts_arr = ['--name-status']
       opts_arr << reference1 if reference1
       opts_arr << reference2 if reference2
@@ -536,18 +874,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 +940,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 +1013,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 +1052,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:
@@ -763,8 +1153,10 @@ module Git
       if File.exist?(filename)
         File.open(filename) do |f|
           f.each_with_index do |line, i|
-            m = line.match(/:(.*)$/)
-            arr << [i, m[1].strip]
+            _, msg = line.split("\t")
+            # NOTE this logic may be removed/changed in 3.x
+            m = msg.match(/^[^:]+:(.*)$/)
+            arr << [i, (m ? m[1] : msg).strip]
           end
         end
       end
@@ -865,16 +1257,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 +1308,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 +1341,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 +1381,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 +1395,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 +1426,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 +1477,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 +1516,7 @@ module Git
     end
 
     def required_command_version
-      [1, 6]
+      [2, 28]
     end
 
     def meets_required_version?
@@ -1133,11 +1534,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 +1544,91 @@ 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,
+        'LC_ALL' => 'en_US.UTF-8'
+      }
     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 +1694,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