git 1.19.1 → 5.5.0

data/git.gemspec

@@ -1,52 +1,140 @@
-$LOAD_PATH.unshift File.expand_path('../lib', __FILE__)
-require 'git/version'
-
-Gem::Specification.new do |s|
-  s.author = 'Scott Chacon and others'
-  s.email = 'schacon@gmail.com'
-  s.homepage = 'http://github.com/ruby-git/ruby-git'
-  s.license = 'MIT'
-  s.name = 'git'
-  s.summary = 'An API to create, read, and manipulate Git repositories'
-  s.description = <<~DESCRIPTION
+# frozen_string_literal: true
+
+# Read the version out of lib/git/version.rb rather than requiring it.
+#
+# The Gemfile uses `gemspec`, so Bundler evaluates this file on every `bundle exec`.
+# `require`ing lib/git/version.rb here would therefore load it before SimpleCov
+# starts in spec_helper, leaving it invisible to the coverage report -- an
+# unmeasured hole in the 100% coverage gate. See the "Test coverage policy" section
+# of CONTRIBUTING.md.
+#
+# release-please rewrites the `VERSION = '...'` assignment in place (see
+# `version-file` in .release-please-config.json), so matching on it stays correct
+# across releases. If the match ever fails, the raise below stops the build
+# immediately rather than letting a nil version reach the specification.
+version = File.read(File.expand_path('lib/git/version.rb', __dir__))[/^\s*VERSION\s*=\s*['"]([^'"]+)['"]/, 1]
+raise 'Could not determine Git::VERSION from lib/git/version.rb' if version.nil?
+
+Gem::Specification.new do |spec|
+  spec.author = 'Scott Chacon and others'
+  spec.email = 'schacon@gmail.com'
+  spec.homepage = 'http://github.com/ruby-git/ruby-git'
+  spec.license = 'MIT'
+  spec.name = 'git'
+  spec.summary = 'An API to create, read, and manipulate Git repositories'
+  spec.description = <<~DESCRIPTION
     The git gem provides an API that can be used to
     create, read, and manipulate Git repositories by wrapping system calls to the git
     command line. The API can be used for working with Git in complex interactions
     including branching and merging, object inspection and manipulation, history, patch
     generation and more.
   DESCRIPTION
-  s.version = Git::VERSION
+  spec.version = version
 
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = spec.homepage
+  spec.metadata['changelog_uri'] = "https://rubydoc.info/gems/#{spec.name}/#{spec.version}/file/CHANGELOG.md"
+  spec.metadata['documentation_uri'] = "https://rubydoc.info/gems/#{spec.name}/#{spec.version}"
+  spec.metadata['rubygems_mfa_required'] = 'true'
 
-  s.metadata['homepage_uri'] = s.homepage
-  s.metadata['source_code_uri'] = s.homepage
-  s.metadata['changelog_uri'] = "https://rubydoc.info/gems/#{s.name}/#{s.version}/file/CHANGELOG.md"
-  s.metadata['documentation_uri'] = "https://rubydoc.info/gems/#{s.name}/#{s.version}"
+  spec.require_paths = ['lib']
+  spec.required_ruby_version = '>= 3.2.0'
+  spec.requirements = ['git 2.28.0 or greater']
 
-  s.require_paths = ['lib']
-  s.required_ruby_version = '>= 2.3'
-  s.required_rubygems_version = Gem::Requirement.new('>= 0') if s.respond_to?(:required_rubygems_version=)
-  s.requirements = ['git 1.6.0.0, or greater']
+  spec.add_dependency 'activesupport', '>= 5.0'
+  spec.add_dependency 'addressable', '~> 2.8'
+  spec.add_dependency 'process_executer', '~> 4.1'
+  spec.add_dependency 'rchardet', '~> 1.9'
 
-  s.add_runtime_dependency 'addressable', '~> 2.8'
-  s.add_runtime_dependency 'rchardet', '~> 1.8'
+  # 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.
 
-  s.add_development_dependency 'bump', '~> 0.10'
-  s.add_development_dependency 'create_github_release', '~> 0.2'
-  s.add_development_dependency 'minitar', '~> 0.9'
-  s.add_development_dependency 'mocha', '~> 2.1'
-  s.add_development_dependency 'rake', '~> 13.0'
-  s.add_development_dependency 'test-unit', '~> 3.3'
+  # 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')
 
-  unless RUBY_PLATFORM == 'java'
-    s.add_development_dependency 'redcarpet', '~> 3.5'
-    s.add_development_dependency 'yard', '~> 0.9', '>= 0.9.28'
-    s.add_development_dependency 'yardstick', '~> 0.9'
-  end
+  # 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
 
   # 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.
-  s.files = Dir.chdir(File.expand_path(__dir__)) do
-    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(tests|spec|features|bin)/}) }
+  #
+  # 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
+  ]
+
+  # .yardopts drives the rubydoc.info build; the gemspec is included by convention.
+  build_files = %w[.yardopts git.gemspec]
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `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/author.rb

@@ -1,14 +1,46 @@
+# frozen_string_literal: true
+
 module Git
+  # An author in a Git commit
+  #
+  # @deprecated Use {Git::AuthorInfo} instead; this mutable class will be
+  #   removed in v6.0.0
+  #
+  # @api public
+  #
   class Author
-    attr_accessor :name, :email, :date
-    
+    # @return [String, nil] the author's name
+    attr_accessor :name
+
+    # @return [String, nil] the author's email
+    attr_accessor :email
+
+    # @return [Time, nil] the date the change was authored (author date, not committer date)
+    attr_accessor :date
+
+    # Initializes a new Author object from a string
+    #
+    # @example
+    #   Git::Author.new("John Doe <john.doe@example.com> 1627849923 +0200")
+    #
+    # @param author_string [String] the author string
+    #
+    # @return [void]
+    #
+    # @deprecated Use {Git::AuthorInfo.parse} instead
+    #
     def initialize(author_string)
-      if m = /(.*?) <(.*?)> (\d+) (.*)/.match(author_string)
-        @name = m[1]
-        @email = m[2]
-        @date = Time.at(m[3].to_i)
+      if defined?(Git::Deprecation)
+        Git::Deprecation.warn(
+          'Git::Author is deprecated and will be removed in v6.0.0. Use Git::AuthorInfo instead.'
+        )
       end
+
+      return unless (m = /(.*?) <(.*?)> (\d+) (.*)/.match(author_string))
+
+      @name = m[1]
+      @email = m[2]
+      @date = Time.at(m[3].to_i)
     end
-    
   end
 end

data/lib/git/author_info.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+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.
+  #
+  # @example Construct from individual values
+  #   info = Git::AuthorInfo.new(
+  #     name: 'John Doe',
+  #     email: 'john.doe@example.com',
+  #     date: Time.at(1627849923)
+  #   )
+  #   info.name  #=> 'John Doe'
+  #
+  # @example Parse from a raw git author string
+  #   info = Git::AuthorInfo.parse('John Doe <john.doe@example.com> 1627849923 +0200')
+  #   info.email     #=> 'john.doe@example.com'
+  #   info.date.to_i #=> 1627849923
+  #
+  # @see Git::Object::Commit#author
+  #
+  # @see Git::Object::Commit#committer
+  #
+  # @api public
+  #
+  # @!attribute [r] name
+  #   @return [String, nil] the person's name, or `nil` if not available
+  #
+  # @!attribute [r] email
+  #   @return [String, nil] the person's email address, or `nil` if not available
+  #
+  # @!attribute [r] date
+  #   @return [Time, nil] the timestamp of the change, or `nil` if not available
+  #
+  AuthorInfo = Data.define(:name, :email, :date) do
+    # Parses a raw git identity string into a Git::AuthorInfo
+    #
+    # The expected format is `"Name <email> timestamp offset"` as emitted by
+    # `git cat-file` for the `author`, `committer`, and `tagger` headers. The
+    # timestamp is interpreted as seconds since the Unix epoch; the timezone
+    # offset is not preserved in the resulting `date`.
+    #
+    # @example Parse a well-formed identity string
+    #   Git::AuthorInfo.parse('John Doe <john.doe@example.com> 1627849923 +0200')
+    #   #=> #<data Git::AuthorInfo name="John Doe", email="john.doe@example.com", ...>
+    #
+    # @example A string that does not match the expected format
+    #   Git::AuthorInfo.parse('garbage')
+    #   #=> #<data Git::AuthorInfo name=nil, email=nil, date=nil>
+    #
+    # @param author_string [String] the raw identity string to parse
+    #
+    # @return [Git::AuthorInfo] the parsed identity; all attributes are `nil`
+    #   when the string does not match the expected format
+    #
+    def self.parse(author_string)
+      match = /(.*?) <(.*?)> (\d+) (.*)/.match(author_string)
+      return new(name: nil, email: nil, date: nil) unless match
+
+      new(name: match[1], email: match[2], date: Time.at(match[3].to_i))
+    end
+  end
+end