git 5.7.0 → 6.0.0

data/git.gemspec

@@ -38,11 +38,12 @@ Gem::Specification.new do |spec|
   spec.metadata['rubygems_mfa_required'] = 'true'
 
   spec.require_paths = ['lib']
-  spec.required_ruby_version = '>= 3.2.0'
-  spec.requirements = ['git 2.28.0 or greater']
+  spec.required_ruby_version = '>= 3.3.0'
+  spec.requirements = ['git 2.43.0 or greater']
 
-  spec.add_dependency 'activesupport', '>= 5.0'
-  spec.add_dependency 'addressable', '~> 2.8'
+  spec.add_dependency 'activesupport', '>= 7.0.9'
+  spec.add_dependency 'addressable', '~> 2.9'
+  spec.add_dependency 'logger', '~> 1.6'
   spec.add_dependency 'process_executer', '~> 4.1'
   spec.add_dependency 'rchardet', '~> 1.9'
 
@@ -74,9 +75,6 @@ Gem::Specification.new do |spec|
   # is also a C extension and so could not install on JRuby regardless.
   install_docs = mri
 
-  # yard-lint requires Ruby >= 3.3.
-  install_yard_lint = install_docs && Gem.ruby_version >= Gem::Version.new('3.3.0')
-
   # i18n 1.15+ uses Fiber.[] (Ruby 3.2 Fiber storage), which TruffleRuby < 34.0.0 does
   # not implement, so those runtimes hold at the last release that works there.
   pin_old_i18n = RUBY_ENGINE == 'truffleruby' &&
@@ -98,7 +96,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'simplecov-rspec', '~> 1.1'
   spec.add_development_dependency 'yard', '~> 0.9', '>= 0.9.28' if install_docs
   spec.add_development_dependency 'yard_example_test', '~> 0.2', '>= 0.2.1' if install_docs
-  spec.add_development_dependency 'yard-lint', '~> 1.8' if install_yard_lint
+  spec.add_development_dependency 'yard-lint', '~> 1.8' if install_docs
 
   # Specify which files should be added to the gem when it is released.
   #

data/lib/git/author_info.rb

@@ -4,8 +4,7 @@ module Git
   # Immutable value object representing an author or committer identity
   #
   # This is a lightweight, immutable data structure holding the identity data
-  # git records for commit authors, committers, and taggers. It replaces the
-  # mutable {Git::Author}, which is deprecated.
+  # git records for commit authors, committers, and taggers.
   #
   # @example Construct from individual values
   #   info = Git::AuthorInfo.new(

data/lib/git/commands/base.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'git/commands/arguments'
+require 'git/system_call_guard'
 require 'git/version'
 require 'git/version_constraint'
 
@@ -451,6 +452,10 @@ module Git
       # Pass an empty string when the process should receive no input (e.g.
       # when `--batch-all-objects` is used and git enumerates objects itself).
       #
+      # Both ends of the pipe are closed by the time this method returns or
+      # raises, whether the failure happens in the block, in the writer thread,
+      # or before the writer thread can be started.
+      #
       # @example Feed bound object names to a git batch command
       #   bound = args_definition.bind(*args, **kwargs)
       #   stdin_content = Array(bound.object).map { |object| "#{object}\n" }.join
@@ -462,6 +467,13 @@ module Git
       #
       # @return [Object] the value returned by the block
       #
+      # @raise [Git::Error] if the pipe cannot be created (for example, when the
+      #   process is out of file descriptors); the `SystemCallError` is the `cause`
+      #
+      # @raise [Git::Error] if the writer thread cannot be started (for example,
+      #   when the process cannot allocate another thread); the `ThreadError` is
+      #   the `cause`
+      #
       # @yield [reader] the read end of the pipe
       #
       # @yieldparam reader [IO] the read end of the pipe; valid only for the
@@ -470,11 +482,14 @@ module Git
       # @yieldreturn [Object] the block's return value, which becomes the method's return value
       #
       def with_stdin(content)
-        reader, writer = IO.pipe
+        reader, writer = Git::SystemCallGuard.call('Failed to create a pipe for stdin') { IO.pipe }
         writer_thread = start_stdin_writer(content, writer)
         yield reader
       ensure
-        reader.close unless reader.closed?
+        reader.close unless reader.nil? || reader.closed?
+        # The writer thread owns writer and closes it when it finishes. Close it
+        # here only when the thread was never started (Thread.new raised).
+        writer.close if writer_thread.nil? && !(writer.nil? || writer.closed?)
         writer_thread&.join
       end
 
@@ -488,6 +503,9 @@ module Git
       #
       # @return [Thread] thread writing content to the pipe
       #
+      # @raise [Git::Error] if the thread cannot be started; the `ThreadError` is
+      #   the `cause`
+      #
       def start_stdin_writer(content, writer)
         Thread.new do
           writer.write(content) unless content.empty?
@@ -496,6 +514,8 @@ module Git
         ensure
           writer.close unless writer.closed?
         end
+      rescue ThreadError => e
+        raise Git::Error, "Failed to start the stdin writer thread: #{e.message}"
       end
     end
   end

data/lib/git/commands/cat_file/raw.rb

@@ -49,14 +49,6 @@ module Git
           # See https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt--s
           flag_option :s
 
-          # Allow -t and -s to query broken or corrupt objects of unknown type.
-          # Deprecated and removed in v6.0.0 (see issue 1709); passing it emits a
-          # deprecation warning. Git 2.28-2.49 honors it with -t and -s and rejects
-          # it in other modes; git 2.50+ accepts and ignores it everywhere (the
-          # unknown-type feature was removed).
-          # See https://git-scm.com/docs/git-cat-file/2.49.0#Documentation/git-cat-file.txt---allow-unknown-type
-          flag_option :allow_unknown_type
-
           # Map committer/author identities through the mailmap before reporting size
           # See https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt---use-mailmap
           flag_option :use_mailmap, negatable: true
@@ -93,13 +85,6 @@ module Git
         #
         #   @param options [Hash] command options
         #
-        #   @option options [Boolean, nil] :allow_unknown_type (nil) pass `--allow-unknown-type` through to git,
-        #     which rejects it in this mode on git 2.28-2.49 and accepts it as a no-op
-        #     on git 2.50 and later
-        #
-        #     Deprecated and removed in v6.0.0; passing it emits a deprecation
-        #     warning.
-        #
         #   @option options [Boolean, nil] :use_mailmap (nil) remap identities via mailmap (`--use-mailmap`)
         #
         #   @option options [Boolean, nil] :no_use_mailmap (nil) suppress mailmap remapping (`--no-use-mailmap`)
@@ -121,13 +106,6 @@ module Git
         #
         #   @param options [Hash] command options
         #
-        #   @option options [Boolean, nil] :allow_unknown_type (nil) allow querying broken or corrupt objects of
-        #     unknown type on git 2.28-2.49
-        #
-        #     Deprecated and removed in v6.0.0; passing it emits a deprecation
-        #     warning. Git 2.50 removed the unknown-type feature and accepts this
-        #     flag as a no-op.
-        #
         #   @option options [Boolean, nil] :use_mailmap (nil) remap identities via mailmap (`--use-mailmap`)
         #
         #   @option options [Boolean, nil] :no_use_mailmap (nil) suppress mailmap remapping (`--no-use-mailmap`)
@@ -149,13 +127,6 @@ module Git
         #
         #   @param options [Hash] command options
         #
-        #   @option options [Boolean, nil] :allow_unknown_type (nil) allow querying broken or corrupt objects of
-        #     unknown type on git 2.28-2.49
-        #
-        #     Deprecated and removed in v6.0.0; passing it emits a deprecation
-        #     warning. Git 2.50 removed the unknown-type feature and accepts this
-        #     flag as a no-op.
-        #
         #   @option options [Boolean, nil] :use_mailmap (nil) remap identities via mailmap (`--use-mailmap`)
         #
         #   @option options [Boolean, nil] :no_use_mailmap (nil) suppress mailmap remapping (`--no-use-mailmap`)
@@ -177,13 +148,6 @@ module Git
         #
         #   @param options [Hash] command options
         #
-        #   @option options [Boolean, nil] :allow_unknown_type (nil) pass `--allow-unknown-type` through to git,
-        #     which rejects it in this mode on git 2.28-2.49 and accepts it as a no-op
-        #     on git 2.50 and later
-        #
-        #     Deprecated and removed in v6.0.0; passing it emits a deprecation
-        #     warning.
-        #
         #   @option options [Boolean, nil] :use_mailmap (nil) remap identities via mailmap (`--use-mailmap`)
         #
         #   @option options [Boolean, nil] :no_use_mailmap (nil) suppress mailmap remapping (`--no-use-mailmap`)
@@ -205,13 +169,6 @@ module Git
         #
         #   @param options [Hash] command options
         #
-        #   @option options [Boolean, nil] :allow_unknown_type (nil) pass `--allow-unknown-type` through to git,
-        #     which rejects it in this mode on git 2.28-2.49 and accepts it as a no-op
-        #     on git 2.50 and later
-        #
-        #     Deprecated and removed in v6.0.0; passing it emits a deprecation
-        #     warning.
-        #
         #   @option options [Boolean, nil] :use_mailmap (nil) remap identities via mailmap (`--use-mailmap`)
         #
         #   @option options [Boolean, nil] :no_use_mailmap (nil) suppress mailmap remapping (`--no-use-mailmap`)
@@ -228,7 +185,6 @@ module Git
         #   @option options [Numeric, nil] :timeout (nil) abort the command after this many seconds
         #
         def call(*, **)
-          warn_allow_unknown_type_deprecated(**)
           bound = args_definition.bind(*, **)
           validate_version!(bound.execution_options)
           result = execute_command(bound)
@@ -241,30 +197,6 @@ module Git
 
           result
         end
-
-        private
-
-        # Emit the deprecation warning when the `allow_unknown_type` keyword is passed
-        #
-        # Keys on the keyword being present, whatever its value: `false` and `nil`
-        # suppress the flag but still name a deprecated option.
-        #
-        # @param options [Hash] the keyword arguments passed to {#call}
-        #
-        # @option options [Boolean, nil] :allow_unknown_type the deprecated option;
-        #   any value, including `false` and `nil`, triggers the warning
-        #
-        # @return [void]
-        #
-        def warn_allow_unknown_type_deprecated(**options)
-          return unless options.key?(:allow_unknown_type)
-
-          Git::Deprecation.warn(
-            'The allow_unknown_type option of Git::Commands::CatFile::Raw is deprecated ' \
-            'and will be removed in v6.0.0. Git 2.50 removed the unknown-type feature ' \
-            'and accepts --allow-unknown-type as a no-op.'
-          )
-        end
       end
     end
   end

data/lib/git/commands/maintenance/register.rb

@@ -22,8 +22,6 @@ module Git
       # @api private
       #
       class Register < Git::Commands::Base
-        requires_git_version '2.30.0'
-
         arguments do
           literal 'maintenance'
           literal 'register'
@@ -65,8 +63,6 @@ module Git
         #
         #   @raise [Git::FailedError] if git exits with a non-zero exit status
         #
-        #   @raise [Git::VersionError] if git version is below 2.30.0
-        #
         #   @api public
         def call(*, **)
           super

data/lib/git/commands/maintenance/run.rb

@@ -28,8 +28,6 @@ module Git
       # @api private
       #
       class Run < Git::Commands::Base
-        requires_git_version '2.30.0'
-
         arguments do
           literal 'maintenance'
           literal 'run'
@@ -100,8 +98,6 @@ module Git
         #
         #     @raise [Git::FailedError] if git exits with a non-zero exit status
         #
-        #     @raise [Git::VersionError] if git version is below 2.30.0
-        #
         #     @api public
       end
     end

data/lib/git/commands/maintenance/start.rb

@@ -22,8 +22,6 @@ module Git
       # @api private
       #
       class Start < Git::Commands::Base
-        requires_git_version '2.30.0'
-
         arguments do
           literal 'maintenance'
           literal 'start'
@@ -63,8 +61,6 @@ module Git
         #     @raise [ArgumentError] if unsupported options are provided
         #
         #     @raise [Git::FailedError] if git exits with a non-zero exit status
-        #
-        #     @raise [Git::VersionError] if git version is below 2.30.0
       end
     end
   end

data/lib/git/commands/maintenance/stop.rb

@@ -19,8 +19,6 @@ module Git
       # @api private
       #
       class Stop < Git::Commands::Base
-        requires_git_version '2.30.0'
-
         arguments do
           literal 'maintenance'
           literal 'stop'
@@ -52,8 +50,6 @@ module Git
         #     @raise [ArgumentError] if unsupported options are provided
         #
         #     @raise [Git::FailedError] if git exits with a non-zero exit status
-        #
-        #     @raise [Git::VersionError] if git version is below 2.30.0
       end
     end
   end

data/lib/git/commands/maintenance/unregister.rb

@@ -22,8 +22,6 @@ module Git
       # @api private
       #
       class Unregister < Git::Commands::Base
-        requires_git_version '2.30.0'
-
         arguments do
           literal 'maintenance'
           literal 'unregister'
@@ -75,8 +73,6 @@ module Git
         #
         #     @raise [Git::FailedError] if git exits with a non-zero exit status
         #
-        #     @raise [Git::VersionError] if git version is below 2.30.0
-        #
         #     @api public
       end
     end

data/lib/git/commands/maintenance.rb

@@ -19,8 +19,6 @@ module Git
     # - {Maintenance::Register} — add repository to maintenance config
     # - {Maintenance::Unregister} — remove repository from maintenance config
     #
-    # All subcommands require Git 2.30.0 or later.
-    #
     # @see https://git-scm.com/docs/git-maintenance git-maintenance documentation
     #
     # @api private

data/lib/git/commands/show_ref/exclude_existing.rb

@@ -16,7 +16,7 @@ module Git
       #
       # For standard ref listing, use {Git::Commands::ShowRef::List}.
       # For strict per-ref verification, use {Git::Commands::ShowRef::Verify}.
-      # For a boolean existence check (git >= 2.43), use {Git::Commands::ShowRef::Exists}.
+      # For a boolean existence check, use {Git::Commands::ShowRef::Exists}.
       #
       # @example Filter refs that do not exist locally
       #   cmd = Git::Commands::ShowRef::ExcludeExisting.new(execution_context)

data/lib/git/commands/show_ref/exists.rb

@@ -25,11 +25,6 @@ module Git
       #   result = cmd.call('refs/heads/main')
       #   result.status.exitstatus  # => 0 (exists) or 2 (not found)
       #
-      # @note Requires git 2.43 or later
-      #
-      #   Earlier versions do not recognise the `--exists` flag and will exit
-      #   non-zero with an "unknown option" error.
-      #
       # @note `arguments` block audited against https://git-scm.com/docs/git-show-ref/2.53.0
       #
       # @see Git::Commands::ShowRef

data/lib/git/commands/show_ref/list.rb

@@ -16,7 +16,7 @@ module Git
       #
       # For strict per-ref verification, use {Git::Commands::ShowRef::Verify}.
       # For stdin-based filtering, use {Git::Commands::ShowRef::ExcludeExisting}.
-      # For a simple boolean existence check (git >= 2.43), use {Git::Commands::ShowRef::Exists}.
+      # For a simple boolean existence check, use {Git::Commands::ShowRef::Exists}.
       #
       # @example List all refs
       #   cmd = Git::Commands::ShowRef::List.new(execution_context)

data/lib/git/commands/show_ref/verify.rb

@@ -18,7 +18,7 @@ module Git
       #
       # For pattern-based listing, use {ShowRef::List}.
       # For stdin-based filtering, use {ShowRef::ExcludeExisting}.
-      # For a silent boolean check (git >= 2.43), use {ShowRef::Exists}.
+      # For a silent boolean check, use {ShowRef::Exists}.
       #
       # @example Verify a single ref
       #   cmd = Git::Commands::ShowRef::Verify.new(execution_context)

data/lib/git/commands/show_ref.rb

@@ -18,7 +18,7 @@ module Git
     # - {ShowRef::ExcludeExisting} — stdin-based filter for ref names, excluding
     #   refs that already exist in the repository
     #   (`git show-ref --exclude-existing[=<pattern>]`)
-    # - {ShowRef::Exists} — boolean existence check without output (git >= 2.43)
+    # - {ShowRef::Exists} — boolean existence check without output
     #   (`git show-ref --exists <ref>`)
     #
     # @example List all refs matching a pattern

data/lib/git/commands/worktree/repair.rb

@@ -34,9 +34,6 @@ module Git
           operand :path, repeatable: true
         end
 
-        # git worktree repair was introduced in git 2.29.0
-        requires_git_version '2.29.0'
-
         # @!method call(*)
         #
         #   @overload call(*path, **options)
@@ -67,8 +64,6 @@ module Git
         #
         #     @raise [Git::FailedError] if git exits with a non-zero exit status
         #
-        #     @raise [Git::VersionError] if git version is below 2.29.0
-        #
         #     @api public
       end
     end

data/lib/git/diff_path_status.rb

@@ -72,7 +72,7 @@ module Git
 
     private
 
-    # Lazily fetches and caches the path status from the git lib
+    # Lazily fetches and caches the path status from the repository
     #
     # @return [Hash{String => String}] a mapping of file paths to status codes
     #

data/lib/git/encoding_utils.rb

@@ -48,6 +48,13 @@ module Git
 
     # Returns the given string converted to {Git::EncodingUtils.default_encoding}
     #
+    # When the string is not valid in its own encoding, the source encoding is
+    # taken from {Git::EncodingUtils.detected_encoding}. rchardet can name an
+    # encoding Ruby has no converter for (`UTF-7` and the two unusual-octet-order
+    # `UCS-4` forms, each assigned from a byte-order mark). In that case the
+    # invalid bytes are replaced with `String#scrub` instead, which keeps any
+    # valid multibyte sequences on the same line.
+    #
     # @param str [String] the string to normalize
     #
     # @return [String] the original or transcoded string in
@@ -59,6 +66,24 @@ module Git
       return str.encode(default_encoding, str.encoding, **encoding_options) if str.valid_encoding?
 
       str.encode(default_encoding, detected_encoding(str), **encoding_options)
+    rescue Encoding::ConverterNotFoundError
+      scrub_to_default_encoding(str)
+    end
+
+    # Returns the given string with its invalid bytes replaced, in
+    # {Git::EncodingUtils.default_encoding}
+    #
+    # `String#scrub` returns the string in its own encoding, so the result is
+    # transcoded afterward. On the gem's own call path the string is already
+    # tagged UTF-8 and that step is a no-op.
+    #
+    # @param str [String] the string to scrub
+    #
+    # @return [String] the scrubbed string in {Git::EncodingUtils.default_encoding}
+    #
+    def self.scrub_to_default_encoding(str)
+      str.scrub.encode(default_encoding, **encoding_options)
     end
+    private_class_method :scrub_to_default_encoding
   end
 end

data/lib/git/errors.rb

@@ -5,24 +5,22 @@ module Git
 
   # Base class for all custom git module errors
   #
-  # Errors the git gem raises deliberately are either `ArgumentError` or a subclass
-  # of `Git::Error`. The exceptions described below come from Ruby's standard
-  # library and are not converted.
-  #
-  # The gem's own filesystem operations, such as reading a `.git` pointer file,
-  # creating a temporary file, or changing directory, do not convert operating
-  # system errors. These can be raised as a bare `SystemCallError` (for example
-  # `Errno::ENOENT` or `Errno::EACCES`) rather than `Git::Error`. Gzip compression
-  # in `archive` can likewise raise a `Zlib::Error`. Rescue `SystemCallError` and
-  # `Zlib::Error` alongside `Git::Error` if your code needs to handle them. Any
-  # method that captures git output can also raise
-  # `Encoding::ConverterNotFoundError` when a line's detected encoding has no Ruby
-  # converter. See the "Errors raised by this gem" section of the README for the
-  # affected methods.
+  # The git gem will only raise an `ArgumentError` or an error that is a subclass of
+  # `Git::Error`.
   #
   # It is recommended to rescue `Git::Error` to catch any runtime error raised by
   # this gem unless you need more specific error handling.
   #
+  # Operating system errors from the gem's own filesystem operations, such as
+  # reading a `.git` pointer file or creating a temporary file, are raised as
+  # `Git::Error`. The original `SystemCallError` is available through `cause`.
+  #
+  # The promise covers errors the gem raises from its own operations. An error
+  # raised by a block your code passes to a method such as `chdir` propagates
+  # unchanged, and when `Git::Deprecation.behavior` is `:raise` a deprecated call
+  # raises `ActiveSupport::DeprecationException`, which is intentionally not a
+  # `Git::Error`.
+  #
   # Git's custom errors are arranged in the following class heirarchy:
   #
   # ```text
@@ -87,12 +85,20 @@ module Git
 
   # 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.
+  # Git::GitExecuteError is an alias for Git::Error kept for backwards
+  # compatibility. It is an ActiveSupport::Deprecation::DeprecatedConstantProxy,
+  # so any use of it, including instantiating it and matching it in a `rescue`
+  # clause, emits a deprecation warning through Git::Deprecation. The
+  # reflective methods that debuggers and IRB call, such as `inspect` and
+  # `name`, do not warn. It will be removed in a future major release.
   #
-  # @deprecated Use Git::Error instead
+  # @deprecated Use Git::Error instead. Will be removed in a future major release.
   #
-  GitExecuteError = ActiveSupport::Deprecation::DeprecatedConstantProxy.new('Git::GitExecuteError', 'Git::Error', Git::Deprecation)
+  GitExecuteError = ActiveSupport::Deprecation::DeprecatedConstantProxy.new(
+    'Git::GitExecuteError', 'Git::Error', Git::Deprecation,
+    message: 'Git::GitExecuteError is deprecated and will be removed in a future major release. ' \
+             'Use Git::Error instead.'
+  )
 
   # Raised when a git command fails or exits because of an uncaught signal
   #