git 5.0.5 → 5.2.0

data/git.gemspec

@@ -43,38 +43,98 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency 'activesupport', '>= 5.0'
   spec.add_dependency 'addressable', '~> 2.8'
-  spec.add_dependency 'process_executer', '~> 4.0'
+  spec.add_dependency 'process_executer', '~> 4.1'
   spec.add_dependency 'rchardet', '~> 1.9'
 
+  # Not every development dependency is installed on every runtime. Each predicate
+  # below names one reason for holding a gem back, which keeps the dependency list
+  # itself a flat, readable list. Deriving one predicate from another also keeps
+  # coupled gems from drifting apart when a condition changes.
+  #
+  # These are local variables rather than methods deliberately. The Gemfile uses
+  # `gemspec`, so Bundler evaluates this file on every `bundle exec`, and a top-level
+  # `def` -- including one written inside this block, since a block is not a definition
+  # scope -- would define a private method on Object in every one of those processes.
+
+  # JRuby (which reports RUBY_PLATFORM as 'java') and TruffleRuby build no C extensions
+  # and do not run the docs build.
+  mri = !(RUBY_PLATFORM == 'java' || RUBY_ENGINE == 'truffleruby')
+
+  # irb stopped being a default gem in Ruby 3.4. JRuby and TruffleRuby ship their own.
+  install_irb = mri
+
+  # Ruby 4.0.0 dropped fiddle from the default gems. On Windows, irb loads
+  # reline/io/windows.rb, which requires fiddle/import for the Win32 console API, so
+  # bin/console cannot start without it; every other platform takes reline's ANSI IO
+  # gate and never loads that file. Derived from install_irb because fiddle exists only
+  # to serve irb and, being a C extension, could not install where irb is not.
+  install_fiddle = install_irb && Gem.win_platform?
+
+  # The docs toolchain is supported on MRI only. redcarpet, YARD's Markdown renderer,
+  # 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' &&
+                 Gem::Version.new(RUBY_ENGINE_VERSION) < Gem::Version.new('34.0.0')
+
   spec.add_development_dependency 'create_github_release', '~> 2.1'
+  spec.add_development_dependency 'fiddle', '~> 1.1' if install_fiddle
   spec.add_development_dependency 'fuubar', '~> 2.5'
+  spec.add_development_dependency 'i18n', '< 1.15' if pin_old_i18n
+  spec.add_development_dependency 'irb', '~> 1.16' if install_irb
   spec.add_development_dependency 'main_branch_shared_rubocop_config', '~> 0.1'
   spec.add_development_dependency 'parallel_tests', '~> 5.6'
   spec.add_development_dependency 'rake', '~> 13.3'
+  spec.add_development_dependency 'redcarpet', '~> 3.6' if install_docs
   spec.add_development_dependency 'rspec', '~> 3.13'
   spec.add_development_dependency 'rubocop', '~> 1.82'
   spec.add_development_dependency 'simplecov', '~> 1.0'
   spec.add_development_dependency 'simplecov-lcov', '~> 0.9'
   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
 
-  if RUBY_ENGINE == 'truffleruby' && Gem::Version.new(RUBY_ENGINE_VERSION) < Gem::Version.new('34.0.0')
-    # i18n 1.15+ uses Fiber.[] (Ruby 3.2 Fiber storage) which TruffleRuby < 34.0.0 does not implement
-    spec.add_development_dependency 'i18n', '< 1.15'
-  end
-
-  unless RUBY_PLATFORM == 'java' || RUBY_ENGINE == 'truffleruby'
-    spec.add_development_dependency 'irb', '~> 1.16'
-    spec.add_development_dependency 'redcarpet', '~> 3.6'
-    spec.add_development_dependency 'yard', '~> 0.9', '>= 0.9.28'
-    spec.add_development_dependency 'yard_example_test', '~> 0.2', '>= 0.2.1'
+  # Specify which files should be added to the gem when it is released.
+  #
+  # This is an allowlist rather than a denylist. A denylist admitted every new
+  # development-only path by default, so the gem shipped `.github/`, `tasks/`, the
+  # husky hooks, and -- the reason this became an allowlist -- the `.claude/skills`
+  # symlink. Extracting a symlink needs a privilege that Windows grants only under
+  # Developer Mode or an elevated shell, so installing the gem there either failed
+  # outright or, on RubyGems new enough to fall back to a copy, silently duplicated
+  # the whole skills tree into the installed gem.
+  #
+  # spec/unit/gemspec_spec.rb guards both directions: nothing in the list may be a
+  # symlink, and every tracked file under lib/ must be present, so the allowlist
+  # cannot quietly drop runtime code.
+  #
+  # doc_files must stay in sync with the extra files named in .yardopts -- those are
+  # what rubydoc.info renders for the published documentation, so a file listed there
+  # but absent from the gem becomes a broken link.
+  doc_files = %w[
+    AI_POLICY.md
+    CHANGELOG.md
+    CODE_OF_CONDUCT.md
+    CONTRIBUTING.md
+    GOVERNANCE.md
+    LICENSE
+    MAINTAINERS.md
+    README.md
+    UPGRADING.md
+  ]
 
-    # yard-lint requires Ruby >= 3.3, so it is only installed on Ruby 3.3+.
-    spec.add_development_dependency 'yard-lint', '~> 1.8' if Gem.ruby_version >= Gem::Version.new('3.3.0')
-  end
+  # .yardopts drives the rubydoc.info build; the gemspec is included by convention.
+  build_files = %w[.yardopts git.gemspec]
 
-  # Specify which files should be added to the gem when it is released.
-  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
   spec.files = Dir.chdir(File.expand_path(__dir__)) do
-    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(tests|spec|features|bin)/}) }
+    `git ls-files -z`.split("\x0").select do |f|
+      f.start_with?('lib/') || doc_files.include?(f) || build_files.include?(f)
+    end
   end
 end

data/lib/git/command_line/base.rb

@@ -232,7 +232,7 @@ module Git
       #
       # @api private
       #
-      # rubocop:disable Metrics/ParameterLists
+      # rubocop:disable-next Metrics/ParameterLists
       def command_line_result(command, result, processed_out, processed_err, timeout, raise_on_failure)
         Git::CommandLine::Result.new(command, result, processed_out, processed_err).tap do |processed_result|
           raise Git::TimeoutError.new(processed_result, timeout) if result.timed_out?
@@ -242,7 +242,6 @@ module Git
           raise Git::FailedError, processed_result if raise_on_failure && !result.success?
         end
       end
-      # rubocop:enable Metrics/ParameterLists
     end
   end
 end

data/lib/git/commands/base.rb

@@ -453,7 +453,7 @@ module Git
       #
       # @example Feed bound object names to a git batch command
       #   bound = args_definition.bind(*args, **kwargs)
-      #   stdin_content = Array(bound.objects).map { |object| "#{object}\n" }.join
+      #   stdin_content = Array(bound.object).map { |object| "#{object}\n" }.join
       #   with_stdin(stdin_content) do |reader|
       #     @execution_context.command_capturing('cat-file', '--batch-check', in: reader, raise_on_failure: false)
       #   end

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

@@ -49,9 +49,10 @@ 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;
-          # rejected by git in any other mode — enforced by constraint below
-          # See https://git-scm.com/docs/git-cat-file#Documentation/git-cat-file.txt---allow-unknown-type
+          # Allow -t and -s to query broken or corrupt objects of unknown type.
+          # Git 2.28-2.49 rejects this flag in other modes; git 2.50+ accepts and
+          # ignores it everywhere (the unknown-type feature was removed; see issue 1709).
+          # 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
@@ -74,8 +75,6 @@ module Git
 
           # Object name: SHA, ref, `HEAD`, treeish path reference, etc.
           operand :object, required: true
-
-          requires_one_of :t, :s, when: :allow_unknown_type
         end
 
         # Execute `git cat-file` for a single object.
@@ -114,7 +113,8 @@ module Git
         #   @param options [Hash] command options
         #
         #   @option options [Boolean, nil] :allow_unknown_type (nil) allow querying broken or corrupt objects of
-        #     unknown type
+        #     unknown type on git 2.28-2.49; 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`)
         #
@@ -138,7 +138,8 @@ module Git
         #   @param options [Hash] command options
         #
         #   @option options [Boolean, nil] :allow_unknown_type (nil) allow querying broken or corrupt objects of
-        #     unknown type
+        #     unknown type on git 2.28-2.49; 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`)
         #

data/lib/git/configuring.rb

@@ -88,6 +88,14 @@ module Git
     #
     # @raise [Git::FailedError] if git exits with an unexpected non-zero status
     #
+    # @note On Git for Windows, git's default regex engine matches *bytes* rather than
+    #   characters, so a metacharacter such as `.` or a POSIX class such as
+    #   `[[:alpha:]]` in `value_regex` never matches a whole multi-byte character. The
+    #   failure is silent: nothing raises, and the outcome is indistinguishable from a
+    #   `value_regex` that genuinely matches nothing. `git config` value patterns are
+    #   POSIX extended regular expressions with no PCRE mode, so unlike
+    #   {Git::Repository#grep} there is no alternate regex engine to select here.
+    #
     def config_get(name, value_regex = nil, **options)
       Private.assert_valid_opts!(CONFIG_GET_ALLOWED_OPTS, **options)
       assert_valid_scope!(**options)
@@ -139,6 +147,14 @@ module Git
     #
     # @raise [Git::FailedError] if git exits with an unexpected non-zero status
     #
+    # @note On Git for Windows, git's default regex engine matches *bytes* rather than
+    #   characters, so a metacharacter such as `.` or a POSIX class such as
+    #   `[[:alpha:]]` in `value_regex` never matches a whole multi-byte character. The
+    #   failure is silent: nothing raises, and the outcome is indistinguishable from a
+    #   `value_regex` that genuinely matches nothing. `git config` value patterns are
+    #   POSIX extended regular expressions with no PCRE mode, so unlike
+    #   {Git::Repository#grep} there is no alternate regex engine to select here.
+    #
     def config_get_all(name, value_regex = nil, **options)
       Private.assert_valid_opts!(CONFIG_GET_ALL_ALLOWED_OPTS, **options)
       assert_valid_scope!(**options)
@@ -238,6 +254,14 @@ module Git
     #
     # @raise [Git::FailedError] if git exits with an unexpected non-zero status
     #
+    # @note On Git for Windows, git's default regex engine matches *bytes* rather than
+    #   characters, so a metacharacter such as `.` or a POSIX class such as
+    #   `[[:alpha:]]` in `value_regex` never matches a whole multi-byte character. The
+    #   failure is silent: nothing raises, and the outcome is indistinguishable from a
+    #   `value_regex` that genuinely matches nothing. `git config` value patterns are
+    #   POSIX extended regular expressions with no PCRE mode, so unlike
+    #   {Git::Repository#grep} there is no alternate regex engine to select here.
+    #
     def config_get_regexp(name_regex, value_regex = nil, **options)
       Private.assert_valid_opts!(CONFIG_GET_REGEXP_ALLOWED_OPTS, **options)
       assert_valid_scope!(**options)
@@ -529,6 +553,22 @@ module Git
     #
     #   @raise [Git::FailedError] if git exits with a non-zero exit status
     #
+    # @note On Git for Windows, git's default regex engine matches *bytes* rather than
+    #   characters, so a metacharacter such as `.` or a POSIX class such as
+    #   `[[:alpha:]]` in `value_regex` never matches a whole multi-byte character. The
+    #   failure is silent: nothing raises, and the outcome is indistinguishable from a
+    #   `value_regex` that genuinely matches nothing. `git config` value patterns are
+    #   POSIX extended regular expressions with no PCRE mode, so unlike
+    #   {Git::Repository#grep} there is no alternate regex engine to select here.
+    #
+    # @note A `value_regex` that selects nothing does not make this method a no-op.
+    #   `git config --replace-all` *adds* `value` as an additional entry when no
+    #   existing value matches, and exits zero. On Git for Windows, a `value_regex`
+    #   whose metacharacters span non-ASCII text therefore leaves the value it was
+    #   meant to replace in place and silently creates a duplicate entry beside it.
+    #   Confirm the result with {#config_get_all}, or match on ASCII text, when the
+    #   key must end up single-valued.
+    #
     def config_replace_all(name, value, value_regex = nil, **)
       Private.assert_valid_opts!(CONFIG_REPLACE_ALL_ALLOWED_OPTS, **)
       assert_valid_scope!(**)
@@ -621,6 +661,14 @@ module Git
     #
     #   @raise [Git::FailedError] if git exits with a non-zero exit status
     #
+    # @note On Git for Windows, git's default regex engine matches *bytes* rather than
+    #   characters, so a metacharacter such as `.` or a POSIX class such as
+    #   `[[:alpha:]]` in `value_regex` never matches a whole multi-byte character. The
+    #   failure is silent: nothing raises, and the outcome is indistinguishable from a
+    #   `value_regex` that genuinely matches nothing. `git config` value patterns are
+    #   POSIX extended regular expressions with no PCRE mode, so unlike
+    #   {Git::Repository#grep} there is no alternate regex engine to select here.
+    #
     def config_unset(name, value_regex = nil, **)
       Private.assert_valid_opts!(CONFIG_UNSET_ALLOWED_OPTS, **)
       assert_valid_scope!(**)
@@ -666,6 +714,14 @@ module Git
     #
     #   @raise [Git::FailedError] if git exits with a non-zero exit status
     #
+    # @note On Git for Windows, git's default regex engine matches *bytes* rather than
+    #   characters, so a metacharacter such as `.` or a POSIX class such as
+    #   `[[:alpha:]]` in `value_regex` never matches a whole multi-byte character. The
+    #   failure is silent: nothing raises, and the outcome is indistinguishable from a
+    #   `value_regex` that genuinely matches nothing. `git config` value patterns are
+    #   POSIX extended regular expressions with no PCRE mode, so unlike
+    #   {Git::Repository#grep} there is no alternate regex engine to select here.
+    #
     def config_unset_all(name, value_regex = nil, **)
       Private.assert_valid_opts!(CONFIG_UNSET_ALL_ALLOWED_OPTS, **)
       assert_valid_scope!(**)

data/lib/git/log.rb

@@ -142,6 +142,25 @@ module Git
     #
     def grep(regex)         = set_option(:grep, regex)
 
+    # Interprets {#grep} and {#author} patterns as Perl-compatible regular expressions
+    #
+    # Selects PCRE instead of git's default POSIX basic regular expressions for
+    # every pattern in the query. Requires a git built with PCRE support.
+    #
+    # @example Match a metacharacter against a non-ASCII character on Git for Windows
+    #   repo.log.perl_regexp.grep('^.PFEL').execute
+    #
+    # @return [Git::Log] the current query builder
+    #
+    # @note On Git for Windows, git's default regex engine matches *bytes* rather
+    #   than characters, so a metacharacter such as `.` or a POSIX class such as
+    #   `[[:alpha:]]` never matches a whole multi-byte character. The match fails
+    #   silently: git exits zero and the result is empty. PCRE does match characters
+    #   on that platform, but it is a different dialect than git's default, so
+    #   selecting it is a deliberate choice by the caller.
+    #
+    def perl_regexp         = set_option(:perl_regexp, true)
+
     # Limits commits to those that touch the given path or paths
     #
     # @param path [String, Pathname, Array<String, Pathname>] path limiter input

data/lib/git/repository/branching.rb

@@ -41,7 +41,7 @@ module Git
 
       # Option keys accepted by {#checkout}
       #
-      CHECKOUT_ALLOWED_OPTS = %i[force f new_branch b start_point].freeze
+      CHECKOUT_ALLOWED_OPTS = %i[force f new_branch b start_point orphan].freeze
       private_constant :CHECKOUT_ALLOWED_OPTS
 
       # Option keys accepted by {#checkout_index}
@@ -130,6 +130,9 @@ module Git
       # @example Create a new branch with a name different from the start point
       #   repo.checkout('main', new_branch: 'new-feature')
       #
+      # @example Create and check out an unborn branch with no history
+      #   repo.checkout('gh-pages', orphan: true)
+      #
       # @example Force checkout discarding local changes
       #   repo.checkout('main', force: true)
       #
@@ -151,13 +154,25 @@ module Git
       #
       # @option opts [Boolean, nil] :f (nil) alias for `:force`
       #
+      # @option opts [Boolean, String, nil] :orphan (nil) when `true`, creates a
+      #   new unborn branch named `branch` whose first commit has no parents
+      #
+      #   When a `String`, creates an unborn branch with that name, using
+      #   `branch` as the start point for the working tree and index.
+      #
+      #   `false` and `nil` are both treated as unset. A blank branch name is
+      #   rejected rather than ignored.
+      #
       # @option opts [String, nil] :start_point (nil) the commit or branch to
-      #   start the new branch from; used together with `new_branch: true`
+      #   start the new branch from; used together with `new_branch: true` or
+      #   `orphan: true`
       #
       # @return [String] git's stdout from the checkout
       #
       # @raise [ArgumentError] if unsupported options are provided
       #
+      # @raise [ArgumentError] if `:orphan` is given a blank or missing branch name
+      #
       # @raise [Git::FailedError] if git exits with a non-zero exit status
       #
       def checkout(branch = nil, opts = {})
@@ -680,19 +695,24 @@ module Git
           :unborn
         end
 
-        # Translates legacy checkout options to the new command interface
+        # Translates {#checkout} options to the new command interface
         #
         # Legacy callers passed combinations like:
         #   checkout('branch', new_branch: true, start_point: 'main')
         # which should map to:
         #   checkout('main', b: 'branch')
         #
+        # `orphan: true` follows the same shape, naming the unborn branch:
+        #   checkout('branch', orphan: true, start_point: 'main')
+        # maps to:
+        #   checkout('main', orphan: 'branch')
+        #
         # @param branch [String, nil] the branch argument passed to {#checkout}
         #
         # @param checkout_options [Hash] the raw options passed to {#checkout}
         #
-        # @return [Array] a two-element tuple `[target, options]` containing the
-        #   translated checkout arguments
+        # @return [Array((String, nil), Hash)] a two-element tuple
+        #   `[target, options]` containing the translated checkout arguments
         #
         #   `target` (`String` or `nil`) is the branch or commit to check out.
         #   `options` is a `Hash` of keyword arguments for
@@ -701,15 +721,69 @@ module Git
         # @api private
         #
         def translate_checkout_opts(branch, checkout_options)
+          checkout_options = normalize_orphan_option(checkout_options)
+
           if checkout_options[:new_branch] == true || checkout_options[:b] == true
             [checkout_options[:start_point], checkout_options.except(:new_branch, :b, :start_point).merge(b: branch)]
           elsif checkout_options[:new_branch].is_a?(String)
             [branch, checkout_options.except(:new_branch).merge(b: checkout_options[:new_branch])]
+          elsif checkout_options[:orphan] == true
+            translate_orphan_opts(branch, checkout_options)
           else
             [branch, checkout_options]
           end
         end
 
+        # Normalizes the `:orphan` option, rejecting names that git would never see
+        #
+        # `:orphan` is a value option on the underlying command, so a literal
+        # `false` would be emitted as `--orphan false` and create a branch named
+        # "false". Flag options such as `:force` already ignore `false`; this
+        # gives `:orphan` the same behavior.
+        #
+        # A blank name is rejected rather than dropped: the argument DSL omits
+        # empty values, so `orphan: ''` would otherwise degrade silently into a
+        # plain checkout.
+        #
+        # @param checkout_options [Hash] the raw options passed to {#checkout}
+        #
+        # @return [Hash] the options with a `false` `:orphan` key removed
+        #
+        # @raise [ArgumentError] if `:orphan` is given a blank branch name
+        #
+        # @api private
+        #
+        def normalize_orphan_option(checkout_options)
+          orphan = checkout_options[:orphan]
+          return checkout_options.except(:orphan) if orphan == false
+          raise ArgumentError, 'orphan requires a non-empty branch name' if orphan.is_a?(String) && orphan.strip.empty?
+
+          checkout_options
+        end
+
+        # Translates `orphan: true` into the command's `:orphan` value option
+        #
+        # `orphan: true` names the unborn branch from the positional argument and
+        # takes its start point from `:start_point`, mirroring `new_branch: true`.
+        #
+        # @param branch [String, nil] the branch argument passed to {#checkout}
+        #
+        # @param checkout_options [Hash] the raw options passed to {#checkout}
+        #
+        # @return [Array((String, nil), Hash)] a two-element tuple
+        #   `[target, options]` containing the translated checkout arguments
+        #
+        # @raise [ArgumentError] if `branch` is blank (`nil`, empty, or whitespace
+        #   only), since the unborn branch would otherwise have no name
+        #
+        # @api private
+        #
+        def translate_orphan_opts(branch, checkout_options)
+          raise ArgumentError, 'orphan: true requires a branch name' if branch.to_s.strip.empty?
+
+          [checkout_options[:start_point], checkout_options.except(:start_point).merge(orphan: branch)]
+        end
+
         # Normalizes path specifications for Git commands
         #
         # @param pathspecs [String, Pathname, Array<String, Pathname>, nil]

data/lib/git/repository/logging.rb

@@ -18,7 +18,7 @@ module Git
       # @return [Array<Symbol>] the supported option keys
       #
       FULL_LOG_COMMITS_ALLOWED_OPTS = %i[
-        count all cherry since until grep author between object path_limiter skip merges
+        count all cherry since until grep author between object path_limiter skip merges perl_regexp
       ].freeze
       private_constant :FULL_LOG_COMMITS_ALLOWED_OPTS
 
@@ -68,6 +68,13 @@ module Git
       #
       # @option opts [Boolean, nil] :merges (nil) include only merge commits
       #
+      # @option opts [Boolean, nil] :perl_regexp (nil) interpret the `:grep` and
+      #   `:author` patterns as Perl-compatible regular expressions (PCRE) instead of
+      #   git's default POSIX basic regular expressions
+      #
+      #   Requires a git built with PCRE support; git otherwise fails with
+      #   "cannot use Perl-compatible regexes...".
+      #
       # @return [Array<Hash>] the parsed raw log output for each commit
       #
       # @raise [ArgumentError] if unsupported options are provided
@@ -76,6 +83,14 @@ module Git
       #
       # @raise [Git::FailedError] if git exits with a non-zero exit status
       #
+      # @note On Git for Windows, git's default regex engine matches *bytes* rather
+      #   than characters, so a metacharacter such as `.` or a POSIX class such as
+      #   `[[:alpha:]]` never matches a whole multi-byte character in a `:grep` or
+      #   `:author` pattern. The match fails silently: git exits zero and the result
+      #   is empty. Pass `perl_regexp: true` to select PCRE, which does match
+      #   characters. PCRE is a different dialect than git's default, so this is a
+      #   deliberate choice by the caller rather than a transparent substitution.
+      #
       # @see https://git-scm.com/docs/git-log git-log
       #
       def full_log_commits(opts = {})
@@ -113,6 +128,14 @@ module Git
       module Private
         module_function
 
+        # Log option keys forwarded to {Git::Commands::Log#call} under the same name
+        #
+        # The remaining options are renamed or reshaped by {#log_base_call_options}.
+        #
+        # @return [Array<Symbol>] the pass-through option keys
+        #
+        PASSTHROUGH_LOG_OPTS = %i[all cherry since until grep author perl_regexp].freeze
+
         # Validates the :count log option
         #
         # @param opts [Hash] the log options
@@ -195,6 +218,9 @@ module Git
         # @option opts [String, nil] :author (nil) only include commits whose author
         #   matches this pattern
         #
+        # @option opts [Boolean, nil] :perl_regexp (nil) interpret the `:grep` and
+        #   `:author` patterns as Perl-compatible regular expressions
+        #
         # @option opts [Integer, nil] :count (nil) maximum number of commits to return
         #
         # @option opts [String, Pathname, Array<String, Pathname>, nil] :path_limiter (nil)
@@ -207,16 +233,14 @@ module Git
         # @return [Hash] keyword options for {Git::Commands::Log#call}
         #
         def log_base_call_options(opts, extra = {})
-          {
-            all: opts[:all],
-            cherry: opts[:cherry],
-            since: opts[:since],
-            until: opts[:until],
-            grep: opts[:grep],
-            author: opts[:author],
-            max_count: opts[:count],
-            path: opts[:path_limiter] ? Array(opts[:path_limiter]) : nil
-          }.merge(extra).compact
+          opts
+            .slice(*PASSTHROUGH_LOG_OPTS)
+            .merge(
+              max_count: opts[:count],
+              path: opts[:path_limiter] ? Array(opts[:path_limiter]) : nil
+            )
+            .merge(extra)
+            .compact
         end
 
         # Executes git log and parses the raw output

data/lib/git/repository/object_operations.rb

@@ -454,7 +454,7 @@ module Git
       end
 
       # Option keys accepted by {#grep}
-      GREP_ALLOWED_OPTS = %i[ignore_case i invert_match v extended_regexp E object].freeze
+      GREP_ALLOWED_OPTS = %i[ignore_case i invert_match v extended_regexp E perl_regexp P object].freeze
       private_constant :GREP_ALLOWED_OPTS
 
       # Search tracked file contents in a git tree for a pattern
@@ -475,6 +475,9 @@ module Git
       # @example Case-insensitive search
       #   repo.grep('todo', nil, ignore_case: true)
       #
+      # @example Match a metacharacter against a non-ASCII character on Git for Windows
+      #   repo.grep('^.PFEL', nil, perl_regexp: true)
+      #
       # @param pattern [String] the pattern to search for
       #
       # @param path_limiter [String, Pathname, Array<String, Pathname>, nil]
@@ -499,6 +502,14 @@ module Git
       #
       #   Alias: :E
       #
+      # @option opts [Boolean, nil] :perl_regexp (nil) use Perl-compatible regular
+      #   expressions (PCRE) for the pattern
+      #
+      #   Requires a git built with PCRE support; git otherwise fails with
+      #   "cannot use Perl-compatible regexes...".
+      #
+      #   Alias: :P
+      #
       # @return [Hash<String, Array<Array(Integer, String)>>] a hash mapping
       #   each `"treeish:filename"` key to an array of `[line_number, text]`
       #   pairs; returns an empty hash when no lines match
@@ -508,6 +519,16 @@ module Git
       # @raise [Git::FailedError] if git exits with a non-zero status and
       #   stderr is non-empty (e.g. bad object reference)
       #
+      # @note On Git for Windows, git's default regex engine matches *bytes* rather
+      #   than characters, so a metacharacter such as `.` or a POSIX class such as
+      #   `[[:alpha:]]` never matches a whole multi-byte character. The failure is
+      #   silent: nothing raises, and the empty hash returned is indistinguishable
+      #   from a pattern that genuinely does not occur in the tree. Pass
+      #   `perl_regexp: true` to select PCRE, which does match characters. PCRE is a
+      #   different dialect than git's default POSIX basic/extended regular
+      #   expressions, so this is a deliberate choice by the caller rather than a
+      #   transparent substitution, and it requires a git built with PCRE support.
+      #
       # @see https://git-scm.com/docs/git-grep git-grep documentation
       #
       def grep(pattern, path_limiter = nil, opts = {})

data/lib/git/version.rb

@@ -4,7 +4,7 @@ module Git
   # The current gem version
   #
   # @return [String] the current gem version
-  VERSION = '5.0.5'
+  VERSION = '5.2.0'
 
   # Represents a git version with major, minor, and patch components
   #