git 1.19.1 → 5.5.0

data/lib/git/dirstat_info.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Git
+  # Immutable value object representing a single directory's contribution to a diff
+  #
+  # @example Create a DirstatEntry
+  #   info = Git::DirstatEntry.new(directory: 'lib/commands/', percentage: 45.2)
+  #   info.directory   #=> "lib/commands/"
+  #   info.percentage  #=> 45.2
+  #
+  # @api private
+  #
+  # Work in progress; this class is internal for now and may be made public in a future release.
+  #
+  # @!attribute [r] directory
+  #   @return [String] the directory path (always ends with '/')
+  #
+  # @!attribute [r] percentage
+  #   @return [Float] the percentage of changes in this directory (0.0-100.0)
+  #
+  DirstatEntry = Data.define(:directory, :percentage)
+
+  # Immutable result object from git --dirstat output
+  #
+  # Contains the list of directories and their contribution percentages to the diff.
+  #
+  # @example Create a DirstatInfo
+  #   dirstat = Git::DirstatInfo.new(
+  #     entries: [
+  #       Git::DirstatEntry.new(directory: 'lib/commands/', percentage: 45.2),
+  #       Git::DirstatEntry.new(directory: 'spec/unit/', percentage: 30.1)
+  #     ]
+  #   )
+  #   dirstat.entries.first.directory  #=> "lib/commands/"
+  #   dirstat['lib/commands/']         #=> 45.2
+  #   dirstat.to_h  #=> { "lib/commands/" => 45.2, "spec/unit/" => 30.1 }
+  #
+  # @api private
+  #
+  # Work in progress; this class is internal for now and may be made public in a future release.
+  #
+  # @!attribute [r] entries
+  #   @return [Array<DirstatEntry>] directory statistics in order from git output
+  #
+  DirstatInfo = Data.define(:entries) do
+    # Look up percentage by directory path
+    #
+    # @param directory [String] the directory path
+    #
+    # @return [Float, nil] the percentage or nil if not found
+    #
+    def [](directory)
+      entries.find { |e| e.directory == directory }&.percentage
+    end
+
+    # Convert to a Hash mapping directory to percentage
+    #
+    # @return [Hash<String, Float>]
+    #
+    def to_h
+      entries.to_h { |e| [e.directory, e.percentage] }
+    end
+
+    # Number of directories in the dirstat
+    #
+    # @return [Integer]
+    #
+    def size
+      entries.size
+    end
+
+    # Check if dirstat is empty
+    #
+    # @return [Boolean]
+    #
+    def empty?
+      entries.empty?
+    end
+
+    # Iterate over entries
+    #
+    # @overload each
+    #
+    #   @return [Enumerator<Git::DirstatEntry>] an enumerator over all dirstat entries
+    #
+    # @overload each(&block)
+    #
+    #   @return [Array<Git::DirstatEntry>] the full list of dirstat entries
+    #
+    #   @yield [entry] each dirstat entry
+    #
+    #   @yieldparam entry [Git::DirstatEntry] a single dirstat entry
+    #
+    #   @yieldreturn [void]
+    #
+    def each(&block)
+      entries.each(&block)
+    end
+
+    include Enumerable
+  end
+end

data/lib/git/encoding_utils.rb

@@ -3,25 +3,56 @@
 require 'rchardet'
 
 module Git
-  # Method that can be used to detect and normalize string encoding
+  # Provides helpers for detecting and normalizing string encodings
+  #
+  # `default_encoding` refers to {Git::EncodingUtils.default_encoding}, which is
+  # derived from this source file's encoding declaration
+  #
+  # @api private
+  #
   module EncodingUtils
+    # Returns the default encoding name used by this source file
+    #
+    # @return [String] the source file encoding name
+    #
     def self.default_encoding
       __ENCODING__.name
     end
 
+    # Returns the fallback encoding name used when detection fails
+    #
+    # @return [String] the fallback encoding name
+    #
     def self.best_guess_encoding
       # Encoding::ASCII_8BIT.name
       Encoding::UTF_8.name
     end
 
+    # Returns the detected encoding name for the given string
+    #
+    # @param str [String] the string whose encoding should be detected
+    #
+    # @return [String] the detected encoding name or the fallback encoding name
+    #
     def self.detected_encoding(str)
       CharDet.detect(str)['encoding'] || best_guess_encoding
     end
 
+    # Returns replacement options used when transcoding invalid byte sequences
+    #
+    # @return [Hash<Symbol, Symbol>] options for replacing invalid and undefined bytes
+    #
     def self.encoding_options
       { invalid: :replace, undef: :replace }
     end
 
+    # Returns the given string converted to {Git::EncodingUtils.default_encoding}
+    #
+    # @param str [String] the string to normalize
+    #
+    # @return [String] the original or transcoded string in
+    #   {Git::EncodingUtils.default_encoding}
+    #
     def self.normalize_encoding(str)
       return str if str.valid_encoding? && str.encoding.name == default_encoding
 

data/lib/git/errors.rb

@@ -0,0 +1,285 @@
+# frozen_string_literal: true
+
+module Git
+  # 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
+  # `Git::Error`. It does not explicitly raise any other types of errors.
+  #
+  # It is recommended to rescue `Git::Error` to catch any runtime error raised by
+  # this gem unless you need more specific error handling.
+  #
+  # Git's custom errors are arranged in the following class heirarchy:
+  #
+  # ```text
+  # StandardError
+  # └─> Git::Error
+  #     ├─> Git::CommandLineError
+  #     │   ├─> Git::FailedError
+  #     │   └─> Git::SignaledError
+  #     │       └─> Git::TimeoutError
+  #     ├─> Git::ProcessIOError
+  #     ├─> Git::UnexpectedResultError
+  #     └─> Git::VersionError
+  # ```
+  #
+  # | 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. |
+  # | `VersionError` | The installed git version does not meet the requirements of the git gem or a specific command. |
+  #
+  # @example Rescuing a generic error
+  #   begin
+  #     # some git operation
+  #   rescue Git::Error => e
+  #     puts "An error occurred: #{e.message}"
+  #   end
+  #
+  # @example Rescuing a timeout error
+  #   begin
+  #     timeout_duration = 0.001 # seconds
+  #     repo = Git.clone('https://github.com/ruby-git/ruby-git', 'ruby-git-temp', timeout: timeout_duration)
+  #   rescue Git::TimeoutError => e # Catch the more specific error first!
+  #     puts "Git clone took too long and timed out #{e}"
+  #   rescue Git::Error => e
+  #     puts "Received the following error: #{e}"
+  #   end
+  #
+  # @see Git::CommandLineError
+  #
+  # @see Git::FailedError
+  #
+  # @see Git::SignaledError
+  #
+  # @see Git::TimeoutError
+  #
+  # @see Git::ProcessIOError
+  #
+  # @see Git::UnexpectedResultError
+  #
+  # @see Git::VersionError
+  #
+  # @api public
+  #
+  class Error < StandardError; end
+
+  # rubocop:enable Layout/LineLength
+
+  # An alias for Git::Error
+  #
+  # Git::GitExecuteError error class is an alias for Git::Error for backwards
+  # compatibility. It is recommended to use Git::Error directly.
+  #
+  # @deprecated Use Git::Error instead
+  #
+  GitExecuteError = ActiveSupport::Deprecation::DeprecatedConstantProxy.new('Git::GitExecuteError', 'Git::Error', Git::Deprecation)
+
+  # Raised when a git command fails or exits because of an uncaught signal
+  #
+  # The git command executed, status, stdout, and stderr are available from this
+  # object.
+  #
+  # The Gem will raise a more specific error for each type of failure:
+  #
+  # * {Git::FailedError}: when the git command exits with a non-zero status
+  # * {Git::SignaledError}: when the git command exits because of an uncaught signal
+  # * {Git::TimeoutError}: when the git command times out
+  #
+  # @api public
+  #
+  class CommandLineError < Git::Error
+    # Create a CommandLineError object
+    #
+    # @example
+    #   `exit 1` # set $? appropriately for this example
+    #   result = Git::CommandLine::Result.new(%w[git status], $?, 'stdout', 'stderr')
+    #   error = Git::CommandLineError.new(result)
+    #   error.to_s #=> '["git", "status"], status: pid 89784 exit 1, stderr: "stderr"'
+    #
+    # @param result [Git::CommandLine::Result] the result of the git command including
+    #   the git command, status, stdout, and stderr
+    #
+    def initialize(result)
+      @result = result
+      super(error_message)
+    end
+
+    # The human readable representation of this error
+    #
+    # @example
+    #   error.error_message #=> '["git", "status"], status: pid 89784 exit 1, stderr: "stderr"'
+    #
+    # @return [String]
+    #
+    def error_message = <<~MESSAGE.chomp
+      #{result.git_cmd}, status: #{result.status}, stderr: #{result.stderr.inspect}
+    MESSAGE
+
+    # The result of the git command including the git command and its status and output
+    #
+    # @example
+    #   error.result #=> #<Git::CommandLine::Result:0x00000001046bd488 ...>
+    #
+    # @return [Git::CommandLine::Result]
+    #
+    attr_reader :result
+  end
+
+  # This error is raised when a git command returns a non-zero exitstatus
+  #
+  # The git command executed, status, stdout, and stderr are available from this
+  # object.
+  #
+  # @api public
+  #
+  class FailedError < Git::CommandLineError; end
+
+  # This error is raised when a git command exits because of an uncaught signal
+  #
+  # @api public
+  #
+  class SignaledError < Git::CommandLineError; end
+
+  # This error is raised when a git command takes longer than the configured timeout
+  #
+  # The git command executed, status, stdout, and stderr, and the timeout duration
+  # are available from this object.
+  #
+  # result.status.timed_out? will be `true`
+  #
+  # @api public
+  #
+  class TimeoutError < Git::SignaledError
+    # Create a TimeoutError object
+    #
+    # @example
+    #   command = %w[sleep 10]
+    #   timeout_duration = 1
+    #   status = ProcessExecuter.spawn(*command, timeout: timeout_duration)
+    #   result = Git::CommandLine::Result.new(command, status, 'stdout', 'err output')
+    #   error = Git::TimeoutError.new(result, timeout_duration)
+    #   error.error_message
+    #   #=> '["sleep", "10"], status: pid 70144 SIGKILL (signal 9), stderr: "err output", timed out after 1s'
+    #
+    # @param result [Git::CommandLine::Result] the result of the git command including
+    #   the git command, status, stdout, and stderr
+    #
+    # @param timeout_duration [Numeric] the amount of time the subprocess was allowed
+    #   to run before being killed
+    #
+    def initialize(result, timeout_duration)
+      @timeout_duration = timeout_duration
+      super(result)
+    end
+
+    # The human readable representation of this error
+    #
+    # @example
+    #   error.error_message
+    #   #=> '["sleep", "10"], status: pid 88811 SIGKILL (signal 9), stderr: "err output", timed out after 1s'
+    #
+    # @return [String]
+    #
+    def error_message = <<~MESSAGE.chomp
+      #{super}, timed out after #{timeout_duration}s
+    MESSAGE
+
+    # The amount of time the subprocess was allowed to run before being killed
+    #
+    # @example
+    #   `kill -9 $$` # set $? appropriately for this example
+    #   result = Git::CommandLine::Result.new(%w[git status], $?, '', "killed")
+    #   error = Git::TimeoutError.new(result, 10)
+    #   error.timeout_duration #=> 10
+    #
+    # @return [Numeric]
+    #
+    attr_reader :timeout_duration
+  end
+
+  # Raised when the output of a git command can not be read
+  #
+  # @api public
+  #
+  class ProcessIOError < Git::Error; end
+
+  # Raised when the git command result was not as expected
+  #
+  # @api public
+  #
+  class UnexpectedResultError < Git::Error; end
+
+  # Raised when the installed git version does not meet requirements
+  #
+  # This error is raised when:
+  # - The installed git version is below `Git::MINIMUM_GIT_VERSION`
+  # - A command requires a minimum git version that isn't met
+  # - A command was removed in a git version older than the installed version
+  #
+  # @example Rescuing a version error
+  #   begin
+  #     git.some_command
+  #   rescue Git::VersionError => e
+  #     puts "Git version #{e.actual_version} does not meet requirements"
+  #     puts "  #{e.subject}: requires #{e.constraint}"
+  #   end
+  #
+  # @api public
+  #
+  class VersionError < Git::Error
+    # Create a VersionError
+    #
+    # @param subject [#to_s] the entity with the version requirement (e.g., "The git gem", a Class)
+    #
+    # @param constraint [Git::VersionConstraint] the version constraint that was violated
+    #
+    # @param actual_version [Git::Version] the installed git version
+    #
+    def initialize(subject:, constraint:, actual_version:)
+      @subject = subject
+      @constraint = constraint
+      @actual_version = actual_version
+      super(build_message)
+    end
+
+    # The entity that has the version requirement
+    #
+    # @return [#to_s]
+    #
+    attr_reader :subject
+
+    # The version constraint that was violated
+    #
+    # @return [Git::VersionConstraint]
+    #
+    attr_reader :constraint
+
+    # The installed git version that caused the error
+    #
+    # @return [Git::Version]
+    #
+    attr_reader :actual_version
+
+    private
+
+    # Builds the error message for the violated version constraint.
+    #
+    # @return [String]
+    #
+    def build_message
+      if constraint.too_new?(actual_version)
+        "#{subject} requires git < #{constraint.before} (found #{actual_version})"
+      else
+        "#{subject} requires git >= #{constraint.min} (found #{actual_version})"
+      end
+    end
+  end
+end

data/lib/git/escaped_path.rb

@@ -3,15 +3,20 @@
 module Git
   # Represents an escaped Git path string
   #
-  # Git commands that output paths (e.g. ls-files, diff), will escape usual
+  # Git commands that output paths (e.g. ls-files, diff), will escape unusual
   # characters in the path with backslashes in the same way C escapes control
   # characters (e.g. \t for TAB, \n for LF, \\ for backslash) or bytes with values
   # larger than 0x80 (e.g. octal \302\265 for "micro" in UTF-8).
   #
-  # @example
-  #   Git::GitPath.new('\302\265').unescape # => "µ"
+  # @example Decode octal UTF-8 bytes
+  #   Git::EscapedPath.new('\302\265').unescape # => "µ"
+  #
+  # @api private
   #
   class EscapedPath
+    # Maps single-character escapes to their decoded byte values
+    #
+    # @return [Hash<String, Integer>] escape characters mapped to byte values
     UNESCAPES = {
       'a' => 0x07,
       'b' => 0x08,
@@ -26,13 +31,27 @@ module Git
       "'" => 0x27
     }.freeze
 
+    # Returns the escaped path as provided by git output
+    #
+    # @return [String] the escaped path string
     attr_reader :path
 
+    # Initializes an escaped path wrapper
+    #
+    # @param path [String] the path string with Git-style escape sequences
+    #
+    # @return [void]
     def initialize(path)
       @path = path
     end
 
-    # Convert an escaped path to an unescaped path
+    # Converts an escaped path to an unescaped UTF-8 path
+    #
+    # @example Decode escaped path output
+    #   Git::EscapedPath.new("dir/\\342\\230\\240\\n").unescape
+    #   # => "dir/☠\n"
+    #
+    # @return [String] the decoded path string
     def unescape
       bytes = escaped_path_to_bytes(path)
       str = bytes.pack('C*')
@@ -41,18 +60,46 @@ module Git
 
     private
 
+    # Extracts an octal escape sequence starting at the given index
+    #
+    # @param path [String] the escaped path string
+    #
+    # @param index [Integer] the index where the sequence starts
+    #
+    # @return [Array(Integer, Integer)] decoded byte and consumed character count
     def extract_octal(path, index)
-      [path[index + 1..index + 3].to_i(8), 4]
+      [path[(index + 1)..(index + 3)].to_i(8), 4]
     end
 
+    # Extracts a single-character escape sequence at the given index
+    #
+    # @param path [String] the escaped path string
+    #
+    # @param index [Integer] the index where the sequence starts
+    #
+    # @return [Array(Integer, Integer)] decoded byte and consumed character count
     def extract_escape(path, index)
       [UNESCAPES[path[index + 1]], 2]
     end
 
+    # Extracts a non-escaped character byte at the given index
+    #
+    # @param path [String] the escaped path string
+    #
+    # @param index [Integer] the index of the character to decode
+    #
+    # @return [Array(Integer, Integer)] decoded byte and consumed character count
     def extract_single_char(path, index)
       [path[index].ord, 1]
     end
 
+    # Decodes the next byte from the escaped path at the given index
+    #
+    # @param path [String] the escaped path string
+    #
+    # @param index [Integer] the index to decode from
+    #
+    # @return [Array(Integer, Integer)] decoded byte and consumed character count
     def next_byte(path, index)
       if path[index] == '\\' && path[index + 1] >= '0' && path[index + 1] <= '7'
         extract_octal(path, index)
@@ -63,6 +110,11 @@ module Git
       end
     end
 
+    # Converts an escaped path string into decoded bytes
+    #
+    # @param path [String] the escaped path string
+    #
+    # @return [Array<Integer>] decoded bytes in order
     def escaped_path_to_bytes(path)
       index = 0
       [].tap do |bytes|

data/lib/git/execution_context/global.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'git/execution_context'
+
+module Git
+  class ExecutionContext
+    # Execution context for global git commands (no repository required)
+    #
+    # Used for commands that do not require an existing repository — such as
+    # `git init`, `git clone`, and `git version`. Unlike
+    # {Git::ExecutionContext::Repository}, this class leaves `GIT_DIR`,
+    # `GIT_WORK_TREE`, and `GIT_INDEX_FILE` as `nil` (which unsets them), so
+    # that the parent environment cannot leak an unintended repository context.
+    # `GIT_SSH` is still supported to allow SSH-based remote operations
+    # (e.g. `git clone git@github.com:...`).
+    #
+    # @example Create a context using the default git binary
+    #   context = Git::ExecutionContext::Global.new
+    #
+    # @example Create a context targeting a specific binary
+    #   context = Git::ExecutionContext::Global.new(binary_path: '/usr/local/bin/git2')
+    #
+    # @see Git::ExecutionContext#initialize for constructor parameters and
+    #   their semantics
+    #
+    # @api private
+    #
+    class Global < ExecutionContext
+    end
+  end
+end