git 1.19.1 → 2.0.0

data/RELEASING.md

@@ -7,64 +7,79 @@
 
 Releasing a new version of the `git` gem requires these steps:
 
-- [How to release a new git.gem](#how-to-release-a-new-gitgem)
-  - [Install Prerequisites](#install-prerequisites)
-  - [Prepare the Release](#prepare-the-release)
-  - [Review and Merge the Release](#review-and-merge-the-release)
-  - [Build and Release the Gem](#build-and-release-the-gem)
-
-These instructions use an example where:
-
-- The default branch is `master`
-- The current release version is `1.5.0`
-- You want to create a new *minor* release, `1.6.0`
+* [Install Prerequisites](#install-prerequisites)
+* [Determine the SemVer release type](#determine-the-semver-release-type)
+* [Create the release](#create-the-release)
+* [Review the CHANGELOG and release PR](#review-the-changelog-and-release-pr)
+* [Manually merge the release PR](#manually-merge-the-release-pr)
+* [Publish the git gem to RubyGems.org](#publish-the-git-gem-to-rubygemsorg)
 
 ## Install Prerequisites
 
 The following tools need to be installed in order to create the release:
 
-- [git](https://git-scm.com) is used to interact with the local and remote repositories
-- [gh](https://cli.github.com) is used to create the release and PR in GitHub
-- [Docker](https://www.docker.com) is used to run the script to create the release notes
+* [create_githhub_release](https://github.com/main-branch/create_github_release) is used to create the release
+* [git](https://git-scm.com) is used by `create-github-release` to interact with the local and remote repositories
+* [gh](https://cli.github.com) is used by `create-github-release` to create the release and PR in GitHub
 
-On a Mac, these tools can be installed using [brew](https://brew.sh):
+On a Mac, these tools can be installed using [gem](https://guides.rubygems.org/rubygems-basics/) and [brew](https://brew.sh):
 
 ```shell
+$ gem install create_github_release
+...
 $ brew install git
 ...
 $ brew install gh
 ...
-$ brew install --cask docker
-...
 $
 ```
 
-## Prepare the Release
+## Determine the SemVer release type
 
-Bump the version, create release notes, tag the release and create a GitHub release and PR which can be used to review the release.
+Determine the SemVer version increment that should be applied for the new release:
 
-Steps:
+* `major`: when the release includes incompatible API or functional changes.
+* `minor`: when the release adds functionality in a backward-compatible manner
+* `patch`: when the release includes small user-facing changes that are
+  backward-compatible and do not introduce new functionality.
 
-- Check out the code with `git clone https://github.com/ruby-git/ruby-git ruby-git-v1.6.0 && cd ruby-git-v1.6.0`
-- Install development dependencies using bundle `bundle install`
-- Based upon the nature of the changes, decide on the type of release: `major`, `minor`, or `patch` (in this example we will use `minor`)
-- Run the release script `bundle exec create-github-release minor`
+## Create the release
 
-## Review and Merge the Release
+Create the release using the `create-github-release` command. If the release type
+is `major`, the command is:
 
-Have the release PR approved and merge the changes into the `master` branch.
+```shell
+create-github-release major
+```
 
-**IMPORTANT** DO NOT merge to the `master` branch using the GitHub UI. Instead use the instructions below.
+Follow the directions given by the `create-github-release` command to finish the
+release. Where the instructions given by the command differ than the instructions
+below, follow the instructions given by the command.
 
-Steps:
+## Review the CHANGELOG and release PR
 
-- Get the release PR reviewed and approved in GitHub
-- Merge the changes with the command `git checkout master && git merge --ff-only v1.6.0 && git push`
+The `create-github-release` command will output a link to the CHANGELOG and the PR
+it created for the release. Review the CHANGELOG and have someone review and approve
+the release PR.
 
-## Build and Release the Gem
+## Manually merge the release PR
 
-Build the gem and publish it to [rubygems.org](https://rubygems.org/gems/git)
+It is important to manually merge the PR so a separate merge commit can be avoided.
+Use the commands output by the `create-github-release` which will looks like this
+if you are creating a 2.0.0 release:
 
-Steps:
+```shell
+git checkout master
+git merge --ff-only release-v2.0.0
+git push
+```
+
+This will automatically close the release PR.
+
+## Publish the git gem to RubyGems.org
 
-- Build and release the gem using rake `bundle exec rake release`
+Finally, publish the git gem to RubyGems.org using the following command:
+
+```shell
+rake release:rubygem_push
+```

data/git.gemspec

@@ -24,22 +24,22 @@ Gem::Specification.new do |s|
   s.metadata['documentation_uri'] = "https://rubydoc.info/gems/#{s.name}/#{s.version}"
 
   s.require_paths = ['lib']
-  s.required_ruby_version = '>= 2.3'
-  s.required_rubygems_version = Gem::Requirement.new('>= 0') if s.respond_to?(:required_rubygems_version=)
-  s.requirements = ['git 1.6.0.0, or greater']
+  s.required_ruby_version = '>= 3.0.0'
+  s.requirements = ['git 2.28.0 or greater']
 
+  s.add_runtime_dependency 'activesupport', '>= 5.0'
   s.add_runtime_dependency 'addressable', '~> 2.8'
+  s.add_runtime_dependency 'process_executer', '~> 1.1'
   s.add_runtime_dependency 'rchardet', '~> 1.8'
 
-  s.add_development_dependency 'bump', '~> 0.10'
-  s.add_development_dependency 'create_github_release', '~> 0.2'
+  s.add_development_dependency 'create_github_release', '~> 1.4'
   s.add_development_dependency 'minitar', '~> 0.9'
   s.add_development_dependency 'mocha', '~> 2.1'
-  s.add_development_dependency 'rake', '~> 13.0'
-  s.add_development_dependency 'test-unit', '~> 3.3'
+  s.add_development_dependency 'rake', '~> 13.1'
+  s.add_development_dependency 'test-unit', '~> 3.6'
 
   unless RUBY_PLATFORM == 'java'
-    s.add_development_dependency 'redcarpet', '~> 3.5'
+    s.add_development_dependency 'redcarpet', '~> 3.6'
     s.add_development_dependency 'yard', '~> 0.9', '>= 0.9.28'
     s.add_development_dependency 'yardstick', '~> 0.9'
   end

data/lib/git/base.rb

@@ -409,14 +409,27 @@ module Git
       self.lib.conflicts(&block)
     end
 
-    # pulls the given branch from the given remote into the current branch
-    #
-    #  @git.pull                          # pulls from origin/master
-    #  @git.pull('upstream')              # pulls from upstream/master
-    #  @git.pull('upstream', 'develope')  # pulls from upstream/develop
-    #
-    def pull(remote = nil, branch = nil)
-      self.lib.pull(remote, branch)
+    # Pulls the given branch from the given remote into the current branch
+    #
+    # @param remote [String] the remote repository to pull from
+    # @param branch [String] the branch to pull from
+    # @param opts [Hash] options to pass to the pull command
+    #
+    # @option opts [Boolean] :allow_unrelated_histories (false) Merges histories of two projects that started their
+    #   lives independently
+    # @example pulls from origin/master
+    #   @git.pull
+    # @example pulls from upstream/master
+    #   @git.pull('upstream')
+    # @example pulls from upstream/develop
+    #   @git.pull('upstream', 'develop')
+    #
+    # @return [Void]
+    #
+    # @raise [Git::FailedError] if the pull fails
+    # @raise [ArgumentError] if a branch is given without a remote
+    def pull(remote = nil, branch = nil, opts = {})
+      self.lib.pull(remote, branch, opts)
     end
 
     # returns an array of Git:Remote objects

data/lib/git/command_line.rb

@@ -0,0 +1,377 @@
+# 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
+    #
+    # 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 args [Array<String>] the command line arguements to pass to git
+    #
+    #   This array should be splatted into the parameter list.
+    #
+    # @param out [#write, nil] 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.
+    #
+    # @param err [#write] 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.
+    #
+    # @param normalize [Boolean] whether to normalize the output to a valid encoding
+    #
+    # @param chomp [Boolean] whether to chomp the output
+    #
+    # @param merge [Boolean] whether to merge stdout and stderr in the string returned
+    #
+    # @param chdir [String] the directory to run the command in
+    #
+    # @param timeout [Numeric, nil] 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(*args, out:, err:, normalize:, chomp:, merge:, chdir: nil, timeout: nil)
+      git_cmd = build_git_cmd(args)
+      out ||= StringIO.new
+      err ||= (merge ? out : StringIO.new)
+      status = execute(git_cmd, out, err, chdir: (chdir || :not_set), timeout: timeout)
+
+      process_result(git_cmd, status, out, err, normalize, chomp, timeout)
+    end
+
+    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.new('The args array can not contain an array') if args.any? { |a| a.is_a?(Array) }
+
+      [binary_path, *global_opts, *args].map { |e| e.to_s }
+    end
+
+    # Determine the output to return in the `CommandLineResult`
+    #
+    # If the writer can return the output by calling `#string` (such as a StringIO),
+    # then return the result of normalizing the encoding and chomping the output
+    # as requested.
+    #
+    # If the writer does not support `#string`, then return nil. The output is
+    # assumed to be collected by the writer itself such as when the  writer
+    # is a file instead of a StringIO.
+    #
+    # @param writer [#string] the writer to post-process
+    #
+    # @return [String, nil]
+    #
+    # @api private
+    #
+    def post_process(writer, normalize, chomp)
+      if writer.respond_to?(:string)
+        output = writer.string.dup
+        output = output.lines.map { |l| Git::EncodingUtils.normalize_encoding(l) }.join if normalize
+        output.chomp! if chomp
+        output
+      else
+        nil
+      end
+    end
+
+    # Post-process all writers and return an array of the results
+    #
+    # @param writers [Array<#write>] the writers 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, nil>] the output of each writer that supports `#string`
+    #
+    # @api private
+    #
+    def post_process_all(writers, normalize, chomp)
+      Array.new.tap do |result|
+        writers.each { |writer| result << post_process(writer, normalize, chomp) }
+      end
+    end
+
+    # Raise an error when there was exception while collecting the subprocess output
+    #
+    # @param git_cmd [Array<String>] the git command that was executed
+    # @param pipe_name [Symbol] the name of the pipe that raised the exception
+    # @param pipe [ProcessExecuter::MonitoredPipe] the pipe that raised the exception
+    #
+    # @raise [Git::ProcessIOError]
+    #
+    # @return [void] this method always raises an error
+    #
+    # @api private
+    #
+    def raise_pipe_error(git_cmd, pipe_name, pipe)
+      raise Git::ProcessIOError.new("Pipe Exception for #{git_cmd}: #{pipe_name}"), cause: pipe.exception
+    end
+
+    # Execute the git command and collect the output
+    #
+    # @param cmd [Array<String>] the git command to execute
+    # @param chdir [String] the directory to run the command in
+    # @param timeout [Numeric, nil] the maximum seconds to wait for the command to complete
+    #
+    #   If timeout is zero of nil, the command will not time out. 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.
+    #
+    # @raise [Git::ProcessIOError] if an exception was raised while collecting subprocess output
+    # @raise [Git::TimeoutError] if the command times out
+    #
+    # @return [ProcessExecuter::Status] the status of the completed subprocess
+    #
+    # @api private
+    #
+    def spawn(cmd, out_writers, err_writers, chdir:, timeout:)
+      out_pipe = ProcessExecuter::MonitoredPipe.new(*out_writers, chunk_size: 10_000)
+      err_pipe = ProcessExecuter::MonitoredPipe.new(*err_writers, chunk_size: 10_000)
+      ProcessExecuter.spawn(env, *cmd, out: out_pipe, err: err_pipe, chdir: chdir, timeout: timeout)
+    ensure
+      out_pipe.close
+      err_pipe.close
+      raise_pipe_error(cmd, :stdout, out_pipe) if out_pipe.exception
+      raise_pipe_error(cmd, :stderr, err_pipe) if err_pipe.exception
+    end
+
+    # The writers that will be used to collect stdout and stderr
+    #
+    # Additional writers could be added here if you wanted to tee output
+    # or send output to the terminal.
+    #
+    # @param out [#write] the object to write stdout to
+    # @param err [#write] the object to write stderr to
+    #
+    # @return [Array<Array<#write>, Array<#write>>] the writers for stdout and stderr
+    #
+    # @api private
+    #
+    def writers(out, err)
+      out_writers = [out]
+      err_writers = [err]
+      [out_writers, err_writers]
+    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 git_cmd [Array<String>] the git command that was executed
+    # @param status [Process::Status] the status of the completed subprocess
+    # @param out [#write] the object that stdout was written to
+    # @param err [#write] the object that stderr was written to
+    # @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(git_cmd, status, out, err, normalize, chomp, timeout)
+      out_str, err_str = post_process_all([out, err], normalize, chomp)
+      logger.info { "#{git_cmd} exited with status #{status}" }
+      logger.debug { "stdout:\n#{out_str.inspect}\nstderr:\n#{err_str.inspect}" }
+      Git::CommandLineResult.new(git_cmd, status, out_str, err_str).tap do |result|
+        raise Git::TimeoutError.new(result, timeout) if status.timeout?
+        raise Git::SignaledError.new(result) if status.signaled?
+        raise Git::FailedError.new(result) unless status.success?
+      end
+    end
+
+    # Execute the git command and write the command output to out and err
+    #
+    # @param git_cmd [Array<String>] the git command to execute
+    # @param out [#write] the object to write stdout to
+    # @param err [#write] the object to write stderr to
+    # @param chdir [String] the directory to run the command in
+    # @param timeout [Numeric, nil] the maximum seconds to wait for the command to complete
+    #
+    #   If timeout is zero of nil, the command will not time out. 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.
+    #
+    # @raise [Git::ProcessIOError] if an exception was raised while collecting subprocess output
+    # @raise [Git::TimeoutError] if the command times out
+    #
+    # @return [Git::CommandLineResult] the result of the command to return to the caller
+    #
+    # @api private
+    #
+    def execute(git_cmd, out, err, chdir:, timeout:)
+      out_writers, err_writers = writers(out, err)
+      spawn(git_cmd, out_writers, err_writers, chdir: chdir, timeout: timeout)
+    end
+  end
+end

data/lib/git/config.rb

@@ -2,11 +2,12 @@ module Git
 
   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
@@ -17,6 +18,9 @@ module Git
       @git_ssh || ENV['GIT_SSH']
     end
 
+    def timeout
+      @timeout || (ENV['GIT_TIMEOUT'] && ENV['GIT_TIMEOUT'].to_i)
+    end
   end
 
 end