git 5.0.0.beta.2 → 5.0.0.beta.4

data/lib/git/dirstat_info.rb

@@ -3,13 +3,15 @@
 module Git
   # Immutable value object representing a single directory's contribution to a diff
   #
-  # @api public
-  #
-  # @example
+  # @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 '/')
   #
@@ -22,9 +24,7 @@ module Git
   #
   # Contains the list of directories and their contribution percentages to the diff.
   #
-  # @api public
-  #
-  # @example
+  # @example Create a DirstatInfo
   #   dirstat = Git::DirstatInfo.new(
   #     entries: [
   #       Git::DirstatEntry.new(directory: 'lib/commands/', percentage: 45.2),
@@ -35,6 +35,10 @@ module Git
   #   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
   #
@@ -42,6 +46,7 @@ module Git
     # Look up percentage by directory path
     #
     # @param directory [String] the directory path
+    #
     # @return [Float, nil] the percentage or nil if not found
     #
     def [](directory)
@@ -74,8 +79,19 @@ module Git
 
     # Iterate over entries
     #
-    # @yield [DirstatEntry] each entry
-    # @return [Enumerator] if no block given
+    # @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)

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

@@ -54,11 +54,17 @@ module Git
   #   end
   #
   # @see Git::CommandLineError
+  #
   # @see Git::FailedError
+  #
   # @see Git::SignaledError
+  #
   # @see Git::TimeoutError
+  #
   # @see Git::ProcessIOError
+  #
   # @see Git::UnexpectedResultError
+  #
   # @see Git::VersionError
   #
   # @api public
@@ -94,11 +100,11 @@ module Git
     #
     # @example
     #   `exit 1` # set $? appropriately for this example
-    #   result = Git::CommandLineResult.new(%w[git status], $?, 'stdout', 'stderr')
+    #   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::CommandLineResult] the result of the git command including
+    # @param result [Git::CommandLine::Result] the result of the git command including
     #   the git command, status, stdout, and stderr
     #
     def initialize(result)
@@ -117,14 +123,12 @@ module Git
       #{result.git_cmd}, status: #{result.status}, stderr: #{result.stderr.inspect}
     MESSAGE
 
-    # @attribute [r] result
-    #
     # The result of the git command including the git command and its status and output
     #
     # @example
-    #   error.result #=> #<Git::CommandLineResult:0x00000001046bd488 ...>
+    #   error.result #=> #<Git::CommandLine::Result:0x00000001046bd488 ...>
     #
-    # @return [Git::CommandLineResult]
+    # @return [Git::CommandLine::Result]
     #
     attr_reader :result
   end
@@ -160,12 +164,12 @@ module Git
     #   command = %w[sleep 10]
     #   timeout_duration = 1
     #   status = ProcessExecuter.spawn(*command, timeout: timeout_duration)
-    #   result = Git::CommandLineResult.new(command, status, 'stdout', 'err output')
+    #   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::CommandLineResult] the result of the git command including
+    # @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
@@ -192,7 +196,7 @@ module Git
     #
     # @example
     #   `kill -9 $$` # set $? appropriately for this example
-    #   result = Git::CommandLineResult.new(%w[git status], $?, '', "killed")
+    #   result = Git::CommandLine::Result.new(%w[git status], $?, '', "killed")
     #   error = Git::TimeoutError.new(result, 10)
     #   error.timeout_duration #=> 10
     #
@@ -234,7 +238,9 @@ module Git
     # 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:)
@@ -264,6 +270,10 @@ module Git
 
     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})"

data/lib/git/escaped_path.rb

@@ -8,10 +8,15 @@ module Git
   # 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]
     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/repository.rb

@@ -116,6 +116,21 @@ module Git
       #
       # @param overrides [Hash] keyword arguments to override in the new instance
       #
+      # @option overrides [String, nil] :git_dir path to the `.git` directory
+      #
+      # @option overrides [String, nil] :git_work_dir path to the working tree
+      #
+      # @option overrides [String, nil] :git_index_file path to the index file
+      #
+      # @option overrides [String, :use_global_config] :binary_path path to the git
+      #   binary
+      #
+      # @option overrides [String, nil, :use_global_config] :git_ssh the SSH
+      #   wrapper path
+      #
+      # @option overrides [Logger, nil] :logger the logger to use in the
+      #   CommandLine layer
+      #
       # @return [Git::ExecutionContext::Repository] the new context
       #
       # @api private

data/lib/git/execution_context.rb

@@ -222,8 +222,6 @@ module Git
     #
     # @overload command_capturing(*args, **options_hash)
     #
-    #   Runs a git command and returns the result
-    #
     #   Args should exclude the 'git' command itself and global options. Remember to
     #   splat the arguments if given as an array.
     #
@@ -241,64 +239,64 @@ module Git
     #
     #   @param args [Array<String>] the command and its arguments
     #
-    #   @param options_hash [Hash] the options to pass to the command
+    #   @return [Git::CommandLine::Result] the result of the command
     #
-    #   @option options_hash [IO, nil] :in the IO object to use as stdin, or nil to
-    #     inherit the parent process stdin
+    # @param options_hash [Hash] the options to pass to the command
     #
-    #     Must be a real IO object with a file descriptor.
+    # @option options_hash [IO, nil] :in the IO object to use as stdin, or nil to
+    #   inherit the parent process stdin
     #
-    #   @option options_hash [IO, String, #write, nil] :out the destination for
-    #     captured stdout
+    #   Must be a real IO object with a file descriptor.
     #
-    #   @option options_hash [IO, String, #write, nil] :err the destination for
-    #     captured stderr
+    # @option options_hash [IO, String, #write, nil] :out the destination for
+    #   captured stdout
     #
-    #   @option options_hash [Boolean, nil] :normalize (true) normalize the output
-    #     encoding to UTF-8
+    # @option options_hash [IO, String, #write, nil] :err the destination for
+    #   captured stderr
     #
-    #   @option options_hash [Boolean, nil] :chomp (true) remove trailing newlines
-    #     from the output
+    # @option options_hash [Boolean, nil] :normalize (true) normalize the output
+    #   encoding to UTF-8
     #
-    #   @option options_hash [Boolean, nil] :merge (false) merge stdout and stderr
-    #     into a single output
+    # @option options_hash [Boolean, nil] :chomp (true) remove trailing newlines
+    #   from the output
     #
-    #   @option options_hash [String, nil] :chdir the directory to run the command in
+    # @option options_hash [Boolean, nil] :merge (false) merge stdout and stderr
+    #   into a single output
     #
-    #   @option options_hash [Hash] :env additional environment variable overrides
-    #     for this command
+    # @option options_hash [String, nil] :chdir the directory to run the command in
     #
-    #   @option options_hash [Boolean, nil] :raise_on_failure (true) whether to raise on
-    #     non-zero exit
+    # @option options_hash [Hash] :env additional environment variable overrides
+    #   for this command
     #
-    #   @option options_hash [Numeric, nil] :timeout the maximum seconds to wait for
-    #     the command to complete
+    # @option options_hash [Boolean, nil] :raise_on_failure (true) whether to raise on
+    #   non-zero exit
     #
-    #     If timeout is nil, the global timeout from {Git::Config} is used.
+    # @option options_hash [Numeric, nil] :timeout the maximum seconds to wait for
+    #   the command to complete
     #
-    #     If timeout is zero, the timeout will not be enforced.
+    #   If timeout is nil, the global timeout from {Git::Config} is used.
     #
-    #     If the command times out, it is killed via a `SIGKILL` signal and
-    #     `Git::TimeoutError` is raised.
+    #   If timeout is zero, the timeout will not be enforced.
     #
-    #     If the command does not respond to SIGKILL, it will hang this method.
+    #   If the command times out, it is killed via a `SIGKILL` signal and
+    #   `Git::TimeoutError` is raised.
     #
-    #   @return [Git::CommandLineResult] the result of the command
+    #   If the command does not respond to SIGKILL, it will hang this method.
     #
-    #   @raise [ArgumentError] if an unknown option is passed
+    # @raise [ArgumentError] if an unknown option is passed
     #
-    #   @raise [Git::FailedError] if the command failed (when raise_on_failure is
-    #     true)
+    # @raise [Git::FailedError] if the command failed (when raise_on_failure is
+    #   true)
     #
-    #   @raise [Git::SignaledError] if the command was signaled
+    # @raise [Git::SignaledError] if the command was signaled
     #
-    #   @raise [Git::TimeoutError] if the command times out
+    # @raise [Git::TimeoutError] if the command times out
     #
-    #   @raise [Git::ProcessIOError] if an exception was raised while collecting
-    #     subprocess output
+    # @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.
+    #   The exception's `result` attribute is a {Git::CommandLine::Result} which will
+    #   contain the result of the command including the exit status, stdout, and stderr.
     #
     # @note Individual command classes (under {Git::Commands}) can selectively expose
     #   `:timeout` and `:env` and other options to their callers by declaring them as
@@ -340,58 +338,58 @@ module Git
     #
     #   @param args [Array<String>] the git command and its arguments
     #
-    #   @param options_hash [Hash] the options to pass to the command
+    #   @return [Git::CommandLine::Result] the result of the command
     #
-    #   @option options_hash [IO, nil] :in the IO object to use as stdin, or nil to
-    #     inherit the parent process stdin
+    # @param options_hash [Hash] the options to pass to the command
     #
-    #     Must be a real IO object with a file descriptor.
+    # @option options_hash [IO, nil] :in the IO object to use as stdin, or nil to
+    #   inherit the parent process stdin
     #
-    #   @option options_hash [#write, nil] :out destination for streamed stdout
+    #   Must be a real IO object with a file descriptor.
     #
-    #   @option options_hash [#write, nil] :err an optional additional destination
-    #     to receive stderr output in real time
+    # @option options_hash [#write, nil] :out destination for streamed stdout
     #
-    #     Stderr is always captured internally; when `err:` is supplied, writes are
-    #     teed to both the internal buffer and this destination. `result.stderr`
-    #     always reflects the internal capture.
+    # @option options_hash [#write, nil] :err an optional additional destination
+    #   to receive stderr output in real time
     #
-    #   @option options_hash [String, nil] :chdir the directory to run the command in
+    #   Stderr is always captured internally; when `err:` is supplied, writes are
+    #   teed to both the internal buffer and this destination. `result.stderr`
+    #   always reflects the internal capture.
     #
-    #   @option options_hash [Hash] :env additional environment variable overrides
-    #     for this command
+    # @option options_hash [String, nil] :chdir the directory to run the command in
     #
-    #   @option options_hash [Boolean, nil] :raise_on_failure (true) whether to raise on
-    #     non-zero exit
+    # @option options_hash [Hash] :env additional environment variable overrides
+    #   for this command
     #
-    #   @option options_hash [Numeric, nil] :timeout
-    #     the maximum seconds to wait for the command to complete
+    # @option options_hash [Boolean, nil] :raise_on_failure (true) whether to raise on
+    #   non-zero exit
     #
-    #     If timeout is nil, the global timeout from {Git::Config} is used.
+    # @option options_hash [Numeric, nil] :timeout the maximum seconds to wait for
+    #   the command to complete
     #
-    #     If timeout is zero, the timeout will not be enforced.
+    #   If timeout is nil, the global timeout from {Git::Config} is used.
     #
-    #     If the command times out, it is killed via a `SIGKILL` signal and
-    #     `Git::TimeoutError` is raised.
+    #   If timeout is zero, the timeout will not be enforced.
     #
-    #     If the command does not respond to SIGKILL, it will hang this method.
+    #   If the command times out, it is killed via a `SIGKILL` signal and
+    #   `Git::TimeoutError` is raised.
     #
-    #   @return [Git::CommandLineResult] the result of the command
+    #   If the command does not respond to SIGKILL, it will hang this method.
     #
-    #     `result.stdout` will always be `''` — stdout was streamed to `out:`.
+    #   `result.stdout` will always be `''` — stdout was streamed to `out:`.
     #
-    #     `result.stderr` contains any stderr output captured for diagnostics.
+    #   `result.stderr` contains any stderr output captured for diagnostics.
     #
-    #   @raise [ArgumentError] if an unknown option is passed
+    # @raise [ArgumentError] if an unknown option is passed
     #
-    #   @raise [Git::FailedError] if the command failed (when raise_on_failure is true)
+    # @raise [Git::FailedError] if the command failed (when raise_on_failure is true)
     #
-    #   @raise [Git::SignaledError] if the command was signaled
+    # @raise [Git::SignaledError] if the command was signaled
     #
-    #   @raise [Git::TimeoutError] if the command times out
+    # @raise [Git::TimeoutError] if the command times out
     #
-    #   @raise [Git::ProcessIOError] if an exception was raised while collecting
-    #     subprocess output
+    # @raise [Git::ProcessIOError] if an exception was raised while collecting
+    #   subprocess output
     #
     # @see Git::CommandLine::Streaming#run
     #
@@ -435,9 +433,16 @@ module Git
     #
     # Per `Process.spawn` semantics, a value of `nil` unsets the variable.
     #
-    # @param additional_overrides [Hash<String, String|nil>] per-call overrides
+    # @param additional_overrides [Hash{String => String, nil}] per-call
+    #   environment overrides keyed by variable name
+    #
+    #   Pass string environment variable names. Ruby preserves string keys when
+    #   callers forward a string-keyed Hash with `**`.
     #
-    # @return [Hash<String, String|nil>] the merged environment variable overrides
+    # @option additional_overrides [String, nil] :"ENV_VAR" value for an arbitrary
+    #   environment variable name
+    #
+    # @return [Hash{String => String, nil}] the merged environment variable overrides
     #
     # @api private
     #
@@ -496,6 +501,3 @@ module Git
     end
   end
 end
-
-require 'git/execution_context/global'
-require 'git/execution_context/repository'

data/lib/git/file_ref.rb

@@ -11,7 +11,6 @@ module Git
   # dst for deleted files), the entire FileRef should be nil rather than having
   # a FileRef with nil attributes.
   #
-  # @api public
   #
   # @example A modified file's source reference
   #   src = Git::FileRef.new(mode: '100644', sha: 'abc1234', path: 'lib/foo.rb')
@@ -20,6 +19,10 @@ module Git
   #   # src = nil
   #   dst = Git::FileRef.new(mode: '100644', sha: 'def5678', path: 'lib/new_file.rb')
   #
+  # @api private
+  #
+  # Work in progress; this class is internal for now and may be made public in a future release.
+  #
   # @!attribute [r] mode
   #   @return [String] the file mode (e.g., '100644' for regular file, '100755' for executable,
   #     '120000' for symlink)
@@ -59,14 +62,14 @@ module Git
     #
     # Useful for bit operations on file permissions.
     #
-    # @return [Integer] the mode as an integer
-    #
     # @example Check file permissions
     #   ref.mode_bits & 0o777  # => 0o644 (420 decimal)
     #
     # @example Check if group writable
     #   (ref.mode_bits & 0o020) != 0
     #
+    # @return [Integer] the mode as an integer
+    #
     def mode_bits
       mode.to_i(8)
     end

data/lib/git/fsck_object.rb

@@ -10,26 +10,33 @@ module Git
   #
   class FsckObject
     # The type of the Git object
+    #
     # @return [Symbol] one of :commit, :tree, :blob, or :tag
     attr_reader :type
 
     # The object identifier (OID) of the object
+    #
     # @return [String] the 40-character object identifier
     attr_reader :oid
 
     # A warning or error message associated with this object
+    #
     # @return [String, nil] the message, or nil if no message
     attr_reader :message
 
     # A name describing how the object is reachable (from --name-objects)
+    #
     # @return [String, nil] the name, or nil if not provided
     attr_reader :name
 
     # Create a new FsckObject
     #
     # @param type [Symbol] the object type (:commit, :tree, :blob, or :tag)
+    #
     # @param oid [String] the 40-character object identifier
+    #
     # @param message [String, nil] optional warning/error message
+    #
     # @param name [String, nil] optional name from --name-objects (e.g., "HEAD~2^2:src/")
     #
     def initialize(type:, oid:, message: nil, name: nil)
@@ -40,6 +47,7 @@ module Git
     end
 
     # Returns the OID as the string representation
+    #
     # @return [String] the object identifier
     def to_s
       oid