ruby_git 0.2.0 → 0.3.1

data/lib/ruby_git/command_line/runner.rb

@@ -0,0 +1,296 @@
+# frozen_string_literal: true
+
+require_relative 'result'
+require 'ruby_git/errors'
+
+module RubyGit
+  # Runs a git command and returns the result
+  #
+  # @api public
+  #
+  module CommandLine
+    # Runs the git command line and returns the result
+    # @api public
+    class Runner
+      # Create a an object to run git commands via the command line
+      #
+      # @example
+      #   env = { 'GIT_DIR' => '/path/to/git/dir' }
+      #   binary_path = '/usr/bin/git'
+      #   global_options = %w[--git-dir /path/to/git/dir]
+      #   logger = Logger.new(STDOUT)
+      #   cli = CommandLine.new(env, binary_path, global_options, logger)
+      #   cli.run('version') #=> #<RubyGit::CommandLineResult:0x00007f9b0c0b0e00
+      #
+      # @param env [Hash<String, String>] environment variables to set
+      # @param binary_path [String] the path to the git binary
+      # @param global_options [Array<String>] global options to pass to git
+      # @param logger [Logger] the logger to use
+      #
+      def initialize(env, binary_path, global_options, logger)
+        @env = env
+        @binary_path = binary_path
+        @global_options = global_options
+        @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 = RubyGit::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 = RubyGit::CommandLine.new({}, binary_path, ['version'], Logger.new(STDOUT))
+      #   command_line.binary_path #=> '/usr/bin/git'
+      #
+      # @return [String]
+      #
+      attr_reader :binary_path
+
+      # @attribute [r] global_options
+      #
+      # 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_options = %w[--git-dir /path/to/git/dir]
+      #   logger = Logger.new(nil)
+      #   cli = CommandLine.new(env, '/usr/bin/git', global_options, logger)
+      #   cli.global_options #=> %w[--git-dir /path/to/git/dir]
+      #
+      # @return [Array<String>]
+      #
+      attr_reader :global_options
+
+      # @attribute [r] logger
+      #
+      # The logger to use for logging git commands and results
+      #
+      # @example
+      #   env = {}
+      #   global_options = %w[]
+      #   logger = Logger.new(STDOUT)
+      #   cli = CommandLine.new(env, '/usr/bin/git', global_options, 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 RubyGit::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 RubyGit::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 options_hash [Hash] the options to initialize {RubyGit::CommandLine::Options}
+      #
+      # @return [RubyGit::CommandLine::Result] the result of the command
+      #
+      # @raise [ArgumentError] if `args` or `options_hash` are not valid
+      #
+      # @raise [RubyGit::FailedError] if the command returned a non-zero exitstatus
+      #
+      # @raise [RubyGit::SignaledError] if the command was terminated because of an uncaught signal
+      #
+      # @raise [RubyGit::TimeoutError] if the command timeed out
+      #
+      # @raise [RubyGit::ProcessIOError] if an exception was raised while collecting subprocess output
+      #
+      def call(*args, **options_hash)
+        options_hash[:raise_errors] = false
+        options = RubyGit::CommandLine::Options.new(logger: logger, **options_hash)
+        begin
+          result = run_with_chdir([env, *build_git_cmd(args)], options)
+        rescue ProcessExecuter::ProcessIOError => e
+          raise RubyGit::ProcessIOError.new(e.message), cause: e.exception.cause
+        end
+        process_result(result)
+      end
+
+      private
+
+      # Run command with options with special handling for the `chdir` option on JRuby
+      #
+      # JRuby does not support the `chdir` option in `Process.spawn`. Note that this
+      # workaround means that this library is not thread-safe when using JRuby.
+      #
+      # @param args [Array<String>] the command to run
+      # @param options [RubyGit::CommandLine::Options] the options to pass to `Process.spawn`
+      #
+      # @return [ProcessExecuter::Result] the result of the command
+      #
+      # @api private
+      #
+      def run_with_chdir(args, options)
+        return ProcessExecuter.run_with_options(args, options) unless jruby? && options.chdir != :not_set
+
+        # :nocov: Not executed in MRI Ruby
+        Dir.chdir(options.chdir) do
+          saved_chdir = options.chdir
+          options.merge!(chdir: :not_set)
+          ProcessExecuter.run_with_options(args, options).tap do
+            options.merge!(chdir: saved_chdir)
+          end
+        end
+        # :nocov:
+      end
+
+      # Returns true if running on JRuby
+      #
+      # @return [Boolean]
+      #
+      # @api private
+      def jruby? = RUBY_ENGINE == 'jruby'
+
+      # Build the git command line from the available sources to send to `Process.spawn`
+      # @return [Array<String>]
+      # @api private
+      #
+      def build_git_cmd(args)
+        raise ArgumentError, 'The args array can not contain an array' if args.any? { |a| a.is_a?(Array) }
+
+        [binary_path, *global_options, *args].map(&:to_s)
+      end
+
+      # Process the result of the command and return a RubyGit::CommandLineResult
+      #
+      # Post process output, log the command and result, and raise an error if the
+      # command failed.
+      #
+      # @param result [ProcessExecuter::Result] the result it is a Process::Status
+      #   and include command, stdout, and stderr
+      #
+      # @return [RubyGit::CommandLineResult] the result of the command to return to the caller
+      #
+      # @raise [RubyGit::FailedError] if the command failed
+      # @raise [RubyGit::SignaledError] if the command was signaled
+      # @raise [RubyGit::TimeoutError] if the command times out
+      # @raise [RubyGit::ProcessIOError] if an exception was raised while collecting subprocess output
+      #
+      # @api private
+      #
+      def process_result(result)
+        RubyGit::CommandLine::Result.new(result).tap do |processed_result|
+          raise_any_errors(processed_result) if processed_result.options.raise_git_errors
+
+          processed_result.process_stdout { |s, r| process_output(s, r) }
+          processed_result.process_stderr { |s, r| process_output(s, r) }
+        end
+      end
+
+      # Raise an error if the command failed, was signaled, or timed out
+      #
+      # @param result [RubyGit::CommandLineResult] the result of the command
+      #
+      # @return [Void]
+      #
+      # @raise [RubyGit::FailedError] if the command failed
+      # @raise [RubyGit::SignaledError] if the command was signaled
+      # @raise [RubyGit::TimeoutError] if the command times out
+      #
+      # @api private
+      #
+      def raise_any_errors(result)
+        raise RubyGit::TimeoutError, result if result.timed_out?
+
+        raise RubyGit::SignaledError, result if result.signaled?
+
+        raise RubyGit::FailedError, result unless result.success?
+      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 output [#string] the output to post-process
+      # @return [String, nil]
+      #
+      # @api private
+      #
+      def process_output(output, result)
+        return nil unless output
+
+        output =
+          if result.options.normalize_encoding
+            output.lines.map { |l| RubyGit::EncodingNormalizer.normalize(l) }.join
+          else
+            output.dup
+          end
+
+        output.tap { |o| o.chomp! if result.options.chomp }
+      end
+    end
+  end
+end

data/lib/ruby_git/command_line.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require_relative 'command_line/options'
+require_relative 'command_line/result'
+require_relative 'command_line/runner'
+
+module RubyGit
+  # Run git commands via the command line
+  #
+  # @api public
+  #
+  module CommandLine
+    # Run a git command
+    #
+    # @example A simple example
+    #   RubyGit::CommandLine.run('version') #=> outputs "git version 2.30.2\n" to stdout
+    #
+    # @example Capture stdout
+    #   command = %w[version]
+    #   options = { out: StringIO.new }
+    #   result = RubyGit::CommandLine.run(*command, **options) #=> #<Process::Status: pid 21742 exit 0>
+    #   result.stdout #=> "git version 2.30.2\n"
+    #
+    # @example A more complex example
+    #   command = %w[rev-parse --show-toplevel]
+    #   options = { chdir: worktree_path, chomp: true, out: StringIO.new, err: StringIO.new }
+    #   RubyGit::CommandLine.run(*command, **options).stdout #=> "/path/to/working/tree"
+    #
+    # @param args [Array<String>] the git command and it arguments
+    # @param repository_path [String] the path to the git repository
+    # @param worktree_path [String] the path to the working tree
+    # @param options [Hash<Symbol, Object>] options to pass to the command line runner
+    #
+    # @return [RubyGit::CommandLine::Result] the result of running the command
+    #
+    # @raise [RubyGit::Error] if the command fails for any of the following reasons
+    # @raise [RubyGit::FailedError] if the command returns with non-zero exitstatus
+    # @raise [RubyGit::TimeoutError] if the command times out
+    # @raise [RubyGit::SignaledError] if the command terminates due to an uncaught signal
+    # @raise [RubyGit::ProcessIOError] if an exception is raised while collecting subprocess output
+    #
+    def self.run(*args, repository_path: nil, worktree_path: nil, **options)
+      runner = RubyGit::CommandLine::Runner.new(
+        env,
+        binary_path,
+        global_options(repository_path:, worktree_path:),
+        logger
+      )
+      runner.call(*args, **options)
+    end
+
+    # The environment variables that will be set for all git commands
+    # @return [Hash<String, String>]
+    # @api private
+    def self.env
+      {
+        'GIT_DIR' => nil,
+        'GIT_WORK_TREE' => nil,
+        'GIT_INDEX_FILE' => nil,
+        # 'GIT_SSH' => Git::Base.config.git_ssh,
+        'LC_ALL' => 'en_US.UTF-8'
+      }
+    end
+
+    # The path to the git binary
+    # @return [String]
+    # @api private
+    def self.binary_path = RubyGit.binary_path
+
+    # The global options that will be set for all git commands
+    # @return [Array<String>]
+    # @api private
+    def self.global_options(repository_path:, worktree_path:) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      [].tap do |global_opts|
+        global_opts << "--git-dir=#{repository_path}" unless repository_path.nil?
+        global_opts << "--work-tree=#{worktree_path}" unless worktree_path.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
+
+    # The logger to use for logging git commands
+    # @return [Logger]
+    # @api private
+    def self.logger = RubyGit.logger
+  end
+end

data/lib/ruby_git/encoding_normalizer.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'rchardet'
+
+module RubyGit
+  # Utility to normalize string encoding
+  # @api public
+  module EncodingNormalizer
+    # Detects the character encoding used to create a string or binary data
+    #
+    # Detects the encoding of a string or return binary if it cannot be detected
+    #
+    # @example
+    #   RubyGit::EncodingNormalizer.detect_encoding("Hello, world!") #=> "ascii"
+    #   RubyGit::EncodingNormalizer.detect_encoding("\xCB\xEF\xF1\xE5\xEC") #=> "ISO-8859-7"
+    #   RubyGit::EncodingNormalizer.detect_encoding("\xC0\xCC\xB0\xCD\xC0\xBA") #=> "EUC-KR"
+    #
+    # @param str [String] the string to detect the encoding of
+    # @return [String] the detected encoding
+    #
+    def self.detect_encoding(str)
+      CharDet.detect(str)&.dig('encoding') || Encoding::BINARY.name
+    end
+
+    # Normalizes the encoding to normalize_to
+    #
+    # @example
+    #   RubyGit::EncodingNormalizer.normalize("Hello, world!") #=> "Hello, world!"
+    #   RubyGit::EncodingNormalizer.normalize("\xCB\xEF\xF1\xE5\xEC") #=> "Λορεμ"
+    #   RubyGit::EncodingNormalizer.normalize("\xC0\xCC\xB0\xCD\xC0\xBA") #=> "이것은"
+    #
+    # @param str [String] the string to normalize
+    # @param normalize_to [String] the name of the encoding to normalize to
+    #
+    # @return [String] the string with encoding converted to normalize_to
+    #
+    # @raise [Encoding::UndefinedConversionError] if the string cannot be converted to the default encoding
+    #
+    def self.normalize(str, normalize_to: Encoding::UTF_8.name)
+      encoding_options = { invalid: :replace, undef: :replace }
+
+      detected_encoding = detect_encoding(str)
+
+      return str if str.valid_encoding? && detected_encoding == normalize_to
+
+      str.encode(normalize_to, detected_encoding, **encoding_options)
+    end
+  end
+end

data/lib/ruby_git/errors.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module RubyGit
+  # rubocop:disable Layout/LineLength
+
+  # Base class for all custom git module errors
+  #
+  # The git gem will only raise an `ArgumentError` or an error that is a subclass of
+  # `RubyGit::Error`. It does not explicitly raise any other types of errors.
+  #
+  # It is recommended to rescue `RubyGit::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
+  # └─> RubyGit::Error
+  #     ├─> RubyGit::CommandLineError
+  #     │   ├─> RubyGit::FailedError
+  #     │   └─> RubyGit::SignaledError
+  #     │       └─> RubyGit::TimeoutError
+  #     ├─> RubyGit::ProcessIOError
+  #     └─> RubyGit::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 RubyGit::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 RubyGit::TimeoutError => e # Catch the more specific error first!
+  #     puts "Git clone took too long and timed out #{e}"
+  #   rescue RubyGit::Error => e
+  #     puts "Received the following error: #{e}"
+  #   end
+  #
+  # @see RubyGit::CommandLineError
+  # @see RubyGit::FailedError
+  # @see RubyGit::SignaledError
+  # @see RubyGit::TimeoutError
+  # @see RubyGit::ProcessIOError
+  # @see RubyGit::UnexpectedResultError
+  #
+  # @api public
+  #
+  class Error < StandardError; end
+
+  # rubocop:enable Layout/LineLength
+
+  # 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:
+  #
+  # * {RubyGit::FailedError}: when the git command exits with a non-zero status
+  # * {RubyGit::SignaledError}: when the git command exits because of an uncaught signal
+  # * {RubyGit::TimeoutError}: when the git command times out
+  #
+  # @api public
+  #
+  class CommandLineError < RubyGit::Error
+    # Create a CommandLineError object
+    #
+    # @example
+    #   `exit 1` # set $? appropriately for this example
+    #   result = RubyGit::CommandLineResult.new(%w[git status], $?, 'stdout', 'stderr')
+    #   error = RubyGit::CommandLineError.new(result)
+    #   error.to_s #=> '["git", "status"], status: pid 89784 exit 1, stderr: "stderr"'
+    #
+    # @param result [RubyGit::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.command}, status: #{result}, stderr: #{result.stderr.inspect}
+    MESSAGE
+
+    # @attribute [r] result
+    #
+    # The the git command result with the command and its status and output
+    #
+    # @example
+    #   error.result #=> #<RubyGit::CommandLineResult:0x00000001046bd488 ...>
+    #
+    # @return [RubyGit::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 < RubyGit::CommandLineError; end
+
+  # This error is raised when a git command exits because of an uncaught signal
+  #
+  # @api public
+  #
+  class SignaledError < RubyGit::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 < RubyGit::SignaledError
+    # 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 #{result.options.timeout_after}s
+    MESSAGE
+  end
+
+  # Raised when the output of a git command can not be read
+  #
+  # @api public
+  #
+  class ProcessIOError < RubyGit::Error; end
+
+  # Raised when the git command result was not as expected
+  #
+  # @api public
+  #
+  class UnexpectedResultError < RubyGit::Error; end
+end

data/lib/ruby_git/repository.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module RubyGit
+  # The repository is the database of all the objects, refs, and other data that
+  # make up the history of a project.
+  #
+  # @api public
+  #
+  class Repository
+    # @attribute [r] path
+    #
+    # The absolute path to the repository
+    #
+    # @example
+    #  repository = RubyGit::Repository.new('.git')
+    #  repository.path = '/absolute/path/.git'
+    #
+    # @return [String]
+    #
+    attr_reader :path
+
+    # Create a new Repository object with the given repository path
+    #
+    # @example
+    #   RubyGit::Repository.new('/path/to/repository') #=> #<RubyGit::Repository ...>
+    #
+    # @param [String] repository_path the path to the repository
+    #
+    def initialize(repository_path)
+      @path = File.realpath(repository_path)
+    end
+  end
+end