git 5.1.0 → 5.3.0

data/UPGRADING.md

@@ -4,6 +4,7 @@ This document covers breaking changes and migration steps when upgrading the
 `git` gem to a new major version. Each section describes what changed and how
 to update your code when upgrading from the preceding major version.
 
+- [Upgrading to v6.0.0](#upgrading-to-v600)
 - [Upgrading to v5.x](#upgrading-to-v5x)
   - [Overview](#overview)
   - [Breaking changes](#breaking-changes)
@@ -17,6 +18,31 @@ to update your code when upgrading from the preceding major version.
     - [Facade method renames](#facade-method-renames)
     - [v4.x-style configuration methods](#v4x-style-configuration-methods)
     - [`Git` module mixin deprecations](#git-module-mixin-deprecations)
+    - [`Git::Author` deprecated](#gitauthor-deprecated)
+    - [`Git::Branch#stashes` deprecated](#gitbranchstashes-deprecated)
+    - [`Git::Repository#remotes` deprecated](#gitrepositoryremotes-deprecated)
+    - [`Git::Remote` deprecated](#gitremote-deprecated)
+    - [`Git::Commands::CatFile::Raw` `allow_unknown_type` option deprecated](#gitcommandscatfileraw-allow_unknown_type-option-deprecated)
+    - [`Git::Branch` and `Git::Branches` deprecated](#gitbranch-and-gitbranches-deprecated)
+
+## Upgrading to v6.0.0
+
+v6.0.0 is not yet released. This section will be completed when it ships.
+
+v6.0.0 removes the APIs deprecated during v5.x under the project's
+[deprecation policy](README.md#deprecation-policy).
+[Issue 1717](https://github.com/ruby-git/ruby-git/issues/1717) tracks its scope.
+
+To prepare:
+
+1. Upgrade to the latest v5.x release.
+2. Set `GIT_DEPRECATION_BEHAVIOR=raise` (or `Git::Deprecation.behavior = :raise`) in
+   your test suite and, if possible, staging.
+3. Fix each deprecation using the entries under
+   [Deprecated methods](#deprecated-methods) until the suite is clean.
+4. Upgrade to v6.0.0.
+
+---
 
 ## Upgrading to v5.x
 
@@ -240,7 +266,7 @@ shim cannot forward them). Update call sites directly:
 
 | v4.x call | Notes |
 |-----------|-------|
-| `g.lib.list_files(ref_dir)` | Walked `.git/refs/` directly. Use `g.branches`, `g.tags`, or `g.remotes` instead. |
+| `g.lib.list_files(ref_dir)` | Walked `.git/refs/` directly. Use `g.branch_list`, `g.tags`, or `g.remote_list` instead. |
 
 ##### Internal plumbing methods (no replacement)
 
@@ -362,4 +388,264 @@ as bare methods is deprecated:
 | `include Git; global_config(name, value)` | `Git.config_set(name, value, global: true)` |
 | `include Git; global_config` | `Git.config_list(global: true)` |
 
+#### `Git::Author` deprecated
+
+Starting in v5.3.0, methods that return author, committer, or tagger data —
+`Git::Object::Commit#author`, `Git::Object::Commit#committer`,
+`Git::Object::Tag#tagger`, and `Git::TagInfo#tagger` — return an immutable
+`Git::AuthorInfo` value object instead of the mutable `Git::Author`.
+
+`Git::AuthorInfo` exposes the same `name`, `email`, and `date` readers, so code
+that only reads these attributes needs no changes. Code that mutated a
+`Git::Author` (via `name=`, `email=`, or `date=`) must be updated:
+`Git::AuthorInfo` is frozen, and `#with` returns a modified copy rather than
+updating in place (e.g. `info = info.with(name: 'New Name')`).
+
+Constructing `Git::Author` directly emits a deprecation warning naming
+`Git::AuthorInfo` as the replacement. The class is removed in v6.0.0.
+
+| Deprecated usage | Replacement |
+|-----------------|-------------|
+| `Git::Author.new('Name <email> 1627849923 +0200')` | `Git::AuthorInfo.parse('Name <email> 1627849923 +0200')` |
+| `author.name = 'New Name'` | `author = author.with(name: 'New Name')` (returns a new object) |
+
+#### `Git::Branch#stashes` deprecated
+
+`Git::Branch#stashes` ignores the branch it is called on and returns every stash
+in the repository, so `g.branch('feature').stashes` and `g.branch('main').stashes`
+return the same entries. Call `Git::Repository#stashes_all` instead; it is the
+query `Git::Branch#stashes` was already running.
+
+> **Return type change:** `Git::Branch#stashes` returns a `Git::Stashes`
+> collection of `Git::Stash` objects, newest first. `g.stashes_all` returns an
+> array of `[index, message]` pairs, oldest first. Code that read `stash.message`
+> from each entry should read the second element of each pair instead. Code that
+> iterated or indexed the collection must reverse the order first, because
+> `Git::Stashes` yields and indexes newest first while `g.stashes_all` is oldest
+> first.
+
+`Git::Stashes` also exposes `save`, `apply`, and `clear`. Those map to the
+repository's `stash_save`, `stash_apply`, and `stash_clear`, which are not
+deprecated. `Git::Stashes#apply(i)` already passed `i` to git as `stash@{i}`
+(`0` = newest), and `g.stash_apply(i)` does the same, so that index needs no
+conversion.
+
+| Deprecated call (works in v5.x, removed in v6.0.0) | Replacement |
+|-----------------------------------------------------|-------------|
+| `g.branch(name).stashes` | `g.stashes_all` — returns `[[index, message], ...]` |
+| `g.branch(name).stashes.each { \|s\| puts s.message }` | `g.stashes_all.reverse_each { \|_index, message\| puts message }` |
+| `g.branch(name).stashes.all` | `g.stashes_all` |
+| `g.branch(name).stashes.size` | `g.stashes_all.size` |
+| `g.branch(name).stashes[i].message` (`0` = newest, `i` coerced with `to_i`) | `g.stashes_all.reverse[i.to_i][1]` |
+| `g.branch(name).stashes.save(message)` | `g.stash_save(message)` |
+| `g.branch(name).stashes.apply` | `g.stash_apply` |
+| `g.branch(name).stashes.apply(i)` (`0` = newest) | `g.stash_apply(i)` |
+| `g.branch(name).stashes.clear` | `g.stash_clear` |
+#### `Git::Repository#remotes` deprecated
+
+`Git::Repository#remotes` is deprecated in favor of `Git::Repository#remote_list`
+and is removed in v6.0.0. Its return value is unchanged. Calling `remotes` emits
+one deprecation warning for itself plus one `Git::Remote` constructor warning for
+each remote it returns (see the `Git::Remote` deprecation below), so a repository
+with N remotes produces N + 1 warnings per call.
+
+> **Return type change:** `remotes` returns `Array<Git::Remote>` — mutable
+> objects with `name`, `url`, and `fetch_opts` accessors and `fetch`, `merge`,
+> `branch`, and `remove` operations. `remote_list` returns
+> `Array<Git::RemoteInfo>` — immutable value objects read from the repository's
+> git config, with fields such as `name`, `url`, `push_url`, `fetch`, and `push`.
+> Because a remote may carry more than one URL or refspec, `url`, `push_url`,
+> `fetch`, and `push` are always frozen `Array<String>`. When a remote has more
+> than one URL, git fetches from the first; the legacy `Git::Remote#url` returned
+> the last one configured, so use `r.url.last` to reproduce that exact value.
+> Likewise, `Git::Remote#fetch_opts` returned only the last configured fetch
+> refspec, while `fetch` holds all of them. Operations that lived on
+> `Git::Remote` are called on the repository with the remote name instead.
+>
+> **Order change:** `remotes` lists remotes in the order `git remote` prints
+> them, while `remote_list` keeps the order in which remotes first appear in the
+> config. When the legacy order matters, iterate `g.remote_names` (the same
+> `git remote` order) or sort `g.remote_list` explicitly.
+
+| Deprecated call (works in v5.x, removed in v6.0.0) | Replacement |
+|-----------------------------------------------------|-------------|
+| `g.remotes` | `g.remote_list` — returns `Array<Git::RemoteInfo>` |
+| `g.remotes.map(&:name)` | `g.remote_list.map(&:name)` or `g.remote_names` |
+| `g.remotes.map(&:to_s)` | `g.remote_list.map(&:name)` — `Git::RemoteInfo#to_s` is not the name |
+| `g.remotes.map(&:url)` | `g.remote_list.map { \|r\| r.url.first }` — `url` is an `Array<String>` |
+| `g.remotes.map(&:fetch_opts)` | `g.remote_list.map { \|r\| r.fetch.last }` — `fetch` holds every refspec |
+| `g.remotes.each(&:fetch)` | `g.remote_names.each { \|name\| g.fetch(name) }` — same order as `remotes` |
+| `remote.fetch` | `g.fetch(remote.name)` |
+| `remote.fetch(opts)` | `g.fetch(remote.name, opts)` — same options hash |
+| `remote.merge` | `g.merge("#{remote.name}/#{g.current_branch}")` |
+| `remote.merge(branch)` | `g.merge("#{remote.name}/#{branch}")` |
+| `remote.branch` | `g.branch_list("#{remote.name}/#{g.current_branch}").first` — returns a `Git::BranchInfo` |
+| `remote.branch(name)` | `g.branch_list("#{remote.name}/#{name}").first` — returns a `Git::BranchInfo` |
+| `remote.remove` | `g.remote_remove(remote.name)` |
+
+#### `Git::Remote` deprecated
+
+`Git::Remote`, `Git::Repository#remote`, and `Git::Repository#config_remote` are
+deprecated and are removed in v6.0.0. Read a remote's configuration through
+`Git::Repository#remote_list`, which returns one `Git::RemoteInfo` value object per
+remote, and call the repository-level operations (`fetch`, `merge`, `branch_list`,
+`remote_remove`) with the remote name. Return values are unchanged. Constructing a
+`Git::Remote` directly emits one deprecation warning, and so does calling
+`g.config_remote`. Calling `g.remote` emits two: one for `Git::Repository#remote`
+and one for the `Git::Remote` it constructs. Likewise `g.remotes` emits one warning
+for itself plus one per `Git::Remote` it returns (N + 1 for N remotes). The extra
+warnings from `g.remote` and `g.remotes` are expected, not a bug.
+
+> **Return type changes:** `Git::RemoteInfo#url` and `Git::RemoteInfo#fetch` are
+> frozen `Array<String>` because a remote may carry more than one URL or fetch
+> refspec. The legacy `Git::Remote#url` and `Git::Remote#fetch_opts` returned only
+> the last configured value, so `r.url.last` and `r.fetch.last` reproduce them
+> exactly; `r.url.first` is the URL git actually fetches from.
+> `config_remote` returned a flat `Hash{String => String}` in which a repeated
+> `url` or `fetch` key overwrote the earlier value, so it could not report every
+> configured URL or refspec; `remote_list` keeps all of them. In the other
+> direction, `Git::RemoteInfo` models only the remote variables git defines and
+> drops any other `remote.<name>.*` key, while `config_remote` returned every key.
+> Code that reads custom keys should filter `g.config_list` instead (see the
+> table); that yields the same `Hash{String => String}` as `config_remote`.
+> `Git::Remote#branch` returned a `Git::Branch`. Its replacement,
+> `g.branch_list("#{name}/#{branch}").first`, returns a `Git::BranchInfo` value
+> object, or `nil` when the remote-tracking branch does not exist.
+
+In the table, `name` is the remote name (`g.remote` defaults it to `'origin'`).
+
+| Deprecated call (works in v5.x, removed in v6.0.0) | Replacement |
+|-----------------------------------------------------|-------------|
+| `g.remote` | `g.remote_list.find { \|r\| r.name == 'origin' }` — returns a `Git::RemoteInfo`; the deprecated call emits two warnings |
+| `g.remote(name)` | `g.remote_list.find { \|r\| r.name == name }` — returns a `Git::RemoteInfo`; the deprecated call emits two warnings |
+| `g.config_remote(name)` for `url`, `fetch`, and the other modeled fields | `g.remote_list.find { \|r\| r.name == name }` — a `Git::RemoteInfo`, not a `Hash` |
+| `g.config_remote(name)` for every key, including custom ones | `g.config_list.select { \|e\| e.key.start_with?("remote.#{name}.") }.to_h { \|e\| [e.key.delete_prefix("remote.#{name}."), e.value] }` — the same `Hash{String => String}` |
+| `remote.name`, `remote.to_s` | `g.remote_list.find { \|r\| r.name == name }.name` or `g.remote_names` |
+| `remote.url` | `g.remote_list.find { \|r\| r.name == name }.url` — `Array<String>`; `.first` for the single-URL case |
+| `remote.fetch_opts` | `g.remote_list.find { \|r\| r.name == name }.fetch` — `Array<String>` of refspecs |
+| `remote.fetch` | `g.fetch(name)` |
+| `remote.fetch(opts)` | `g.fetch(name, opts)` — same option keys |
+| `remote.merge` | `g.merge("#{name}/#{g.current_branch}")` |
+| `remote.merge(branch)` | `g.merge("#{name}/#{branch}")` |
+| `remote.branch` | `g.branch_list("#{name}/#{g.current_branch}").first` — returns a `Git::BranchInfo` |
+| `remote.branch(branch)` | `g.branch_list("#{name}/#{branch}").first` — returns a `Git::BranchInfo` |
+| `remote.remove` | `g.remote_remove(name)` |
+
+#### `Git::Commands::CatFile::Raw` `allow_unknown_type` option deprecated
+
+The `allow_unknown_type:` option of `Git::Commands::CatFile::Raw` is deprecated
+and is removed in v6.0.0. Passing it emits a deprecation warning; the
+`--allow-unknown-type` flag still reaches git unchanged until the option is
+removed.
+
+There is no replacement. Git 2.50 removed the unknown-type feature, so on git
+2.50 and later `--allow-unknown-type` is an accepted no-op and the option has no
+effect. On git 2.28 through 2.49 the flag still lets `t: true` and `s: true`
+report the type and size of an object whose type git does not recognize, but
+that behavior is dropped together with the option. The class is internal
+(`@api private`) and no `Git::Repository` method passes the option, so only code
+that constructs the command class directly is affected.
+
+| Deprecated call (works in v5.x, removed in v6.0.0) | Replacement |
+|-----------------------------------------------------|-------------|
+| `Git::Commands::CatFile::Raw.new(ctx).call(sha, t: true, allow_unknown_type: true)` | `Git::Commands::CatFile::Raw.new(ctx).call(sha, t: true)` |
+| `Git::Commands::CatFile::Raw.new(ctx).call(sha, s: true, allow_unknown_type: true)` | `Git::Commands::CatFile::Raw.new(ctx).call(sha, s: true)` |
+
+#### `Git::Branch` and `Git::Branches` deprecated
+
+`Git::Branch`, `Git::Branches`, `Git::Repository#branch`, and
+`Git::Repository#branches` are deprecated and are removed in v6.0.0. Read branch
+data through `Git::Repository#branch_list`, which returns one `Git::BranchInfo`
+value object per local and remote-tracking branch, and call the repository-level
+operations (`checkout`, `branch_new`, `branch_delete`, `merge`, `merge_into`,
+`in_branch`, and so on) with the branch name. Calling `g.branch` or `g.branches`,
+constructing a `Git::Branches`, and calling any operation on a `Git::Branch` each
+emit a deprecation warning; their return values are unchanged. The `full`,
+`name`, `remote`, `to_s`, and `to_a` readers on `Git::Branch` do not warn.
+
+> **Return shape change:** `Git::Branch` exposes `full` (`main` or
+> `remotes/origin/main`), `name`, and `remote` (a `Git::Remote`, or `nil`).
+> `Git::BranchInfo` exposes `refname` (always the full ref: `refs/heads/main` or
+> `refs/remotes/origin/main`), `short_name` (`main` for both), `remote_name` (a
+> `String`, or `nil`), `remote?`, `current?`, `target_oid`, `upstream`,
+> `worktree_path`, and `symref`. `Git::BranchInfo#to_s` is the full ref, not the
+> `remotes/origin/main` form `Git::Branch#to_s` returned. `branch_list` takes
+> `git branch --list` patterns: `'main'` matches the local branch and
+> `'origin/main'` matches the remote-tracking branch. The `remotes/origin/main`
+> and `refs/...` forms that `g.branches[...]` accepted match nothing.
+>
+> **`checkout` no longer creates the branch:** `g.branch('x').checkout` created
+> `x` when it did not exist, ignoring any error from that attempt, and then
+> checked it out. `g.checkout('x')` does not create a missing local branch,
+> with one exception that is git's own: when exactly one remote has a branch
+> named `x`, git creates a local tracking branch from it (its default guess
+> behavior). Otherwise the checkout fails. To reproduce create-or-checkout,
+> call `g.branch_new('x') unless g.local_branch?('x')` and then
+> `g.checkout('x')`. Use `g.checkout('x', new_branch: true)` only when `x` is
+> known not to exist; like `g.branch_new('x')`, it fails when `x` already
+> exists. Likewise `g.branch('x').create` ignored every error, while
+> `g.branch_new('x')` raises `Git::FailedError` when `x` already exists.
+>
+> **`in_branch` and `merge_into` differences:**
+>
+> 1. **Branch creation.** `g.branch('x').in_branch { ... }` created `x` if it did
+>    not exist. `g.in_branch('x') { ... }` raises `ArgumentError` unless `x` is an
+>    existing local branch, so call `g.branch_new('x')` first. A commit SHA, tag,
+>    or remote-tracking name is also rejected before any checkout.
+> 2. **Detached HEAD.** `Git::Branch#in_branch` recorded the literal `HEAD` and
+>    could not restore a detached HEAD to its original commit. `g.in_branch` and
+>    `g.merge_into` record the SHA and restore it.
+> 3. **Unborn HEAD.** Both new methods raise `Git::Error` before checking anything
+>    out when HEAD is on a branch with no commits. The old methods failed later,
+>    mid-flow.
+> 4. **Merge overload.** `g.branch('main').merge('feature')` returned stdout from
+>    the final restore checkout and ran a hard reset after the merge.
+>    `g.merge_into('main', 'feature')` returns the merge's stdout and does no
+>    reset. It also rejects the `:no_commit` option; callers who need
+>    `--no-commit` use `checkout` and `merge` directly.
+> 5. **Remote-tracking receivers.** Called on a remote-tracking `Git::Branch`,
+>    `in_branch` and `merge(branch)` checked out the remote-tracking ref,
+>    detaching HEAD, and any commit made there was left dangling. `g.in_branch`
+>    and `g.merge_into` take an existing local branch only. Create one from the
+>    remote-tracking ref first, with
+>    `g.branch_new(name, "remotes/#{remote}/#{name}")`, and pass that branch.
+
+In the table, `name` is the branch name (`g.branch` defaults it to the current
+branch), `remote` is the remote name of a remote-tracking branch, `b` is a
+`Git::Branch`, and `info` is the `Git::BranchInfo` that replaces it. Where a
+row says to pass `info.refname` for a remote-tracking branch, `b.full` (the
+`remotes/<remote>/<name>` form) works too; the shorter `"#{remote}/#{name}"`
+can resolve a local branch of that name and is only used where git expects it
+(`branch_delete` with `remotes: true`).
+
+| Deprecated call (works in v5.x, removed in v6.0.0) | Replacement |
+|-----------------------------------------------------|-------------|
+| `g.branch(name)` | `g.branch_list(name).first` for a local branch, or `g.branch_list("#{remote}/#{name}").find(&:remote?)` for a remote-tracking one — a `Git::BranchInfo`, or `nil` when the branch does not exist; the `remotes/` and `refs/` forms match nothing |
+| `g.branch` | `g.branch_list(g.current_branch).first` — `nil` when HEAD is detached or unborn; use `g.current_branch_state` there |
+| `g.branches` | `g.branch_list` — returns `Array<Git::BranchInfo>` |
+| `g.branches[name]` | `g.branch_list(name).first`, or `g.branch_list("#{remote}/#{name}").find(&:remote?)` for a remote-tracking branch |
+| `g.branches.local` | `g.branch_list.reject(&:remote?)` |
+| `g.branches.remote` | `g.branch_list.select(&:remote?)` |
+| `g.branches.size` | `g.branch_list.size` |
+| `g.branches.each { \|b\| ... }` | `g.branch_list.each { \|info\| ... }` |
+| `g.branches.to_s` | `g.branch_list.map { \|i\| "#{i.current? ? '* ' : '  '}#{i.refname}\n" }.join` — full refs, not `remotes/...` |
+| `b.full`, `b.to_s` | `info.refname` — `refs/remotes/origin/main` rather than `remotes/origin/main` |
+| `b.to_a` | `[info.refname]` |
+| `b.name` | `info.short_name` |
+| `b.remote` | `info.remote_name` — a `String`, or `nil` for a local branch |
+| `b.gcommit` | `g.gcommit(name)` — pass `info.refname` for a remote-tracking branch |
+| `b.checkout` | `g.checkout(name)` — does not create the branch (see above); pass `info.refname` for a remote-tracking branch |
+| `b.create` | `g.branch_new(name)` — raises when the branch already exists |
+| `b.delete` (local) | `g.branch_delete(name)` |
+| `b.delete` (remote-tracking) | `g.branch_delete("#{remote}/#{name}", remotes: true)` |
+| `b.current` | `g.current_branch == name` |
+| `b.contains?(commit)` | `!g.branch_contains(commit, name).empty?` |
+| `b.merge` | `g.merge(name)` |
+| `b.merge(branch, message)` | `g.merge_into(name, branch, message)` — local `b` only; see the differences above |
+| `b.update_ref(commit)` (local) | `g.update_ref(name, commit)` |
+| `b.update_ref(commit)` (remote-tracking) | `g.update_ref("remotes/#{remote}/#{name}", commit)` |
+| `b.archive(file, opts)` | `g.archive(name, file, opts)` — pass `info.refname` for a remote-tracking branch |
+| `b.in_branch(message) { ... }` | `g.in_branch(name, message) { ... }` — local `b` only; see the differences above |
+| `b.stashes` | `g.stashes_all` — see [`Git::Branch#stashes` deprecated](#gitbranchstashes-deprecated) |
+
 ---

data/git.gemspec

@@ -43,7 +43,7 @@ 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
@@ -101,8 +101,40 @@ Gem::Specification.new do |spec|
   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.
+  #
+  # 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").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/author.rb

@@ -3,6 +3,9 @@
 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
@@ -24,7 +27,15 @@ module Git
     #
     # @return [void]
     #
+    # @deprecated Use {Git::AuthorInfo.parse} instead
+    #
     def initialize(author_string)
+      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]

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