git 5.2.0 → 5.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0046556c3068d7b41423d2f0ce69631d5f5818ce279e410797c44c46c6df0311
-  data.tar.gz: 59c5cc50b9a8ad522feac1360610f87932ee8624ed4119e1780a39eab29c9e43
+  metadata.gz: aedbda16896f72f7adc9320f2e1ade684cd1f4a49a392929ce3eb64d0320ca31
+  data.tar.gz: 8a77684970cde47e1ce927b2c4dab8c1e3c7b9356d876bbcb66a79c5d39769f4
 SHA512:
-  metadata.gz: 5e2fd4a85f9bfac64f8255aab6442b03384f69fc8376e6cd280dd2f4f93cbaac1cd15fce9169bb3d441a6ddcf12b901cb4e2d9fafa8efea06906f0bd55181d76
-  data.tar.gz: d87911a2437fd057da4caf47ee893df61a4e872eaa43d1fc470ea15ce8a3e546e4f083922df1eb38b0e44cd18d501cc1ba30e8333ba550eb8583cfb7ee13c218
+  metadata.gz: 37f051a10d8fad9eb51e3bebd2cefd84d523ca5961bb1fabc619f01a2db28f9c271a2a97701e8a575d2ab2e3244c5c1ee36b97bf9b94f45caa29f2f4a46340c1
+  data.tar.gz: 8c9cb46f8a7a74eff2488ef24e3641a3f6dccadee4735009290450630f3aab6bc90402e333c45c5061d8cb276767971eb316cba00196a1b7c3f3a6d7ad4fda85

data/CHANGELOG.md

@@ -5,6 +5,39 @@
 
 # Change Log
 
+## [5.3.0](https://github.com/ruby-git/ruby-git/compare/v5.2.0...v5.3.0) (2026-09-03)
+
+
+### Features
+
+* **author:** Add immutable Git::AuthorInfo and deprecate Git::Author ([c08b04b](https://github.com/ruby-git/ruby-git/commit/c08b04bf25142140c626fd16354355aae26b4fba)), closes [#1721](https://github.com/ruby-git/ruby-git/issues/1721)
+* **branch:** Deprecate Git::Branch and Git::Branches in favor of Git::Repository#branch_list ([1581aa0](https://github.com/ruby-git/ruby-git/commit/1581aa00b3fc7984a2024b290b83f6f6f5e97838)), closes [#1639](https://github.com/ruby-git/ruby-git/issues/1639)
+* **branch:** Deprecate Git::Branch#stashes in favor of Git::Repository#stashes_all ([dcee889](https://github.com/ruby-git/ruby-git/commit/dcee889a63bfd38cc3073577b55e2112721c5e33)), closes [#1637](https://github.com/ruby-git/ruby-git/issues/1637)
+* **cat-file:** Deprecate the allow_unknown_type option of Git::Commands::CatFile::Raw ([95769ea](https://github.com/ruby-git/ruby-git/commit/95769ea683349c445a7a7ea7b839fc990d2d8c4b)), closes [#1709](https://github.com/ruby-git/ruby-git/issues/1709)
+* **info:** Nest Git::AuthorInfo in Git::TagInfo and Git::StashInfo ([2f44f96](https://github.com/ruby-git/ruby-git/commit/2f44f9617122c3719625cf3a56f4b263b0de4c3c)), closes [#1745](https://github.com/ruby-git/ruby-git/issues/1745)
+* **remote:** Deprecate Git::Remote and Git::Repository#remote in favor of #remote_list ([1abb585](https://github.com/ruby-git/ruby-git/commit/1abb585339c0d003622719aa5930b5bde2262502)), closes [#1643](https://github.com/ruby-git/ruby-git/issues/1643)
+* **remote:** Freeze Git::RemoteInfo array-valued members ([4d44a3d](https://github.com/ruby-git/ruby-git/commit/4d44a3dc8fed77b39c7146675eaa9d46eb12e34d))
+* **repository:** Add in_branch and merge_into facade methods ([59b58d0](https://github.com/ruby-git/ruby-git/commit/59b58d0389656051e8cd61bd856dc116139c2507)), closes [#1641](https://github.com/ruby-git/ruby-git/issues/1641)
+* **repository:** Deprecate Git::Repository#remotes in favor of #remote_list ([410095c](https://github.com/ruby-git/ruby-git/commit/410095c4d2a3065c222f9cc750a05143230801d7)), closes [#1640](https://github.com/ruby-git/ruby-git/issues/1640)
+
+
+### Bug Fixes
+
+* **branching:** Verify refs/heads when classifying the HEAD state ([bfc4d8a](https://github.com/ruby-git/ruby-git/commit/bfc4d8a2b82000906d1a398c69125fcfdc22c276)), closes [#1641](https://github.com/ruby-git/ruby-git/issues/1641)
+
+
+### Other Changes
+
+* **adr:** Supersede ADR-0006 with a release-based deprecation period ([b3b32e3](https://github.com/ruby-git/ruby-git/commit/b3b32e339f3804d022ea83cec03977039ecdcace))
+* **author:** Add failing tests for Git::AuthorInfo and Git::Author deprecation ([e0d3123](https://github.com/ruby-git/ruby-git/commit/e0d3123fadd836e301160f492e0a1303f43267b8)), closes [#1721](https://github.com/ruby-git/ruby-git/issues/1721)
+* **branch:** Add failing test for the Git::Branch#stashes deprecation ([a806808](https://github.com/ruby-git/ruby-git/commit/a806808f3e5a5a38a92646c1ab64c8906b3dc525))
+* **contributing:** Describe the release line and maintenance branch rules ([fd78c9c](https://github.com/ruby-git/ruby-git/commit/fd78c9ccd262470c9e33166ba63dc095b2060a5d))
+* **info:** Add failing tests for nested Git::AuthorInfo on TagInfo and StashInfo ([a7f5e69](https://github.com/ruby-git/ruby-git/commit/a7f5e6988beaa85bce68e6295ad23a2754338d5b)), closes [#1745](https://github.com/ruby-git/ruby-git/issues/1745)
+* **readme:** Add the deprecation and release support policies ([50ac2e2](https://github.com/ruby-git/ruby-git/commit/50ac2e28bdd6ddb9349b8980e457441a0d39f6c9))
+* **remote:** Add failing tests for the Git::Remote and Git::Repository#remote deprecations ([36af404](https://github.com/ruby-git/ruby-git/commit/36af40419603f9c0a03f424e3839a1d7337b517b))
+* **skills:** State the deprecation policy and the major release checklists ([a246cf8](https://github.com/ruby-git/ruby-git/commit/a246cf8fee93a96132f2bd1b0796899204b830a1))
+* **upgrading:** Add the v6.0.0 upgrade procedure ([4d7c58c](https://github.com/ruby-git/ruby-git/commit/4d7c58c7a0e963da6146608093e9373dade1efe4))
+
 ## [5.2.0](https://github.com/ruby-git/ruby-git/compare/v5.1.0...v5.2.0) (2026-08-30)
 
 

data/CONTRIBUTING.md

@@ -221,10 +221,14 @@ first keeps the review cycle short.
 
 This project maintains two active branches:
 
-- **`main`**: Active development for the next major version (v5.0.0+). This branch
-  may contain breaking changes.
-- **`4.x`**: Maintenance branch for the v4.x release series. This branch receives bug
-  fixes and backward-compatible improvements only.
+- **`main`**: All development. It releases the next version of the gem, including
+  the next major version.
+- **`4.x`**: The maintenance branch for the most recent previous major series. It
+  receives bug fixes and security fixes, and backward-compatible features at the
+  maintainers' discretion.
+
+The README's [Release support policy](README.md#release-support-policy) says how long
+each major series is supported.
 
 When submitting a pull request:
 
@@ -232,6 +236,15 @@ When submitting a pull request:
 - **Bug fixes**: Target `main`, and maintainers will backport to `4.x` if applicable
 - **Security fixes**: Target both branches or `4.x` if the issue only affects v4.x
 
+Removing a deprecated API follows the
+[deprecation policy](.github/skills/breaking-change-analysis/SKILL.md#step-4-deprecation-policy):
+
+A removal PR merges to main only when its deprecation warning and `UPGRADING.md` entry
+are contained in a previous normal release. Once any removal has merged to main, main
+becomes the release line for the next major version. If another release of the
+previous major is needed, it is cut from a branch created for that major (e.g. `4.x`
+or `5.x`).
+
 ## AI-assisted contributions
 
 AI-assisted contributions are welcome. Please review and apply our [AI

data/README.md

@@ -35,6 +35,8 @@ Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?log
 - [Project policies](#project-policies)
   - [Ruby version support policy](#ruby-version-support-policy)
   - [Git version support policy](#git-version-support-policy)
+  - [Deprecation policy](#deprecation-policy)
+  - [Release support policy](#release-support-policy)
 - [Project announcements](#project-announcements)
   - [2026-08-23: v5.x deprecations and the v6.0.0 roadmap](#2026-08-23-v5x-deprecations-and-the-v600-roadmap)
   - [2026-07-28: v5.0.0 released](#2026-07-28-v500-released)
@@ -296,9 +298,9 @@ See [the Active Support Deprecation
 documentation](https://api.rubyonrails.org/classes/ActiveSupport/Deprecation.html)
 for more details.
 
-If you silence deprecation warnings, reenable them before upgrading the git gem to
-the next major version. This makes it easier to identify changes needed for the
-upgrade.
+Before upgrading the git gem to the next major version, follow the upgrade procedure
+in [UPGRADING.md](UPGRADING.md#upgrading-to-v600). It turns the warnings into errors so
+that you cannot miss one.
 
 For the full list of deprecated methods and their replacements, see
 [UPGRADING.md](UPGRADING.md).
@@ -382,6 +384,8 @@ opening issues or pull requests.
 | [AI_POLICY](AI_POLICY.md) | AI-assisted contributions are welcome. Contributors are expected to read and apply the AI Policy, and ensure any AI-assisted work meets our quality, security, and licensing standards. |
 | [Ruby version support policy](#ruby-version-support-policy) | Supported Ruby runtimes and platforms; bump decisions and CI coverage expectations. |
 | [Git version support policy](#git-version-support-policy) | Minimum supported git version and how version bumps are communicated and enforced. |
+| [Deprecation policy](#deprecation-policy) | When an API may be removed, what a deprecation warning says, and how to upgrade across a major version. |
+| [Release support policy](#release-support-policy) | Which branch releases what, and how long each major series is supported. |
 | [GOVERNANCE](GOVERNANCE.md) | Principles-first governance defining maintainer/project lead roles, least-privilege access, consensus/majority decisions, and nomination/emeritus steps. |
 | [MAINTAINERS](MAINTAINERS.md) | Lists active maintainers (Project Lead noted) and emeritus alumni with links; see governance for role scope. |
 | [LICENSE](LICENSE) | MIT License terms for using, modifying, and redistributing this project. |
@@ -418,6 +422,42 @@ The supported git version may be increased in future major or minor releases of
 gem as new git features are adopted or as maintaining backward compatibility becomes
 impractical. Such changes will be documented in the CHANGELOG and release notes.
 
+### Deprecation policy
+
+This gem removes an API only in a major release, and only after a normal release
+deprecated it with a runtime warning and documented its replacement in
+[UPGRADING.md](UPGRADING.md). A normal release is one that is not a pre-release. The
+warning names the major release that removes the API once that is decided. Until then
+it says the API will be removed in a future major release.
+
+The recommended way to upgrade across a major version:
+
+1. Upgrade to the latest release of the major series you are on.
+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 in [UPGRADING.md](UPGRADING.md) until the
+   suite is clean.
+4. Upgrade to the next major release.
+
+Because every deprecation warning is present in the last release of a major series,
+this procedure finds every change the next major requires. The version-specific steps
+are in [UPGRADING.md](UPGRADING.md#upgrading-to-v600). See
+[Deprecations](#deprecations) for how to configure the warnings.
+
+### Release support policy
+
+All development happens on `main`, which releases the next version of the gem,
+including the next major version.
+
+The most recent previous major series is maintained on a branch named for that
+series, currently `4.x`. It receives bug fixes and security fixes, and
+backward-compatible features at the maintainers' discretion. Fixes land on `main`
+first and are backported, except a fix for a problem that exists only in the
+maintenance branch, which targets that branch directly.
+
+Support for a major series ends when the second major after it is released. v4.x is
+supported until v6.0.0 ships, and v5.x until v7.0.0.
+
 ## Project announcements
 
 ### 2026-08-23: v5.x deprecations and the v6.0.0 roadmap
@@ -426,10 +466,11 @@ The road to v6.0.0 is now planned and public. The remaining ActiveRecord-style
 classes (`Git::Branch`, `Git::Remote`, `Git::Stash`, `Git::Worktree`,
 `Git::Object::Tag`, `Git::Status`, `Git::Author`, and their collections) will be
 deprecated during the v5.x series in favor of the immutable `*Info` value-object
-APIs. v6.0.0 will remove each deprecated class that passes the project's removal
-gate: a mandated deprecation soak period plus a proven-safe check. Any class that
-does not pass carries forward, still deprecated. v6.0.0 also raises the version
-floors: git ≥ 2.42.0, Ruby ≥ 3.4.
+APIs. v6.0.0 will remove each deprecated class once a normal v5.x release has carried
+its deprecation warning and UPGRADING.md entry, per the
+[Deprecation policy](#deprecation-policy). v6.0.0 will not ship until every planned
+deprecation has shipped that way. v6.0.0 also raises the version floors: git ≥ 2.42.0,
+Ruby ≥ 3.4.
 
 [Issue #1717](https://github.com/ruby-git/ruby-git/issues/1717) is the living
 roadmap, tracking scope, sequencing, and status. If your code uses the classes

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/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