git 5.6.0 → 6.0.0

data/UPGRADING.md

@@ -1,10 +1,31 @@
-# Upgrading the `git` Gem
+# Upgrading the `git` gem
 
 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 v6.x](#upgrading-to-v6x)
+  - [Before you upgrade](#before-you-upgrade)
+    - [Minimum Ruby version](#minimum-ruby-version)
+    - [Minimum git version](#minimum-git-version)
+    - [Minimum addressable version](#minimum-addressable-version)
+    - [Minimum activesupport version](#minimum-activesupport-version)
+  - [Changes the deprecation run does not catch or does not explain](#changes-the-deprecation-run-does-not-catch-or-does-not-explain)
+    - [Filesystem errors raised as `Git::Error`](#filesystem-errors-raised-as-giterror)
+    - [Gzip failures in `archive` raised as `Git::Error`](#gzip-failures-in-archive-raised-as-giterror)
+    - [Relative `:repository` and `:index` paths](#relative-repository-and-index-paths)
+    - [Tilde expansion in `Git.init` and `Git.clone` paths](#tilde-expansion-in-gitinit-and-gitclone-paths)
+    - [Context helpers yield a separate repository](#context-helpers-yield-a-separate-repository)
+    - [`Git.init`, `Git.open`, and `Git.bare` reject unknown options](#gitinit-gitopen-and-gitbare-reject-unknown-options)
+    - [`tag_create` raises when the created tag is missing](#tag_create-raises-when-the-created-tag-is-missing)
+    - [`stash_list` returns an Array of `Git::StashInfo`](#stash_list-returns-an-array-of-gitstashinfo)
+    - [`stash_store` raises when the stored entry is missing](#stash_store-raises-when-the-stored-entry-is-missing)
+    - [`worktree_add` returns `Git::WorktreeInfo` and raises when the worktree is missing](#worktree_add-returns-gitworktreeinfo-and-raises-when-the-worktree-is-missing)
+    - [`Git::Deprecation` horizon is prose](#gitdeprecation-horizon-is-prose)
+  - [Removed APIs](#removed-apis)
+  - [Deprecated in v6.0.0](#deprecated-in-v600)
+    - [`set_index` and `set_working` deprecated](#set_index-and-set_working-deprecated)
+    - [`Git::GitExecuteError` deprecated](#gitgitexecuteerror-deprecated)
 - [Upgrading to v5.x](#upgrading-to-v5x)
   - [Overview](#overview)
   - [Breaking changes](#breaking-changes)
@@ -17,6 +38,7 @@ to update your code when upgrading from the preceding major version.
   - [Deprecated methods](#deprecated-methods)
     - [Facade method renames](#facade-method-renames)
     - [`Git::Repository` method renames](#gitrepository-method-renames)
+    - [`Git::Repository` alias renames](#gitrepository-alias-renames)
     - [`Git::Repository` option renames](#gitrepository-option-renames)
     - [v4.x-style configuration methods](#v4x-style-configuration-methods)
     - [`Git` module mixin deprecations](#git-module-mixin-deprecations)
@@ -35,24 +57,628 @@ to update your code when upgrading from the preceding major version.
     - [`Git::Log` Enumerable interface deprecated](#gitlog-enumerable-interface-deprecated)
     - [`Git::Object::Commit#set_commit` deprecated](#gitobjectcommitset_commit-deprecated)
     - [`Git.export` `:remote` option deprecated](#gitexport-remote-option-deprecated)
-    - [Context helper blocks that declare no parameter deprecated](#context-helper-blocks-that-declare-no-parameter-deprecated)
 
-## Upgrading to v6.0.0
-
-v6.0.0 is not yet released. This section will be completed when it ships.
+## Upgrading to v6.x
 
 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.
+[deprecation policy](README.md#deprecation-policy), raises the Ruby, git, and
+dependency floors, and changes a small number of behaviors that had no deprecation
+path. [Issue 1717](https://github.com/ruby-git/ruby-git/issues/1717) tracks its scope.
+
+This section is organized by what you have to do rather than by what changed:
+
+- [Before you upgrade](#before-you-upgrade) gives the version floors and the upgrade
+  procedure. Read it first.
+- [Changes the deprecation run does not catch or does not
+  explain](#changes-the-deprecation-run-does-not-catch-or-does-not-explain) covers
+  every change that a clean run under `GIT_DEPRECATION_BEHAVIOR=raise` does not find,
+  and the two warnings whose fix is not a removed API's replacement. Read each entry.
+- [Removed APIs](#removed-apis) is one table of every API removed in v6.0.0 and its
+  replacement. Every one of them warned in v5.x when called, constructed, or used, so
+  the raise behavior finds each call, and the table links to the entry under
+  "Upgrading to v5.x" that maps each call shape to its replacement. A bare reference
+  to a removed constant did not warn, so step 8 has you search for those.
+- [Deprecated in v6.0.0](#deprecated-in-v600) covers the APIs that warn in v6.0.0 and
+  are removed in a later major release.
+
+If you are upgrading from v4.x directly, the v5.x warnings never ran against your
+code, so also read [Upgrading to v5.x](#upgrading-to-v5x). Its entries map each v4.x
+call to its replacement, and the [Removed APIs](#removed-apis) table tells you which of
+those replacements are now the only option.
+
+### Before you upgrade
+
+1. Upgrade to Ruby 3.3 or later if you are still on Ruby 3.2 (see
+   [Minimum Ruby version](#minimum-ruby-version)).
+2. Check that `git --version` reports 2.43.0 or later everywhere the gem runs (see
+   [Minimum git version](#minimum-git-version)).
+3. Run `bundle update addressable` and confirm the lockfile resolves addressable
+   2.9.0 or later (see [Minimum addressable version](#minimum-addressable-version)).
+4. Run `bundle update activesupport` and confirm the lockfile resolves activesupport
+   7.0.9 or later (see [Minimum activesupport version](#minimum-activesupport-version)).
+5. Upgrade to the latest v5.x release.
+6. Set `GIT_DEPRECATION_BEHAVIOR=raise` (or `Git::Deprecation.behavior = :raise`) in
+   your test suite and, if possible, staging.
+7. Fix each deprecation until the suite is clean. The [Removed APIs](#removed-apis)
+   table links each removed API's replacement. Three warnings are not removals:
+   - `stash_list` keeps its name and changes its return type (see [`stash_list`
+     returns an Array of `Git::StashInfo`](#stash_list-returns-an-array-of-gitstashinfo)).
+   - A context-helper block with no positional parameter, which v5.6.0 and later
+     warn about (see [Context helpers yield a separate
+     repository](#context-helpers-yield-a-separate-repository)).
+   - `Git::GitExecuteError`, which still warns in v6.0.0 (see
+     [`Git::GitExecuteError` deprecated](#gitgitexecuteerror-deprecated)).
+8. Search your code for each constant in the [Removed APIs](#removed-apis) table. A
+   bare reference such as `is_a?(Git::Base)`, `rescue Git::Status`, or
+   `case ... when Git::Author` never warned in v5.x, so the raise behavior does not
+   find it, and it raises `NameError` in v6.0.0.
+9. Work through each entry under [Changes the deprecation run does not catch or does
+   not explain](#changes-the-deprecation-run-does-not-catch-or-does-not-explain). The two
+   that affect the most code:
+   - Replace any `rescue Errno::*` around gem calls with `rescue Git::Error` (see
+     [Filesystem errors raised as `Git::Error`](#filesystem-errors-raised-as-giterror)).
+   - Give every `with_index`, `with_temp_index`, `with_working`, and
+     `with_temp_working` block a parameter and call methods on it rather than on the
+     outer repository; v5.6.0 and later warn for a block with no positional parameter
+     (see [Context helpers yield a separate
+     repository](#context-helpers-yield-a-separate-repository)).
+10. Upgrade to v6.0.0.
+
+#### Minimum Ruby version
+
+v6.0.0 requires Ruby 3.3.0 or later. v5.x supports Ruby 3.2, which reached end of
+life on 2026-03-31. The
+[Ruby version support policy](README.md#ruby-version-support-policy) commits the
+gem to the MRI versions that are still maintained, so the floor moves when a Ruby
+version leaves maintenance rather than with the gem's major version. Ruby 3.3 is
+in security maintenance until about 2027-03-31, so it stays supported in v6.0.0.
+A 3.4 floor can land in a later v6.x release once 3.3 reaches end of life.
+
+JRuby and TruffleRuby support is unchanged.
+
+If your application still runs on Ruby 3.2, upgrade Ruby before upgrading the gem,
+or stay on the latest v5.x release.
+
+#### Minimum git version
+
+v6.0.0 requires git 2.43.0 or later. v5.x required 2.28.0.
+
+Git 2.43.0 was released on November 20, 2023, and is the version shipped by
+Ubuntu 24.04, RHEL 8.10 and 9.4, SLES 15 SP6, openSUSE Leap 15.6, and Alpine 3.19.
+Ubuntu 22.04 (git 2.34) and Debian 12 (git 2.39) are the supported platforms whose
+stock git falls below the new floor. On Ubuntu 22.04, install a newer git (for
+example from the [git-core PPA](https://launchpad.net/~git-core/+archive/ubuntu/ppa));
+on Debian 12, install it from
+[bookworm-backports](https://backports.debian.org/Instructions/); or stay on v5.x.
+Apple's git 2.39 from Xcode 16 also falls below the floor; Xcode 26 ships git 2.50.
+
+Features that need a git newer than 2.43.0 stay gated per command and raise
+`Git::VersionError` on older installations, as `git am --retry` (2.46.0) does today.
+
+#### Minimum addressable version
+
+v6.0.0 depends on `addressable ~> 2.9`. v5.x accepts `~> 2.8`.
+
+Addressable 2.9.0 (released in April 2026) fixes the ReDoS vulnerability in
+`Addressable::Template#match`
+([GHSA-h27x-rffw-24p4](https://github.com/sporkmonger/addressable/security/advisories/GHSA-h27x-rffw-24p4)).
+Addressable 2.8.10 mitigates only part of it, and the advisory lists every release
+below 2.9.0 as affected. The gem never calls `Addressable::Template`, so v5.x is not
+affected and keeps the wider constraint. v6.0.0 raises the floor to the 2.9 series so
+that dependency scanners stop flagging the gem's resolved dependency tree.
+
+The `~> 2.8` constraint already permits 2.9.0, so most applications resolve it after
+`bundle update addressable`. The upgrade fails only when another gem in the bundle
+caps addressable below 2.9.0. In that case, update or replace that gem, or stay on
+the latest v5.x release.
+
+#### Minimum activesupport version
+
+v6.0.0 depends on `activesupport >= 7.0.9`. v5.x accepts `>= 5.0`.
+
+Two things set the floor. The `Git::GitExecuteError` deprecation warning passes its
+text to ActiveSupport's `DeprecatedConstantProxy` through the `message:` keyword, which
+no release before 6.0.3 accepts on Ruby 3. Separately, activesupport requires
+`base64`, `bigdecimal`, `drb`, and `mutex_m` from the standard library, and Ruby 3.4
+removed those from the default gems, so on Ruby 3.4 or later `require 'git'` fails
+under Bundler unless a gem in the bundle declares them. Activesupport 7.0.9 is the
+first 7.0.x release that declares them as dependencies; every 7.1.0 and later release
+does too. The floor applies on every Ruby version so that Bundler reports the conflict
+when it resolves the bundle, instead of `require 'git'` failing on Ruby 3.4.
+
+Most applications already resolve a newer activesupport. The upgrade fails only when
+another gem in the bundle caps activesupport below 7.0.9. In that case, update or
+replace that gem, or stay on the latest v5.x release.
+
+### Changes the deprecation run does not catch or does not explain
+
+Most changes below never emitted a warning in v5.x, because the method keeps its name
+and changes what it returns or does, or keeps working after the upgrade with a
+different result. Two of them warned, `stash_list` and the context-helper block form,
+but neither is a removed API, so the [Removed APIs](#removed-apis) table has no row
+for them and their entries live here. A clean run under
+`GIT_DEPRECATION_BEHAVIOR=raise` is therefore not proof that your code is unaffected.
+Search your code for each one before upgrading.
+
+#### Filesystem errors raised as `Git::Error`
+
+The gem's own filesystem calls used to let a bare `SystemCallError` escape, which
+contradicted the documented contract that the gem raises only `ArgumentError` or a
+`Git::Error` subclass. Those calls now raise `Git::Error`, with the original error
+available through `cause`.
+
+The affected methods are `Git.open` (reading a gitdir pointer file), `Git.export`,
+`Git::Repository#chdir`, `#with_index`, `#with_working`, `#with_temp_index`,
+`#with_temp_working`, `#set_index`, `#set_working`, `#cat_file_contents`,
+`#each_conflict`, `#archive`, and `#repo_size`. `Git.init`, `Git.clone`, `Git.bare`,
+and `Git.open` also raise `Git::Error` when the directory argument or a
+`:repository`, `:index`, or `:chdir` option cannot be expanded to an absolute path,
+which happens when the process working directory has been removed.
 
-To prepare:
+```ruby
+# v5.x
+begin
+  Git.open('/path/to/repo')
+rescue Errno::EACCES => e
+  handle_permission_problem(e)
+end
 
-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.
+# v6.x
+begin
+  Git.open('/path/to/repo')
+rescue Git::Error => e
+  raise unless e.cause.is_a?(Errno::EACCES)
+
+  handle_permission_problem(e.cause)
+end
+```
+
+Code that already rescues `Git::Error` needs no change. A `SystemCallError` raised by
+your own block inside `chdir`, `with_working`, `with_temp_index`, `with_temp_working`,
+or the block form of `cat_file_contents` still propagates unchanged, so the gem never
+relabels an error raised by your code.
+
+#### Gzip failures in `archive` raised as `Git::Error`
+
+`Git::Repository#archive` with `format: 'tgz'` or `add_gzip: true` used to let a
+`Zlib::Error` subclass escape when compression failed. It now raises `Git::Error`, with
+the `Zlib::Error` available through `cause`. Code that already rescues `Git::Error`
+needs no change.
+
+#### Relative `:repository` and `:index` paths
+
+A relative `:repository` option of `Git.open` or `Git.init`, and a relative `:index`
+option of `Git.open`, `Git.init`, or `Git.clone`, is now expanded against the process
+working directory, the same way the positional directory argument, `set_index`, and
+`set_working` treat a relative path. A relative `:repository` used to be expanded
+against the working directory, and a relative `:index` against the git directory.
+For `Git.clone` with the `:chdir` option, a relative `:index` is expanded against
+`:chdir` instead, like the clone directory itself.
+
+Omitted options resolve as before: `:repository` defaults to `<working_dir>/.git` and
+`:index` to `<git_dir>/index`. Absolute paths are unaffected. A relative `:repository`
+option of `Git.clone` keeps its meaning: it is relative to `:chdir` when given and to
+the process working directory otherwise, which is where git already resolved it.
+
+```ruby
+# v5.x: the index is bound to /path/to/repo/.git/scratch.index
+repo = Git.open('/path/to/repo', index: 'scratch.index')
+
+# v6.x: the index is bound to scratch.index in the process working directory.
+# Join the path yourself to keep the v5.x location.
+repo = Git.open('/path/to/repo', index: '/path/to/repo/.git/scratch.index')
+```
+
+#### Tilde expansion in `Git.init` and `Git.clone` paths
+
+`Git.init` and `Git.clone` now expand the directory argument and the `:repository` and
+`:index` options before handing the path to git, so `~` is the home directory, as it
+already is for `Git.bare`, `set_index`, and `set_working`. `Git.clone` expands its
+`:chdir` option the same way, and `Git.open` expands its directory argument before
+checking that it exists, so `Git.open('~/scratch')` opens the repository instead of
+raising `ArgumentError`. git does no tilde expansion on its arguments, so a `~`-prefixed
+path used to make git create a directory literally named `~` under the process working
+directory, or under `:chdir` for `Git.clone`. For `Git.init('~/scratch')` the returned
+repository then pointed at `$HOME/scratch`, which git had not created, and the first
+command run on it failed. For a `~`-prefixed `:repository` or `:chdir` option of
+`Git.clone`, git failed before cloning anything.
+
+A caller who passed a `~`-prefixed path and wanted a directory named `~` must anchor
+the path to keep it. Expanding before git runs is also visible in three other ways:
+
+- git receives absolute paths, so a `:log` that recorded `Cloning into 'my-repo'...` now
+  records the absolute path.
+- A `:repository`, `:index`, or `:chdir` that cannot be expanded raises before git runs,
+  with nothing on disk, instead of after the clone or init completed: `Git::Error` when
+  the process working directory has been removed, and `ArgumentError` for a `~user`
+  prefix that names no user.
+- `..` is normalized lexically before git sees the path. `Git.init('a/../b')` creates
+  only `b`, where `git init a/../b` at a shell prompt also created `a`, and a path
+  through a symlinked directory resolves to where the link appears rather than where it
+  points.
+
+The rule these methods now share is recorded in
+[ADR-0010](docs/adr/0010-a-repository-locating-path-means-what-it-would-mean-at-a-shell-prompt.md).
+
+```ruby
+# v5.x: git creates ./~/scratch; the returned repository points at $HOME/scratch
+repo = Git.init('~/scratch')
+
+# v6.x: git creates $HOME/scratch and the returned repository is bound to it
+repo = Git.init('~/scratch')
+
+# v6.x: anchor the path to keep a directory literally named ~
+repo = Git.init('./~/scratch')
+```
+
+#### Context helpers yield a separate repository
+
+`Git::Repository#with_index`, `#with_temp_index`, `#with_working`, and
+`#with_temp_working` used to rebind the receiver to the other index or working tree
+for the duration of the block and yield the receiver itself. They now build a second
+repository of the receiver's class bound to that index or working tree, yield it,
+and leave the receiver bound to its original index and working tree.
+
+Code that uses the block parameter and finishes with it before the block ends needs
+no change. A block that declares no positional parameter, the v5.x form, now raises
+`ArgumentError` before the block runs. Starting in v5.6.0 that form warns through
+`Git::Deprecation`, so clear the warning on the latest v5.x release before upgrading.
+A call with no block raises `ArgumentError` instead of `LocalJumpError`. Code that
+declares the parameter but ignores it and calls methods on the outer repository
+inside the block runs those calls against the original index or working tree. Use the
+block parameter instead:
+
+```ruby
+# v5.x
+repo.with_temp_index do
+  repo.read_tree('HEAD')
+  repo.write_tree
+end
+
+# v6.x
+repo.with_temp_index do |indexed|
+  indexed.read_tree('HEAD')
+  indexed.write_tree
+end
+```
+
+The same applies to reading `index` or `dir` inside the block to find the temporary
+path: read them on the block parameter. A block that needs only the changed process
+directory, such as one that writes files inside `with_temp_working`, still declares
+the parameter (`do |_scratch|`).
+
+A helper nested inside another must also be called on the block parameter. A nested
+call on the outer repository derives from the outer repository's original index and
+working tree, so it does not see the outer block's temporary location:
+
+```ruby
+# v5.x
+repo.with_temp_working do
+  repo.with_temp_index do
+    repo.add('.')
+    repo.write_tree
+  end
+end
+
+# v6.x
+repo.with_temp_working do |scratch|
+  scratch.with_temp_index do |indexed|
+    indexed.add('.')
+    indexed.write_tree
+  end
+end
+```
+
+Calling `set_index` or `set_working` on the outer repository inside the block is no
+longer undone when the block ends. In v5.x the block restored the receiver's
+original index and working tree on exit; in v6.x there is no restore step, so the
+receiver stays bound to whatever `set_index` or `set_working` gave it. Both methods
+are deprecated in v6.0.0 (see [`set_index` and `set_working`
+deprecated](#set_index-and-set_working-deprecated)).
+
+The repository yielded by `with_temp_index` or `with_temp_working` stays bound to
+the temporary path after the block removes it. This is the one case where code that
+already used the block parameter has to change. If the yielded repository escapes
+the block, directly or inside an object that holds it and later runs commands, calls
+against the removed working tree raise `Git::Error`. Against the removed index,
+reads do not raise: git treats the missing index file as an empty index, so
+`ls_files` returns nothing and `status_info` reports every tracked file both as
+deleted and as untracked. Writes such as `add` do raise `Git::Error`. Reads from
+the object database, such as `Git::Object::AbstractObject#contents`, still work. In
+v5.x an escaped object held the outer repository, which had been rebound to the
+original path by then.
+
+The yielded repository is built with `self.class.new(execution_context:)`, so a
+subclass of `Git::Repository` has to accept that call. A subclass whose `initialize`
+takes different keywords raises `ArgumentError` from these helpers. One that takes a
+positional argument instead receives the keywords as a Hash and yields a
+misconfigured repository, so check the constructor rather than waiting for an
+exception.
+
+`with_working` and `with_temp_working` still change the process working directory
+with `Dir.chdir` for the duration of the block, so they remain unsafe to call from
+more than one thread at a time.
+
+#### `Git.init`, `Git.open`, and `Git.bare` reject unknown options
+
+`Git.init`, `Git.open`, and `Git.bare` now raise `ArgumentError` when the options
+hash contains a key they do not accept, the same way `Git.ls_remote` already does.
+v5.x ignored unknown keys, so a typo such as `respository:` or an unsupported key
+silently returned a repository bound to paths the caller did not ask for, and
+`Git.init` created the repository in the default location instead of the one
+the mistyped key was meant to name.
+
+For the APIs that did validate option names in v5.x, see
+[Unsupported options raise `ArgumentError`](#unsupported-options-raise-argumenterror).
+
+The accepted keys are:
+
+- `Git.init`: `:bare`, `:initial_branch`, `:repository`, `:separate_git_dir`,
+  `:index`, `:log`, `:git_ssh`, and `:binary_path`
+- `Git.open`: `:repository`, `:index`, `:log`, `:git_ssh`, and `:binary_path`
+- `Git.bare`: `:index`, `:log`, `:git_ssh`, and `:binary_path`
+
+The check runs before any filesystem or git call, so a bad key fails fast. To fix a
+call that now raises, drop the key.
+
+```ruby
+# v5.x: the typo is ignored and the .git directory is auto-detected
+# v6.x: raises ArgumentError, "Unknown options: respository"
+repo = Git.open('/path/to/worktree', respository: '/srv/repo.git')
+
+# v6.x: the corrected call opens the repository
+repo = Git.open('/path/to/worktree', repository: '/srv/repo.git')
+
+# v5.x: the typo is ignored and the repository is created at /path/to/worktree/.git
+# v6.x: raises ArgumentError, "Unknown options: separate_gitdir"
+repo = Git.init('/path/to/worktree', separate_gitdir: '/srv/repo.git')
+
+# v6.x: the corrected call creates the repository at /srv/repo.git
+repo = Git.init('/path/to/worktree', separate_git_dir: '/srv/repo.git')
+```
+
+#### `tag_create` raises when the created tag is missing
+
+In v5.x, `g.tag_create` returned `nil` when the tag it had just created was missing from
+the tag list (for example, another process deleted it before the lookup). It never
+emitted a deprecation warning, since the method keeps its name. In v6.0.0 it raises
+`Git::UnexpectedResultError` instead, so its return value is always a `Git::TagInfo`.
+Search for `tag_create` before upgrading and remove any check for a `nil` result.
+
+#### `stash_list` returns an Array of `Git::StashInfo`
+
+In v5.x, `g.stash_list` returned the `git stash list` text as a `String` and emitted a
+`Git::Deprecation` warning on every call. A project that silences or ignores deprecation
+warnings never acts on that notice, and in v6.0.0 the call keeps working with a
+different return type: `Array<Git::StashInfo>`, newest first, the same value as
+`Git::Repository#stash_infos`, which stays as a permanent alias. Search for `stash_list`
+before upgrading. Code that needs the text builds it from the entries:
+`g.stash_list.map { |s| "#{s.name}: #{s.message}" }.join("\n")`.
+
+#### `stash_store` raises when the stored entry is missing
+
+In v5.x, `g.stash_store` returned the top entry of the stash list after the store, so it
+returned `nil` when the list was empty and another process's entry when one had been
+pushed in between. It never emitted a deprecation warning, since the method keeps its
+name. In v6.0.0 it returns the entry for the commit it stored and raises
+`Git::UnexpectedResultError` when that entry is missing, so its return value is always a
+`Git::StashInfo`. A commit that does not resolve raises `Git::FailedError` before
+anything is stored. A `nil` commit or one that begins with `-` raises `ArgumentError` as
+in v5.x, with a different message; one that begins with `^` raises `ArgumentError` where
+v5.x raised `Git::FailedError`. An annotated tag name now stores the tagged commit; v5.x
+stored the tag object, which hid every entry from `git stash list`. Search for
+`stash_store` before upgrading and remove any check for a `nil` result.
+
+#### `worktree_add` returns `Git::WorktreeInfo` and raises when the worktree is missing
+
+In v4.x and v5.x, `g.worktree_add` returned the `git worktree add` output
+(`"HEAD is now at …"`) as a `String` and never emitted a deprecation warning, since the
+method keeps its name. In v6.0.0 it returns the new worktree's `Git::WorktreeInfo`, the
+same entry `g.worktree_list` reports for it, and raises `Git::UnexpectedResultError`
+when that entry is missing after the add, as `tag_create` and `stash_store` do. A
+`rescue Git::FailedError` around the call no longer covers every error it can raise.
+Search for `worktree_add` before upgrading.
+Code that used the return value as a `String` reads `info.path`, `info.head`, and
+`info.branch` instead; `Git::WorktreeInfo#to_s` is the path, so string interpolation of
+the result yields the worktree path.
+
+#### `Git::Deprecation` horizon is prose
+
+v6.0.0 constructs `Git::Deprecation` with the horizon `"in a future major release"`.
+v5.x used `"6.0.0"`. The gem never puts the horizon into a warning, so the warnings
+themselves do not change. The horizon reaches your code through the
+`Git::Deprecation.deprecation_horizon` reader, the `deprecation_horizon` key of the
+payload the `:notify` behavior publishes, and the third argument of a custom
+`behavior` or `disallowed_behavior` proc declared with four parameters. Code that
+parses that value as a version, for example with `Gem::Version.new`, now raises; read
+the removal version from the warning text instead, which names it once it is decided.
+
+### Removed APIs
+
+Every API in this table emitted a deprecation warning in v5.x that named its
+replacement when it was called, constructed, or used, and each row links to the entry
+under "Upgrading to v5.x" that maps every call shape, reader, and option to its
+replacement, including return shape differences. A bare reference to a removed
+constant (`is_a?`, `rescue`, `case ... when`, `defined?`) did not warn, except for
+`Git::CommandLineResult`, so search for each constant in the table as well as
+clearing the warnings. In v6.0.0 a removed constant raises `NameError` when
+referenced, a removed method raises `NoMethodError` when called, and a removed option
+raises `ArgumentError` like any other unsupported option (see [Unsupported options
+raise `ArgumentError`](#unsupported-options-raise-argumenterror)).
+
+| Removed in v6.0.0 | Use instead | Migration entry |
+| --- | --- | --- |
+| `Git::Repository#add_remote`, `#remove_remote`, `#set_remote_url`, `#add_tag`, `#delete_tag` | `remote_add`, `remote_remove`, `remote_set_url`, `tag_create`, `tag_delete` | [Facade method renames](#facade-method-renames) |
+| `Git::Repository#empty?`, `#reset_hard`, `#conflicts`, `#is_local_branch?`, `#is_remote_branch?`, `#is_branch?`, `#branches_all` | `no_commits?`, `reset(commitish, hard: true)`, `each_conflict`, `local_branch?`, `remote_branch?`, `branch?`, `branch_list` | [`Git::Repository` method renames](#gitrepository-method-renames) |
+| `Git::Repository#object_contents`, `#object_size`, `#object_type`, `#commit_data`, `#tag_data`, `#revparse`, `#namerev`, `#diff_name_status` | `cat_file_contents`, `cat_file_size`, `cat_file_type`, `cat_file_commit`, `cat_file_tag`, `rev_parse`, `name_rev`, `diff_path_status` | [`Git::Repository` alias renames](#gitrepository-alias-renames) |
+| `clean(ff: true)` and `clean(force_force: true)`; `diff_path_status(path: ...)`; `commit(add_all: true)`; the positional `check` argument of `set_working` and `set_index` | `force: 2`; `:path_limiter`; `:all`; `must_exist:` | [`Git::Repository` option renames](#gitrepository-option-renames) |
+| `Git::Repository#config` and `#global_config`; `Git.global_config`; `config` and `global_config` as instance methods of the `Git` module | `config_get`, `config_set`, and `config_list` on `Git::Repository` or `Git`, with `global: true` for the global scope | [v4.x-style configuration methods](#v4x-style-configuration-methods), [`Git` module mixin deprecations](#git-module-mixin-deprecations) |
+| `Git.binary_version`; `Git.ls_remote(nil)` | `Git.git_version` (`.to_a` for the Array); `Git.ls_remote` with no argument or `'.'` | [Module-level `Git` function deprecations](#module-level-git-function-deprecations) |
+| `Git.clone` options `:path`, `:recursive`, and `:remote` | `:chdir`, `:recurse_submodules`, and `:origin` | [`Git.clone` option renames](#gitclone-option-renames) |
+| `Git.export` option `:remote` | Delete the option; it has no replacement | [`Git.export` `:remote` option deprecated](#gitexport-remote-option-deprecated) |
+| `Git::Base` | Include an application-owned module into `Git::Repository` | [`Git::Base` removed](#gitbase-removed) |
+| `Git::Repository#lib` | Call the facade method directly on the repository | [`Git::Lib` removed](#gitlib-removed) |
+| `Git::CommandLineResult` | `Git::CommandLine::Result` | [`Git::CommandLineResult` deprecated](#gitcommandlineresult-deprecated) |
+| `Git::Log#each`, `#size`, `#to_s`, `#first`, `#last`, `#[]`, and every other `Enumerable` method on `Git::Log` | `Git::Log#execute`, which returns a `Git::Log::Result` with the same methods | [`Git::Log` Enumerable interface deprecated](#gitlog-enumerable-interface-deprecated) |
+| `Git::Object::Commit#set_commit` | `from_data` | [`Git::Object::Commit#set_commit` deprecated](#gitobjectcommitset_commit-deprecated) |
+| `Git::Author` | `Git::AuthorInfo` (`parse` to build one, `with` in place of the writers) | [`Git::Author` deprecated](#gitauthor-deprecated) |
+| `Git::Branch#stashes` | `Git::Repository#stash_infos` | [`Git::Branch#stashes` deprecated](#gitbranchstashes-deprecated) |
+| `Git::Stash`, `Git::Stashes`, `Git::Repository#stashes_all`, `#stash_save` | `stash_list` (or its alias `stash_infos`), `stash_push`, and the name-based stash operations | [Legacy stash API deprecated](#legacy-stash-api-deprecated) |
+| `Git::Repository#remotes` | `remote_list`, or `remote_names` for the names alone | [`Git::Repository#remotes` deprecated](#gitrepositoryremotes-deprecated) |
+| `Git::Remote`, `Git::Repository#remote`, `#config_remote` | `remote_list`, which returns `Git::RemoteInfo` objects; filter `config_list` on the `remote.<name>.` prefix for keys it does not model | [`Git::Remote` deprecated](#gitremote-deprecated) |
+| The `allow_unknown_type:` option of `Git::Commands::CatFile::Raw` | No replacement | [`Git::Commands::CatFile::Raw` `allow_unknown_type` option deprecated](#gitcommandscatfileraw-allow_unknown_type-option-deprecated) |
+| `Git::Branch`, `Git::Branches`, `Git::Repository#branch`, `#branches` | `branch_list`, which returns `Git::BranchInfo` objects, and the name-based branch operations | [`Git::Branch` and `Git::Branches` deprecated](#gitbranch-and-gitbranches-deprecated) |
+| `Git::Object::Tag`, `Git::Repository#tag`, `#tags`, `#tag_add`, and the `is_tag` argument of `Git::Object.new` | `tag_list` and `tag_create`, which return `Git::TagInfo` objects | [`Git::Object::Tag` deprecated](#gitobjecttag-deprecated) |
+| `Git::Status`, `Git::Status::StatusFile`, `Git::Repository#status` | `status_info`, which returns a `Git::StatusInfo` | [`Git::Status` deprecated](#gitstatus-deprecated) |
+| `Git::Worktree`, `Git::Worktrees`, `Git::Repository#worktree`, `#worktrees`, `#worktrees_all` | `worktree_list`, which returns `Git::WorktreeInfo` objects, and the path-based worktree operations | [`Git::Worktree` and `Git::Worktrees` deprecated](#gitworktree-and-gitworktrees-deprecated) |
+
+Notes on specific rows:
+
+- `add_tag`: go straight to `tag_create`. The `tag_add` that the v5.x warning names is
+  removed too.
+- `diff_name_status` callers that passed `:path` must also switch to `:path_limiter`.
+- `cat_file` is unaffected and stays as a legacy name for `cat_file_contents`, and
+  `stash_infos` stays as an alias of `stash_list`.
+- `set_working` and `set_index`: a positional `check` argument raises `ArgumentError`
+  for the wrong number of arguments. Pass `must_exist:` instead; it defaults to
+  `true`. An explicit `must_exist: nil` no longer means "not given". v5.x treated it
+  as `true`, and v6.0.0 treats it as `false` like any other falsy value. Omit the
+  keyword to get the default. Both methods are deprecated in v6.0.0 (see [`set_index`
+  and `set_working` deprecated](#set_index-and-set_working-deprecated)), so consider
+  replacing the call instead of updating its arguments.
+- `Git.ls_remote(nil)`: an explicit `nil` repository argument raises `ArgumentError`
+  with the message `repository must not be nil`. Omitting the argument still defaults
+  to `'.'`, so `Git.ls_remote` and `Git.ls_remote('.', opts)` are unchanged.
+- `Git.config` (the gem-configuration accessor used as `Git.config.binary_path`) and
+  `Git.configure` are not part of the configuration API removal and are unchanged.
+- `Git.export` `:remote` renamed the clone's remote, and `Git.export` deletes the `.git`
+  directory before returning, so the name was never observable.
+- `allow_unknown_type`: git 2.50 removed the unknown-type feature and accepts the flag
+  as a no-op, and on git 2.43 through 2.49 the ability to query the type and size of an
+  object of unknown type goes with the option.
+- `status` to `status_info`: the `changed`, `added`, `deleted`, and `untracked` readers
+  keep their names, but the categories are derived from both porcelain status
+  characters and clean tracked paths are no longer listed. Read the v5.x entry before
+  changing the call.
+- `g.branch(name)`: the string constructor could mis-split a remote-tracking name when
+  the remote name itself contains a slash (`remotes/team/upstream/main`). `branch_list`
+  resolves configured remote names and has no such limitation.
+
+### Deprecated in v6.0.0
+
+Both APIs below keep working in v6.0.0 and warn through `Git::Deprecation` every time
+they are used. A later major release removes them.
+
+#### `set_index` and `set_working` deprecated
+
+`Git::Repository#set_index` and `#set_working` rebind the receiver to another index
+file or working tree. They are the last mutable state on `Git::Repository`. Once
+they are gone, a repository object is bound at construction and never changes.
+Until then, the rebind retargets every object that holds the receiver, such as a
+`Git::Object`, a `Git::Log`, or a second caller that was handed the same
+repository. v6.0.0 keeps both methods but warns on every call through
+`Git::Deprecation`, and a later major release removes them. The warnings are:
+
+- `Git::Repository#set_index is deprecated and will be removed in a future major
+  release. Open a repository bound to the index instead: Git.open(dir, index: path)
+  or Git.bare(git_dir, index: path).`
+- `Git::Repository#set_working is deprecated and will be removed in a future major
+  release. Open a repository bound to the working tree instead: Git.open(work_dir,
+  repository: git_dir).`
+
+Open a repository bound to the index or working tree up front instead of rebinding
+it afterward. `Git.open` accepts `:index` and `:repository`, and `Git.bare` accepts
+`:index`:
+
+```ruby
+# instead of
+repo = Git.open('/path/to/repo')
+repo.set_index('/path/to/custom.index')
+
+# open the bound repository
+repo = Git.open('/path/to/repo', index: '/path/to/custom.index')
+
+# instead of
+repo = Git.bare('/srv/repo.git')
+repo.set_index('/tmp/scratch.index')
+
+# open the bound bare repository
+repo = Git.bare('/srv/repo.git', index: '/tmp/scratch.index')
+
+# instead of
+repo.set_working('/path/to/worktree')
+
+# open the bound repository
+repo = Git.open('/path/to/worktree', repository: '/path/to/repo/.git')
+```
+
+`Git.open` and `Git.bare` build the repository from scratch and carry over nothing
+the caller does not pass. A receiver opened with a custom `:index`, `:git_ssh`,
+`:binary_path`, or `:log` passes the same values again; `set_working` kept the
+receiver's index, so its replacement needs `:index` whenever that index was custom.
+When `:repository` is given without `:index`, the index resolves to
+`<repository>/index`.
+
+A replacement built from an existing object reads the paths back from it.
+`repo.repo`, `repo.dir`, and `repo.index` return the `.git` directory, working tree,
+and index file as `Pathname`s. A repository opened without `:index` has `repo.index`
+pointing at `<git dir>/index`, so passing it back is harmless. The repository exposes
+no public reader for `:git_ssh`, `:binary_path`, or `:log`, so a caller that opened
+with any of them passes the same values again from wherever they were first built:
+
+```ruby
+# instead of
+repo.set_working('/path/to/worktree')
+
+# rebind from an existing object, keeping its .git directory and index
+rebound = Git.open('/path/to/worktree',
+                   repository: repo.repo.to_s, index: repo.index.to_s,
+                   git_ssh: ssh_command, binary_path: git_binary, log: logger)
+```
+
+A caller that needs a copy of an existing object for the duration of a block, with
+every setting intact, uses `with_index` or `with_working` and the block parameter.
+The yielded repository keeps every setting the call does not replace: the logger,
+`git_ssh`, `binary_path`, and the receiver's working tree under `with_index` or its
+index under `with_working`:
+
+```ruby
+repo.with_working('/path/to/worktree') do |bound|
+  bound.add('.')
+end
+```
+
+`set_working(dir, must_exist: false)` has no replacement. `Git.open` and
+`with_working` both raise `ArgumentError` when the working directory does not exist,
+so a repository can no longer be bound to a directory that is created later. When the
+missing directory's parent exists, git runs commands that do not read the working
+tree, such as `rev_parse` or `current_branch`, and only commands that need the
+working tree fail until it exists; when the parent is missing too, git rejects every
+command with an invalid path error. Create the directory, then call `Git.open`. If
+your code needs the deferred bind, open an issue describing the use case; under
+ADR-0007 that becomes a feature request. `set_index(path, must_exist: false)` has no
+gap: the `:index` option is not checked for existence.
+
+#### `Git::GitExecuteError` deprecated
+
+`Git::GitExecuteError` has been a deprecated alias for `Git::Error` since v2.0.0 and
+has warned whenever it is rescued or instantiated since then. The warning now follows
+the project's deprecation policy: it names the replacement and says the alias is
+removed in a future major release, and this entry records it. The warning is:
+
+- `Git::GitExecuteError is deprecated and will be removed in a future major release.
+  Use Git::Error instead.`
+
+Replace every reference with `Git::Error`. The two constants name the same class, so a
+`rescue Git::Error` clause catches everything a `rescue Git::GitExecuteError` clause did.
+
+```ruby
+# instead of
+rescue Git::GitExecuteError => e
+
+# rescue the class directly
+rescue Git::Error => e
+```
 
 ---
 
@@ -60,25 +686,24 @@ To prepare:
 
 ### Overview
 
-v5.0.0 delivers a new internal architecture while keeping the v4.x API working
-for the vast majority of users. Most v4.x code requires **no changes** to run on
-v5.x.
+v5.0.0 replaces the internal architecture while keeping the v4.x API working
+for most users. Most v4.x code runs on v5.x without changes.
 
 The new architecture introduces a layered design (`Git::Commands`,
-`Git::Repository`, and associated parsers). Compatibility shims — deprecated
-forwarding methods that map old call patterns to the new API — ensure that v4.x
-code continues to work. These shims emit deprecation warnings that tell you
-exactly what to change and what will be eliminated in v6.0.0.
+`Git::Repository`, and associated parsers). Compatibility shims, deprecated
+forwarding methods that map old call patterns to the new API, keep v4.x code
+working. These shims emit deprecation warnings that tell you what to change and
+what v6.0.0 removes.
 
-Hard breaks are limited to a small number of things that had no safe migration
-path. These are described in the [Breaking changes](#breaking-changes) section,
-followed by [Deprecated methods](#deprecated-methods) that still work in v5.x
-but are removed in v6.0.0.
+Hard breaks are limited to the few things that had no safe migration path.
+The [Breaking changes](#breaking-changes) section describes them, followed by
+[Deprecated methods](#deprecated-methods) that still work in v5.x but are
+removed in v6.0.0.
 
-For information on how to suppress or configure deprecation warnings, see the
-[Deprecations](README.md#deprecations) section of the README.
+To suppress or configure deprecation warnings, see the [Deprecations](README.md#deprecations)
+section of the README.
 
-**Changes at a glance:**
+Changes at a glance:
 
 | Change | Type | Impact | Action required |
 |--------|------|--------|-----------------|
@@ -95,59 +720,57 @@ For information on how to suppress or configure deprecation warnings, see the
 
 #### `Git::Base` removed
 
-`Git::Base` — the class previously returned by `Git.open`, `Git.clone`,
-`Git.init`, and `Git.bare` — is removed in v5.0.0. The replacement is
-`Git::Repository`, which is returned by all four entry points and exposes the
-same public API.
+`Git::Base`, the class that `Git.open`, `Git.clone`, `Git.init`, and `Git.bare`
+returned, is removed in v5.0.0. All four entry points now return
+`Git::Repository`, which exposes the same public API.
 
-**Code that must be updated:**
+Code that must be updated:
 
 ```ruby
-# v4.x — explicit Git::Base reference (raises NameError in v5.x)
+# v4.x: explicit Git::Base reference (raises NameError in v5.x)
 repo = Git::Base.new(working_directory: '/path/to/repo')
 
-# v5.x — use the entry-point methods; do not construct Git::Repository directly
+# v5.x: use the entry-point methods; do not construct Git::Repository directly
 repo = Git.open('/path/to/repo')
 ```
 
 ```ruby
-# v4.x — type-checking against Git::Base (raises NameError in v5.x because Git::Base is removed)
+# v4.x: type-checking against Git::Base (raises NameError in v5.x because Git::Base is removed)
 raise unless repo.is_a?(Git::Base)
 
-# v5.x — check against Git::Repository
+# v5.x: check against Git::Repository
 raise unless repo.is_a?(Git::Repository)
 ```
 
 ```ruby
-# v4.x — requiring the internal file (raises LoadError in v5.x)
+# v4.x: requiring the internal file (raises LoadError in v5.x)
 require 'git/base'
 
-# v5.x — the public entry point is git itself; no internal require needed
+# v5.x: the public entry point is git itself; no internal require needed
 require 'git'
 ```
 
-**Public API is preserved:** `Git::Repository` provides every method that
-`Git::Base` did. Code that simply calls methods on the object returned by
-`Git.open` (e.g., `repo.commit`, `repo.status`, `repo.add`) requires no
-changes.
+**The public API is unchanged.** `Git::Repository` provides every method that
+`Git::Base` did. Code that calls methods on the object returned by `Git.open`
+(e.g., `repo.commit`, `repo.status`, `repo.add`) requires no changes.
 
-**Monkeypatching `Git::Base` is deprecated:** v5.x includes a temporary
+**Monkeypatching `Git::Base` is deprecated.** v5.x includes a temporary
 compatibility shim for applications that define instance methods on `Git::Base`.
-Those methods are made available on `Git::Repository` instances, but each method
-definition emits a deprecation warning and this shim will be removed in v6.0.0.
+The shim makes those methods available on `Git::Repository` instances, but each
+method definition emits a deprecation warning, and v6.0.0 removes the shim.
 
 Move custom repository helpers to an application-owned extension module and
 include or prepend that module into `Git::Repository` during application setup:
 
 ```ruby
-# Deprecated in v5.x and will be removed in v6.0.0
+# Deprecated in v5.x and removed in v6.0.0
 module Git::Base
   def worktree_clean?
     status.changed.empty?
   end
 end
 
-# v5.x — keep the extension in application-owned code
+# v5.x: keep the extension in application-owned code
 module MyAppGitRepositoryExtensions
   def worktree_clean?
     status.changed.empty?
@@ -164,9 +787,9 @@ Git::Repository.include(MyAppGitRepositoryExtensions)
 `Git.open`, `Git.clone`, `Git.init`, and `Git.bare` now return
 `Git::Repository` instead of `Git::Base`.
 
-For most callers this is transparent — the returned object responds to the same
-methods. Code that explicitly checks `is_a?(Git::Base)` or `be_a(Git::Base)` in
-tests must be updated:
+For most callers this is transparent, because the returned object responds to
+the same methods. Update code that checks `is_a?(Git::Base)` or `be_a(Git::Base)`
+in tests:
 
 ```ruby
 # v4.x
@@ -184,20 +807,26 @@ construct a repository object.
 
 #### Unsupported options raise `ArgumentError`
 
-v5.x validates options more strictly for factory methods and command APIs.
-Unknown options that were silently ignored in v4.x may now raise
-`ArgumentError`. Check option names against the documented API when upgrading,
-especially for calls that pass keyword options through helper methods or shared
-option hashes.
+In v5.x, only some APIs reject unknown options: `Git.clone`, `Git.ls_remote`,
+and most `Git::Repository` methods that accept an options hash (for example,
+`#add`) raise `ArgumentError` for option names they do not recognize. The
+factory methods `Git.init`, `Git.open`, and `Git.bare` do not validate option
+names in v5.x. All three reject unknown keys in v6.0.0 (see
+[`Git.init`, `Git.open`, and `Git.bare` reject unknown options](#gitinit-gitopen-and-gitbare-reject-unknown-options)).
+
+For APIs that validate options, names that v4.x silently ignored may raise
+`ArgumentError` in v5.x. Check option names against the documented API when
+upgrading, especially for calls that pass keyword options through helper
+methods or shared option hashes.
 
 For example, `Git.clone` supports `log:`, not `logger:`. A misspelled or
 unsupported option that v4.x ignored must be corrected:
 
 ```ruby
-# v4.x — silently ignored; did not configure clone logging
+# v4.x: silently ignored; did not configure clone logging
 Git.clone(url, path, logger: logger)
 
-# v5.x — use the documented option name
+# v5.x: use the documented option name
 Git.clone(url, path, log: logger)
 ```
 
@@ -210,31 +839,29 @@ exposed a `#lib` method that gave access to `Git::Lib`, the gem's internal
 implementation class. `Git::Lib` is removed in v5.0.0.
 
 In v5.x, calling `#lib` on a repo object returns `self` with a deprecation
-warning. This means `g.lib.some_method(args)` is forwarded to
-`g.some_method(args)` — but only if `some_method` exists on `Git::Repository`.
-Methods that were unique to `Git::Lib` and have no counterpart on
-`Git::Repository` raise `NoMethodError` immediately. The `#lib` method itself
-is removed in v6.0.0.
+warning, so `g.lib.some_method(args)` calls `g.some_method(args)`, but only if
+`some_method` exists on `Git::Repository`. Methods that were unique to `Git::Lib`
+and have no counterpart on `Git::Repository` raise `NoMethodError` immediately.
+The `#lib` method itself is removed in v6.0.0.
 
-Most public behavior previously accessible via `g.lib.*` is available directly
-on the repository object (`g.*`). See the tables below for every affected
-method.
+Most of what `g.lib.*` exposed is available directly on the repository object
+(`g.*`). See the tables below for every affected method.
 
-##### Methods that work via the `#lib` shim (with deprecation warning)
+##### Methods that work through the `#lib` shim (with deprecation warning)
 
 The following v4.x `g.lib.*` call shapes are forwarded to their `Git::Repository`
-counterpart by the `#lib → self` shim. They emit a deprecation warning; migrate
-to the replacement shown to silence it.
+counterpart by the `#lib` shim, which returns `self`. They emit a deprecation
+warning; migrate to the replacement shown to silence it.
 
-> **Note — config return type change:** `g.lib.config_get(name)` returned a
+> **Config return type change.** `g.lib.config_get(name)` returned a
 > `String`; `g.lib.config_list` returned a `Hash`.
 > The v5.x replacements `config_get` and `config_list` return
-> `Git::ConfigEntryInfo` and `Array<Git::ConfigEntryInfo>` respectively — richer
-> objects that expose `.value` (the String), `.key`, `.scope`, and `.origin`.
+> `Git::ConfigEntryInfo` and `Array<Git::ConfigEntryInfo>` respectively. Those
+> objects expose `.value` (the String), `.key`, `.scope`, and `.origin`.
 >
 > If you only need the String value:
-> - `g.config_get(name)&.value` → replaces `g.lib.config_get(name)`
-> - `g.config_list.to_h { |e| [e.key, e.value] }` → replaces `g.lib.config_list`
+> - `g.config_get(name)&.value` replaces `g.lib.config_get(name)`
+> - `g.config_list.to_h { |e| [e.key, e.value] }` replaces `g.lib.config_list`
 >
 > If your code was using the v4.x public `g.config(name)` API (not `g.lib.*`),
 > that deprecated bridge still returns a `String` in v5.x and continues to work
@@ -242,17 +869,17 @@ to the replacement shown to silence it.
 
 | v4.x call | Replacement in v5.x |
 |-----------|---------------------|
-| `g.lib.config_get(name)` | `g.config_get(name)` — returns `Git::ConfigEntryInfo`; use `.value` for the String |
-| `g.lib.config_list` | `g.config_list` — returns `Array<Git::ConfigEntryInfo>` |
+| `g.lib.config_get(name)` | `g.config_get(name)`. Returns `Git::ConfigEntryInfo`; use `.value` for the String |
+| `g.lib.config_list` | `g.config_list`. Returns `Array<Git::ConfigEntryInfo>` |
 | `g.lib.config_set(name, value)` | `g.config_set(name, value)` |
 | `g.lib.git_version` | `g.git_version` |
-| `g.lib.stash_list` | `g.stash_infos` — returns `Array<Git::StashInfo>`, newest first |
+| `g.lib.stash_list` | `g.stash_infos`. Returns `Array<Git::StashInfo>`, newest first |
 | `g.lib.unmerged` | `g.unmerged` |
 | `g.lib.change_head_branch(name)` | `g.change_head_branch(name)` |
 | `g.lib.ls_remote(location, opts)` | `g.ls_remote(location, opts)` |
 | `g.lib.current_branch_state` | `g.current_branch_state` |
 
-> **Note — `current_branch_state` return type change:** `g.lib.current_branch_state`
+> **`current_branch_state` return type change.** `g.lib.current_branch_state`
 > returned a `Git::Lib::HeadState` (a mutable `Struct`). `g.current_branch_state`
 > returns a `Git::Repository::Branching::HeadState` (an immutable `Data` object).
 > Both expose `.state` (`:active`, `:unborn`, or `:detached`) and `.name`. If your
@@ -263,8 +890,8 @@ to the replacement shown to silence it.
 ##### Methods that raise `NoMethodError` in v5.x
 
 These `Git::Lib` method names have no counterpart on `Git::Repository`, so
-`g.lib.method_name` raises `NoMethodError` even in v5.x (the `#lib → self`
-shim cannot forward them). Update call sites directly:
+`g.lib.method_name` raises `NoMethodError` even in v5.x because the `#lib` shim
+has nothing to forward them to. Update call sites directly:
 
 | v4.x call | Replacement in v5.x |
 |-----------|---------------------|
@@ -282,8 +909,8 @@ shim cannot forward them). Update call sites directly:
 
 ##### Internal plumbing methods (no replacement)
 
-The following methods were technically public on `Git::Lib` but are internal
-helpers with no plausible external use. They have no replacement in v5.0.0:
+The following methods were public on `Git::Lib` in name only. They are internal
+helpers with no plausible external use and have no replacement in v5.0.0:
 
 - `assert_args_are_not_options`
 - `assert_valid_opts`
@@ -307,15 +934,15 @@ filter log output by path when combined with `#between` or other revision range
 options. This relied on ambiguous `git log` argument handling and was not the
 intended API for path filtering.
 
-In v5.x, `Git::Log#object` should be treated as a revision expression. When both
-`#object` and `#between` are specified, `#between` takes precedence. Code that
-used `#object` to limit commits to a path should use `#path` instead.
+In v5.x, `Git::Log#object` is a revision expression. When both `#object` and
+`#between` are specified, `#between` takes precedence. Code that used `#object`
+to limit commits to a path should use `#path` instead.
 
 ```ruby
-# v4.x — ambiguous; could appear to filter commits touching this path
+# v4.x: ambiguous; could appear to filter commits touching this path
 git.log(500).object('cookbooks/mycookbook').between('1.0.0', 'HEAD').execute
 
-# v5.x — use #path for path filtering
+# v5.x: use #path for path filtering
 git.log(500).path('cookbooks/mycookbook').between('1.0.0', 'HEAD').execute
 
 # #object remains appropriate for revision expressions
@@ -339,19 +966,25 @@ result.is_a?(Git::CommandLine::Result)
 ```
 
 This change is only relevant if your code references `Git::CommandLineResult`
-by name (typically in type checks or documentation). Code that simply uses the
-result object returned by git commands is unaffected.
+by name (typically in type checks or documentation). Code that uses the result
+object returned by git commands is unaffected.
 
 ---
 
 ### Deprecated methods
 
 The following methods are available in v5.x with deprecation warnings and are
-removed in v6.0.0. Migrate to the replacement shown to silence the warnings.
+removed in v6.0.0. Migrate to the replacement shown to silence the warnings. The
+[Removed APIs](#removed-apis) table under "Upgrading to v6.x" indexes these entries.
+
+`Git::GitExecuteError` is not listed here because v6.0.0 keeps it. It has warned since
+v2.0.0 and still warns in v6.0.0; see [`Git::GitExecuteError`
+deprecated](#gitgitexecuteerror-deprecated) under "Upgrading to v6.x" for the
+replacement.
 
 #### Facade method renames
 
-Five methods were renamed to follow the project's `noun_verb` naming convention.
+v5.x renamed five methods to follow the project's `noun_verb` naming convention.
 The old names continue to work but emit deprecation warnings:
 
 | Deprecated call (works in v5.x, removed in v6.0.0) | Replacement |
@@ -364,11 +997,11 @@ The old names continue to work but emit deprecation warnings:
 
 #### `Git::Repository` method renames
 
-Seven more `Git::Repository` methods were renamed in v5.x. The old names continue
-to work but emit deprecation warnings. Each old name returns exactly what its
+v5.x renamed seven more `Git::Repository` methods. The old names continue to work
+but emit deprecation warnings. Each old name returns exactly what its
 replacement returns, except `branches_all`.
 
-> **Return shape change:** `g.branches_all` returns an `Array` of 4-element
+> **Return shape change.** `g.branches_all` returns an `Array` of 4-element
 > tuples `[refname, current, worktree, symref]`, where `refname` is the short
 > form (`main` or `remotes/origin/main`), `current` and `worktree` are booleans,
 > and `symref` is the symbolic-ref target or `nil`. `g.branch_list` returns
@@ -386,14 +1019,36 @@ replacement returns, except `branches_all`.
 
 | Deprecated call (works in v5.x, removed in v6.0.0) | Replacement |
 |-----------------------------------------------------|-------------|
-| `g.empty?` | `g.no_commits?` — `true` when the repository has no commits |
-| `g.reset_hard` | `g.reset(nil, hard: true)` — `reset` takes the commitish positionally, so pass `nil` before the options; returns git's stdout, as `reset_hard` did |
-| `g.reset_hard(commitish)` | `g.reset(commitish, hard: true)` — `reset_hard` ignored any `:hard` option passed to it and always reset with `--hard` |
-| `g.conflicts { \|file, yours, theirs\| ... }` | `g.each_conflict { \|file, yours, theirs\| ... }` — same block arguments; returns the unmerged paths |
+| `g.empty?` | `g.no_commits?`. `true` when the repository has no commits |
+| `g.reset_hard` | `g.reset(nil, hard: true)`. `reset` takes the commitish positionally, so pass `nil` before the options; returns git's stdout, as `reset_hard` did |
+| `g.reset_hard(commitish)` | `g.reset(commitish, hard: true)`. `reset_hard` ignored any `:hard` option passed to it and always reset with `--hard` |
+| `g.conflicts { \|file, yours, theirs\| ... }` | `g.each_conflict { \|file, yours, theirs\| ... }`. Same block arguments; returns the unmerged paths |
 | `g.is_local_branch?(name)` | `g.local_branch?(name)` |
 | `g.is_remote_branch?(name)` | `g.remote_branch?(name)` |
 | `g.is_branch?(name)` | `g.branch?(name)` |
-| `g.branches_all` | `g.branch_list` — returns `Array<Git::BranchInfo>`; see the return shape change above |
+| `g.branches_all` | `g.branch_list`. Returns `Array<Git::BranchInfo>`; see the return shape change above |
+
+#### `Git::Repository` alias renames
+
+Eight `Git::Repository` methods have a second, older name carried over from v4.x.
+Releases before v5.7.0 kept the older names as aliases with no warning. From
+v5.7.0 on, each old name emits a deprecation warning. Each old name takes the
+same arguments and returns exactly what its replacement returns.
+
+> **`diff_name_status`:** a `:path` option emits its own deprecation warning
+> after the method-name warning. Pass `:path_limiter` instead, as described
+> under [`Git::Repository` option renames](#gitrepository-option-renames) below.
+
+| Deprecated call (works in v5.x, removed in v6.0.0) | Replacement |
+|-----------------------------------------------------|-------------|
+| `g.object_contents(object)` | `g.cat_file_contents(object)` |
+| `g.object_size(object)` | `g.cat_file_size(object)` |
+| `g.object_type(object)` | `g.cat_file_type(object)` |
+| `g.commit_data(object)` | `g.cat_file_commit(object)` |
+| `g.tag_data(object)` | `g.cat_file_tag(object)` |
+| `g.revparse(objectish)` | `g.rev_parse(objectish)` |
+| `g.namerev(commit_ish)` | `g.name_rev(commit_ish)` |
+| `g.diff_name_status(from, to, opts)` | `g.diff_path_status(from, to, opts)` |
 
 #### `Git::Repository` option renames
 
@@ -401,7 +1056,7 @@ Five methods accept a v4.x option or positional argument under its old name.
 The old form still works in v5.x but emits a deprecation warning and is
 translated to the v5.x form shown below.
 
-> **`clean`:** `force: 2` runs `git clean -ff`, which also removes untracked
+> **`clean`.** `force: 2` runs `git clean -ff`, which also removes untracked
 > nested git repositories. A `false` or `nil` value for `:ff` or `:force_force`
 > still warns and has no effect; a value other than `true`, `false`, or `nil`
 > raises `ArgumentError`. When the deprecated key is `true` and a valid
@@ -410,11 +1065,11 @@ translated to the v5.x form shown below.
 > unchanged and still raises `ArgumentError`; the deprecated key does not mask
 > it.
 
-> **`diff_path_status`:** `:path_limiter` accepts the same values as `:path`
+> **`diff_path_status`.** `:path_limiter` accepts the same values as `:path`
 > (a `String`, a `Pathname`, or an `Array` of them). When both keys are given,
 > `:path_limiter` wins and no warning is emitted.
 
-> **`set_working` and `set_index`:** `must_exist:` defaults to `true`. When
+> **`set_working` and `set_index`.** `must_exist:` defaults to `true`. When
 > both the positional argument and `must_exist:` are given, they are OR'ed so
 > the more restrictive value wins.
 
@@ -423,39 +1078,39 @@ translated to the v5.x form shown below.
 | `g.clean(ff: true)` | `g.clean(force: 2)` |
 | `g.clean(force_force: true)` | `g.clean(force: 2)` |
 | `g.diff_path_status(ref1, ref2, path: p)` | `g.diff_path_status(ref1, ref2, path_limiter: p)` |
-| `g.commit(message, add_all: true)` | `g.commit(message, all: true)` — runs `git commit -a` |
+| `g.commit(message, add_all: true)` | `g.commit(message, all: true)`. Runs `git commit -a` |
 | `g.set_working(dir, check)` | `g.set_working(dir, must_exist: check)` |
 | `g.set_index(file, check)` | `g.set_index(file, must_exist: check)` |
 
 #### v4.x-style configuration methods
 
 The v4.x `config` and `global_config` methods accepted varying argument shapes
-to read, write, or list configuration. These are replaced by separate,
+to read, write, or list configuration. v5.x replaces them with separate,
 purpose-named methods. The same applies to the module-level
-`Git.global_config`, which is replaced by `Git.config_get`, `Git.config_set`,
+`Git.global_config`, whose replacements are `Git.config_get`, `Git.config_set`,
 and `Git.config_list` called with `global: true`.
 
-> **Return type change:** The v4.x `g.config(name)` and `Git.global_config(name)`
+> **Return type change.** The v4.x `g.config(name)` and `Git.global_config(name)`
 > returned a `String`; `g.config` and `Git.global_config` returned a `Hash`. The
 > v5.x replacements `config_get` and `config_list` return `Git::ConfigEntryInfo`
 > (or `nil` when the key is not set) and `Array<Git::ConfigEntryInfo>`
 > respectively. Use `.value` to get the String value:
-> - `g.config_get(name)&.value` → String or nil
-> - `g.config_list.to_h { |e| [e.key, e.value] }` → Hash (key → value)
+> - `g.config_get(name)&.value` returns a String or nil
+> - `g.config_list.to_h { |e| [e.key, e.value] }` returns a Hash of key to value
 >
 > The setters `g.config(name, value)` and `Git.global_config(name, value)`
 > returned the raw command result; `config_set` returns `nil`.
 
 | Deprecated call (works in v5.x, removed in v6.0.0) | Replacement |
 |-----------------------------------------------------|-------------|
-| `g.config(name)` | `g.config_get(name)` — returns `Git::ConfigEntryInfo`; use `.value` for the String |
-| `g.config` | `g.config_list` — returns `Array<Git::ConfigEntryInfo>` |
+| `g.config(name)` | `g.config_get(name)`. Returns `Git::ConfigEntryInfo`; use `.value` for the String |
+| `g.config` | `g.config_list`. Returns `Array<Git::ConfigEntryInfo>` |
 | `g.config(name, value)` | `g.config_set(name, value)` |
 | `g.global_config(name)` | `g.config_get(name, global: true)` |
 | `g.global_config` | `g.config_list(global: true)` |
 | `g.global_config(name, value)` | `g.config_set(name, value, global: true)` |
-| `Git.global_config(name)` | `Git.config_get(name, global: true)` — returns `Git::ConfigEntryInfo` or `nil`; use `.value` for the String |
-| `Git.global_config` | `Git.config_list(global: true)` — returns `Array<Git::ConfigEntryInfo>` |
+| `Git.global_config(name)` | `Git.config_get(name, global: true)`. Returns `Git::ConfigEntryInfo` or `nil`; use `.value` for the String |
+| `Git.global_config` | `Git.config_list(global: true)`. Returns `Array<Git::ConfigEntryInfo>` |
 | `Git.global_config(name, value)` | `Git.config_set(name, value, global: true)` |
 
 #### `Git` module mixin deprecations
@@ -489,7 +1144,7 @@ legacy type that is deprecated:
 - `Git.binary_version` is replaced by `Git.git_version`, which keeps the
   optional binary path argument.
 
-> **Return type change:** `Git.binary_version` returned an `Array<Integer>` of
+> **Return type change.** `Git.binary_version` returned an `Array<Integer>` of
 > `[major, minor, patch]`. `Git.git_version` returns a `Git::Version`, which
 > supports comparison and exposes `major`, `minor`, and `patch`.
 > `Git.git_version.to_a` reproduces the legacy array. The return value of
@@ -499,19 +1154,20 @@ legacy type that is deprecated:
 |-----------------------------------------------------|-------------|
 | `Git.ls_remote(nil)` | `Git.ls_remote` or `Git.ls_remote('.')` |
 | `Git.ls_remote(nil, opts)` | `Git.ls_remote('.', opts)` |
-| `Git.binary_version` | `Git.git_version` — returns `Git::Version`; use `.to_a` for the `[major, minor, patch]` Array |
+| `Git.binary_version` | `Git.git_version`. Returns `Git::Version`; use `.to_a` for the `[major, minor, patch]` Array |
 | `Git.binary_version(binary_path)` | `Git.git_version(binary_path)` |
 
 #### `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`.
+Starting in v5.3.0, the methods that return author, committer, or tagger data
+return an immutable `Git::AuthorInfo` value object instead of the mutable
+`Git::Author`. Those methods are `Git::Object::Commit#author`,
+`Git::Object::Commit#committer`, `Git::Object::Tag#tagger`, and
+`Git::TagInfo#tagger`.
 
 `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::Author` through `name=`, `email=`, or `date=` has to change.
 `Git::AuthorInfo` is frozen, and `#with` returns a modified copy rather than
 updating in place (e.g. `info = info.with(name: 'New Name')`).
 
@@ -530,7 +1186,7 @@ in the repository, so `g.branch('feature').stashes` and `g.branch('main').stashe
 return the same entries. Call `Git::Repository#stash_infos` instead; it is the
 query `Git::Branch#stashes` was already running.
 
-> **Return type change:** `Git::Branch#stashes` returns a `Git::Stashes`
+> **Return type change.** `Git::Branch#stashes` returns a `Git::Stashes`
 > collection of `Git::Stash` objects. `g.stash_infos` returns an array of
 > `Git::StashInfo` values. Both are newest first, so indexes carry over unchanged.
 > `Git::Stash#message` strips the `WIP on <branch>:` or `On <branch>:` prefix;
@@ -546,15 +1202,15 @@ its methods.
 
 | Deprecated call (works in v5.x, removed in v6.0.0) | Replacement |
 |-----------------------------------------------------|-------------|
-| `g.branch(name).stashes` | `g.stash_infos` — returns `Array<Git::StashInfo>`, newest first |
+| `g.branch(name).stashes` | `g.stash_infos`. Returns `Array<Git::StashInfo>`, newest first |
 | `g.branch(name).stashes.each { \|s\| puts s.message }` | `g.stash_infos.each { \|info\| puts info.message }` |
-| `g.branch(name).stashes.all` (`[index, message]` pairs, oldest first) | `g.stash_infos.reverse` — see the ordering note in [Legacy stash API deprecated](#legacy-stash-api-deprecated) |
+| `g.branch(name).stashes.all` (`[index, message]` pairs, oldest first) | `g.stash_infos.reverse`. See the ordering note in [Legacy stash API deprecated](#legacy-stash-api-deprecated) |
 | `g.branch(name).stashes.size` | `g.stash_infos.size` |
 | `g.branch(name).stashes[i].message` (`0` = newest, `i` coerced with `to_i`) | `g.stash_infos[i.to_i].message` |
 | `g.branch(name).stashes.save(message)` | `g.stash_push(message: 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` — returns git's stdout (normally `""`, which is truthy) where `Git::Stashes#clear` returned `nil` |
+| `g.branch(name).stashes.clear` | `g.stash_clear`. Returns git's stdout (normally `""`, which is truthy) where `Git::Stashes#clear` returned `nil` |
 
 #### Legacy stash API deprecated
 
@@ -571,14 +1227,14 @@ The legacy methods and classes are deprecated and removed in v6.0.0:
 `Git::Repository#stash_list`, `Git::Stash`, and `Git::Stashes`. Constructing a
 `Git::Stash` or `Git::Stashes` emits one warning per object.
 
-> **Ordering flip:** `g.stashes_all` returns entries **oldest first** with a
+> **Ordering flip.** `g.stashes_all` returns entries oldest first with a
 > sequential index of its own (`0` is the oldest). `g.stash_infos` returns entries
-> **newest first**, the order `git stash list` uses, and `Git::StashInfo#index` is
+> newest first, the order `git stash list` uses, and `Git::StashInfo#index` is
 > git's own `stash@{N}` number (`0` is the newest). `g.stashes_all.first` is
 > `g.stash_infos.last`. Code that reads an entry by position must reverse the
 > array or the index.
 
-> **Message difference:** `g.stashes_all` strips the `WIP on <branch>:` or
+> **Message difference.** `g.stashes_all` strips the `WIP on <branch>:` or
 > `On <branch>:` prefix from each message. `Git::StashInfo#message` keeps the full
 > message git stores, and `Git::StashInfo#branch` holds the branch name. A stash
 > created from a detached HEAD has the branch `"(no branch)"`, the label git writes
@@ -591,32 +1247,38 @@ new `Git::StashInfo`, or `nil` when there were no local changes, so a truthiness
 check such as `if g.stash_push(message: 'WIP')` still works.
 
 `g.stash_list` returned the `git stash list` text as a String. Build that text from
-`g.stash_infos` if you need it. In v6.0.0, `stash_list` returns
-`Array<Git::StashInfo>`, the same value as `stash_infos`, and `stash_infos` stays as
-a permanent alias. Move String callers of `stash_list` to `stash_infos` before
-upgrading so the return type change cannot go unnoticed.
+`g.stash_infos` if you need it. In v6.0.0 `stash_list` returns what `stash_infos`
+returns (see [`stash_list` returns an Array of
+`Git::StashInfo`](#stash_list-returns-an-array-of-gitstashinfo)), so move String
+callers of `stash_list` to `stash_infos` before upgrading so the return type change
+cannot go unnoticed.
+
+> **`stash_store` in v6.0.0.** On v5.x, `g.stash_store` returns the top entry of
+> the stash list after the store, which is `nil` when the list is empty. v6.0.0
+> changes that; see [`stash_store` raises when the stored entry is
+> missing](#stash_store-raises-when-the-stored-entry-is-missing).
 
 | Deprecated call (works in v5.x, removed in v6.0.0) | Replacement |
 |-----------------------------------------------------|-------------|
-| `g.stashes_all` | `g.stash_infos` — returns `Array<Git::StashInfo>`, newest first |
+| `g.stashes_all` | `g.stash_infos`. Returns `Array<Git::StashInfo>`, newest first |
 | `g.stashes_all.each { \|index, message\| ... }` | `g.stash_infos.reverse_each.with_index { \|info, index\| ... info.message }` |
 | `g.stashes_all[i]` (`0` = oldest) | `g.stash_infos.reverse[i]` |
 | `g.stashes_all.last` | `g.stash_infos.first` |
-| `g.stash_save(message)` | `g.stash_push(message: message)` — returns `Git::StashInfo` or `nil` |
+| `g.stash_save(message)` | `g.stash_push(message: message)`. Returns `Git::StashInfo` or `nil` |
 | `g.stash_list` (String) | `g.stash_infos.map { \|s\| "#{s.name}: #{s.message}" }.join("\n")` |
 | `Git::Stash.new(g, message)` | `info = g.stash_push(message: message)` |
-| `Git::Stash.new(g, message, existing: true)` | `message` — `existing: true` only wrapped the String and never looked an entry up; code that needs a real entry picks one from `g.stash_infos` by index or name |
+| `Git::Stash.new(g, message, existing: true)` | `message`. `existing: true` only wrapped the String and never looked an entry up; code that needs a real entry picks one from `g.stash_infos` by index or name |
 | `stash.save` | `info = g.stash_push(message: message)` |
-| `stash.saved?` | `!info.nil?` — check the value `stash_push` returned rather than pushing again |
-| `stash.message` / `stash.to_s` | `info.message` — keeps the branch prefix; see the note above |
+| `stash.saved?` | `!info.nil?`. Check the value `stash_push` returned rather than pushing again |
+| `stash.message` / `stash.to_s` | `info.message`. Keeps the branch prefix; see the note above |
 | `Git::Stashes.new(g)` | `g.stash_infos` |
-| `stashes.all` (`[index, message]` pairs, oldest first) | `g.stash_infos.reverse` — see the ordering note above |
+| `stashes.all` (`[index, message]` pairs, oldest first) | `g.stash_infos.reverse`. See the ordering note above |
 | `stashes.each { \|s\| ... }` (newest first) | `g.stash_infos.each { \|info\| ... }` |
 | `stashes[i]` (`0` = newest, `i` coerced with `to_i`) | `g.stash_infos[i.to_i]` |
 | `stashes.size` | `g.stash_infos.size` |
 | `stashes.save(message)` | `g.stash_push(message: message)` |
 | `stashes.apply` / `stashes.apply(i)` | `g.stash_apply` / `g.stash_apply(i)` |
-| `stashes.clear` | `g.stash_clear` — returns git's stdout (normally `""`, which is truthy) where `Git::Stashes#clear` returned `nil` |
+| `stashes.clear` | `g.stash_clear`. Returns git's stdout (normally `""`, which is truthy) where `Git::Stashes#clear` returned `nil` |
 
 #### `Git::Repository#remotes` deprecated
 
@@ -626,10 +1288,10 @@ one deprecation warning for itself plus one `Git::Remote` constructor warning fo
 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
+> **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
+> `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
@@ -637,27 +1299,28 @@ with N remotes produces N + 1 warnings per call.
 > 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.
+> `Git::Remote` are called on the repository instead; the table below shows
+> the argument each one takes.
 >
-> **Order change:** `remotes` lists remotes in the order `git remote` prints
+> **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` | `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` |
+| `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.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.branch` | `g.branch_list("#{remote.name}/#{g.current_branch}").find(&:remote?)`. Returns a `Git::BranchInfo` |
+| `remote.branch(name)` | `g.branch_list("#{remote.name}/#{name}").find(&:remote?)`. Returns a `Git::BranchInfo` |
 | `remote.remove` | `g.remote_remove(remote.name)` |
 
 #### `Git::Remote` deprecated
@@ -665,15 +1328,15 @@ with N remotes produces N + 1 warnings per call.
 `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
+remote; the table below shows the replacement for each operation. 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
@@ -686,26 +1349,27 @@ warnings from `g.remote` and `g.remotes` are expected, not a bug.
 > 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.
+> `g.branch_list("#{name}/#{branch}").find(&:remote?)`, 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}` |
+| `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.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.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.branch` | `g.branch_list("#{name}/#{g.current_branch}").find(&:remote?)`. Returns a `Git::BranchInfo` |
+| `remote.branch(branch)` | `g.branch_list("#{name}/#{branch}").find(&:remote?)`. Returns a `Git::BranchInfo` |
 | `remote.remove` | `g.remote_remove(name)` |
 
 #### `Git::Commands::CatFile::Raw` `allow_unknown_type` option deprecated
@@ -735,12 +1399,14 @@ that constructs the command class directly is affected.
 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
+`in_branch`, and so on) with the branch name. For a remote-tracking branch the
+argument differs by operation; the table below shows the form each one takes.
+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
@@ -751,7 +1417,7 @@ emit a deprecation warning; their return values are unchanged. The `full`,
 > `'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
+> **`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
@@ -797,33 +1463,33 @@ can resolve a local branch of that name and is only used where git expects it
 
 | 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.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` |
+| `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.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.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.stash_infos` — see [`Git::Branch#stashes` deprecated](#gitbranchstashes-deprecated) |
+| `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.stash_infos`. See [`Git::Branch#stashes` deprecated](#gitbranchstashes-deprecated) |
 
 #### `Git::Object::Tag` deprecated
 
@@ -842,7 +1508,7 @@ for the `g.tag_add` it calls; `g.add_tag(name, d: true)` emits three, adding the
 `:d`/`:delete` warning described below. The readers on a `Git::Object::Tag` do not
 warn.
 
-> **Return shape change:** `Git::Object::Tag` exposes `name`, `sha`, `objectish`,
+> **Return shape change.** `Git::Object::Tag` exposes `name`, `sha`, `objectish`,
 > `annotated?`, `message`, and `tagger`. `Git::TagInfo` exposes `name`, `oid`,
 > `target_oid`, `objecttype`, `annotated?`, `lightweight?`, `message`, and
 > `tagger`. `name` and `annotated?` are unchanged. `tagger` keeps the same `name`
@@ -860,18 +1526,23 @@ warn.
 > which kind (`tag` for an annotated tag, or the target's own type such as
 > `commit` or `blob` for a lightweight one).
 >
-> **Missing tags:** `g.tag(name)` raises `Git::UnexpectedResultError` when no tag
+> **Missing tags.** `g.tag(name)` raises `Git::UnexpectedResultError` when no tag
 > has that name. `g.tag_list(name).first` returns `nil`.
 >
-> **Deleting through `tag_add`:** `g.tag_add(name, d: true)`, which was already
+> **`tag_create` in v6.0.0.** On v5.x, `g.tag_create` returns `nil` when the tag it
+> has just created is missing from the tag list. v6.0.0 raises instead; see
+> [`tag_create` raises when the created tag is
+> missing](#tag_create-raises-when-the-created-tag-is-missing).
+>
+> **Deleting through `tag_add`.** `g.tag_add(name, d: true)`, which was already
 > deprecated, deletes the tag and emits a second warning pointing at
 > `g.tag_delete`. `g.tag_create` rejects `:d` and `:delete` with `ArgumentError`.
 >
-> **Extra positional arguments:** `g.tag_add(name, target, extra)` ignores
+> **Extra positional arguments.** `g.tag_add(name, target, extra)` ignores
 > `extra` and tags `target`. `g.tag_create` raises `ArgumentError` when more than
 > one positional argument follows the name.
 >
-> **Object identity:** every `Git::Object::Tag` resolves its tag to an object ID
+> **Object identity.** Every `Git::Object::Tag` resolves its tag to an object ID
 > when it is constructed and runs `size`, `contents`, `grep`, `diff`, `log`, and
 > `archive` against that ID, so moving or deleting the tag afterwards does not
 > redirect an existing object. `Git::Object::Tag.new(g, sha, name)` uses the
@@ -890,26 +1561,26 @@ In the table, `name` is the tag name, `t` is a `Git::Object::Tag`, `info` is the
 
 | Deprecated call (works in v5.x, removed in v6.0.0) | Replacement |
 |-----------------------------------------------------|-------------|
-| `g.tag(name)` | `g.tag_list(name).first` — a `Git::TagInfo`, or `nil` when the tag does not exist |
-| `g.tags` | `g.tag_list` — returns `Array<Git::TagInfo>` |
+| `g.tag(name)` | `g.tag_list(name).first`. A `Git::TagInfo`, or `nil` when the tag does not exist |
+| `g.tags` | `g.tag_list`. Returns `Array<Git::TagInfo>` |
 | `g.tags.map(&:name)` | `g.tag_list.map(&:name)` |
-| `g.tag_add(name, opts)` | `g.tag_create(name, opts)` — returns a `Git::TagInfo` |
+| `g.tag_add(name, opts)` | `g.tag_create(name, opts)`. Returns a `Git::TagInfo` |
 | `g.tag_add(name, target, opts)` | `g.tag_create(name, target, opts)` |
 | `g.tag_add(name, d: true)` | `g.tag_delete(name)` |
-| `g.add_tag(name, opts)`, `g.add_tag(name, target, opts)` | `g.tag_create(name, ...)` — its warning names `g.tag_add`, which is deprecated too; go straight to `g.tag_create` |
-| `g.add_tag(name, d: true)` | `g.tag_delete(name)` — `g.tag_create` rejects `:d`; see the deletion note above |
+| `g.add_tag(name, opts)`, `g.add_tag(name, target, opts)` | `g.tag_create(name, ...)`. Its warning names `g.tag_add`, which is deprecated too; go straight to `g.tag_create` |
+| `g.add_tag(name, d: true)` | `g.tag_delete(name)`. `g.tag_create` rejects `:d`; see the deletion note above |
 | `Git::Object::Tag.new(g, name)` | `g.tag_list(name).first` |
-| `Git::Object::Tag.new(g, sha, name)` | `g.tag_list(name).first` — reads the ref rather than `sha`; use `sha` as `id` for the operations below, or read the object with `g.cat_file_tag(sha)`; see the object identity note above |
-| `Git::Object.new(g, name, nil, true)` | `g.tag_list(name).first` — its warning names `Git::Object::Tag.new`, which is deprecated too |
+| `Git::Object::Tag.new(g, sha, name)` | `g.tag_list(name).first`. Reads the ref rather than `sha`; use `sha` as `id` for the operations below, or read the object with `g.cat_file_tag(sha)`; see the object identity note above |
+| `Git::Object.new(g, name, nil, true)` | `g.tag_list(name).first`. Its warning names `Git::Object::Tag.new`, which is deprecated too |
 | `t.name` | `info.name` |
-| `t.sha`, `t.objectish`, `t.to_s` | `info.oid \|\| info.target_oid` — see the return shape change above |
+| `t.sha`, `t.objectish`, `t.to_s` | `info.oid \|\| info.target_oid`. See the return shape change above |
 | `t.annotated?` | `info.annotated?` |
-| `t.message` | `info.message` — `nil` rather than `""` for an annotated tag with an empty message |
-| `t.tagger` | `info.tagger` — `date` keeps the recorded UTC offset; see the return shape change above |
+| `t.message` | `info.message`. `nil` rather than `""` for an annotated tag with an empty message |
+| `t.tagger` | `info.tagger`. `date` keeps the recorded UTC offset; see the return shape change above |
 | `t.tag?` | not needed; every `Git::TagInfo` is a tag |
-| `t.size` | `g.cat_file_size(id)` — `id` rather than `name` keeps this and the operations below on the object `t` pinned; see the object identity note above |
+| `t.size` | `g.cat_file_size(id)`. `id` rather than `name` keeps this and the operations below on the object `t` pinned; see the object identity note above |
 | `t.contents` | `g.cat_file_contents(id)` |
-| `t.contents { \|file\| ... }` | `g.cat_file_contents(id) { \|file\| ... }` — streams to a temporary file instead of buffering the object |
+| `t.contents { \|file\| ... }` | `g.cat_file_contents(id) { \|file\| ... }`. Streams to a temporary file instead of buffering the object |
 | `t.contents_array` | `g.cat_file_contents(id).split("\n")` |
 | `t.grep(string, path, opts)` | `g.grep(string, path, opts.merge(object: id))` |
 | `t.diff(other)` | `g.diff(id, other)` |
@@ -919,7 +1590,7 @@ In the table, `name` is the tag name, `t` is a `Git::Object::Tag`, `info` is the
 #### `Git::Status` deprecated
 
 Starting in v5.4.0, `Git::Status`, `Git::Status::StatusFile`, and
-`Git::Repository#status` are deprecated and will be removed in v6.0.0. Read the
+`Git::Repository#status` are deprecated and are removed in v6.0.0. Read the
 index and working tree state through `Git::Repository#status_info`, which
 returns an immutable `Git::StatusInfo` holding one `Git::StatusFileInfo` per
 path that `git status --porcelain=v2` reports. Calling `g.status` emits one
@@ -964,7 +1635,7 @@ reference, so `blob` is gone; fetch the object through the repository instead.
 `stage` is gone too: an unmerged entry carries its stage 1, 2, and 3 modes and
 SHAs in `unmerged_stages`, and every other entry is at stage 0.
 
-> **Field renames:** the legacy mode and SHA readers were named for the wrong
+> **Field renames.** The legacy mode and SHA readers were named for the wrong
 > sides. `sha_index` and `mode_index` held the working-tree side of the diff:
 > the index blob when the working tree matched the index, and an all-zero SHA
 > when it did not. `sha_repo` and `mode_repo` held the side git compared the
@@ -982,12 +1653,12 @@ In the table, `g` is a `Git::Repository`, `status` is the `Git::Status` from
 
 | Deprecated call (works in v5.x, removed in v6.0.0) | Replacement |
 |-----------------------------------------------------|-------------|
-| `g.status` | `g.status_info` — returns a `Git::StatusInfo` |
+| `g.status` | `g.status_info`. Returns a `Git::StatusInfo` |
 | `Git::Status.new(g)` | `g.status_info` |
-| `status.changed`, `status.added`, `status.deleted`, `status.untracked` | same names on `g.status_info` — now `Hash{String => Git::StatusFileInfo}` keyed by path |
+| `status.changed`, `status.added`, `status.deleted`, `status.untracked` | same names on `g.status_info`. Now `Hash{String => Git::StatusFileInfo}` keyed by path |
 | `status.changed?(path)`, `status.added?(path)`, `status.deleted?(path)`, `status.untracked?(path)` | same names on `g.status_info` |
-| `status[path]` | `g.status_info[path]` — a `Git::StatusFileInfo`, or `nil`; `nil` for a clean tracked path, which `status[path]` reported (see above) |
-| `status.each { \|file\| ... }` | `g.status_info.files.each { \|info\| ... }` — does not yield clean tracked paths (see above) |
+| `status[path]` | `g.status_info[path]`. A `Git::StatusFileInfo`, or `nil`; `nil` for a clean tracked path, which `status[path]` reported (see above) |
+| `status.each { \|file\| ... }` | `g.status_info.files.each { \|info\| ... }`. Does not yield clean tracked paths (see above) |
 | `status.pretty` | no replacement; format `g.status_info.files` yourself |
 | `file.path` | `info.path` |
 | `file.type` | `info.index_status` and `info.worktree_status`, or the `info.changed?`, `info.added?`, and `info.deleted?` predicates |
@@ -997,8 +1668,8 @@ In the table, `g` is a `Git::Repository`, `status` is the `Git::Status` from
 | `file.mode_repo` | `info.mode_head`, or `info.mode_index` in a repository with no commits |
 | `file.sha_index` | `info.sha_index` for the staged blob; `info.worktree_status` says whether the working tree differs from it |
 | `file.mode_index` | `info.mode_worktree` |
-| `file.blob` | `g.object(info.sha_index)` when `info.sha_index` is set and not all zeros — it is `nil` for untracked, ignored, and unmerged entries and all zeros when the path is not in the index; legacy `blob` returned `nil` without a lookup when no SHA was available and fell back to `sha_repo` when `sha_index` was `nil`. For an unmerged entry read a stage instead: `g.object(info.unmerged_stages[2][:sha])` |
-| `file.blob(:repo)` | `g.object(info.sha_head)` when `info.sha_head` is set and not all zeros — it is `nil` for untracked, ignored, and unmerged entries and all zeros when the path is not in HEAD |
+| `file.blob` | `g.object(info.sha_index)` when `info.sha_index` is set and not all zeros. It is `nil` for untracked, ignored, and unmerged entries and all zeros when the path is not in the index; legacy `blob` returned `nil` without a lookup when no SHA was available and fell back to `sha_repo` when `sha_index` was `nil`. For an unmerged entry read a stage instead: `g.object(info.unmerged_stages[2][:sha])` |
+| `file.blob(:repo)` | `g.object(info.sha_head)` when `info.sha_head` is set and not all zeros. It is `nil` for untracked, ignored, and unmerged entries and all zeros when the path is not in HEAD |
 
 #### `Git::Worktree` and `Git::Worktrees` deprecated
 
@@ -1009,7 +1680,7 @@ and are removed in v6.0.0. Read worktree data through
 object per worktree, and call the repository-level operations (`worktree_add`,
 `worktree_remove`, `worktree_move`, `worktree_lock`, `worktree_unlock`,
 `worktree_repair`, and `worktree_prune`) with the worktree path or its
-`Git::WorktreeInfo`. Return values are unchanged. Calling `g.worktree`,
+`Git::WorktreeInfo`. Return values are unchanged on v5.x. Calling `g.worktree`,
 `g.worktrees`, or `g.worktrees_all`, constructing a `Git::Worktrees`, and calling
 `gcommit`, `add`, or `remove` on a `Git::Worktree` each emit a deprecation
 warning; the `dir`, `full`, `to_s`, and `to_a` readers on `Git::Worktree` do not.
@@ -1017,7 +1688,7 @@ warning; the `dir`, `full`, `to_s`, and `to_a` readers on `Git::Worktree` do not
 it constructs, and `g.worktree(dir).add` emits one for `g.worktree` and one for
 `add`.
 
-> **Return shape change:** `worktrees_all` returns `[directory, sha]` pairs and
+> **Return shape change.** `worktrees_all` returns `[directory, sha]` pairs and
 > omits the main worktree of a bare repository, which has no checked-out commit.
 > `worktree_list` returns `Git::WorktreeInfo` objects with `path`, `head`,
 > `branch` (the full refname, such as `refs/heads/main`, or `nil` when detached
@@ -1026,42 +1697,54 @@ it constructs, and `g.worktree(dir).add` emits one for `g.worktree` and one for
 > `branch` set to `nil`. `Git::WorktreeInfo#to_s` is the path, so an entry can be
 > passed to any method that takes a worktree path.
 >
-> **`gcommit` return type:** `Git::Worktree#gcommit` returned a
+> **`gcommit` return type.** `Git::Worktree#gcommit` returned a
 > `Git::Object::Commit` for a worktree obtained from `g.worktree(dir)` and a raw
 > SHA `String` for one obtained from `g.worktrees`. `info.head` is always a
 > `String` (or `nil` for a bare main worktree); call `g.gcommit(info.head)` for
 > the commit object.
 >
-> **`full` and `to_s`:** `Git::Worktree#full` and `#to_s` append the commitish
+> **`full` and `to_s`.** `Git::Worktree#full` and `#to_s` append the commitish
 > given at construction to the path, so entries from `g.worktrees` read
 > `"/path/to/wt <sha>"`. `Git::WorktreeInfo#to_s` is the path alone.
+>
+> **`worktree_add` in v6.0.0.** On v5.x, `worktree_add` returns the
+> `git worktree add` output (`"HEAD is now at …"`). In v6.0.0 it returns the new
+> `Git::WorktreeInfo` instead (see [`worktree_add` returns `Git::WorktreeInfo` and
+> raises when the worktree is
+> missing](#worktree_add-returns-gitworktreeinfo-and-raises-when-the-worktree-is-missing)).
+> To get the entry today, look it up after the add:
+> `g.worktree_list.find { |w| File.identical?(w.path, dir) }`. Compare with
+> `File.identical?`, not string equality: git stores worktree paths with
+> symlinks resolved, so `/tmp/...` on macOS is listed as `/private/tmp/...`,
+> and on case-insensitive filesystems the listed casing may differ from `dir`.
 
 In the table, `dir` is the worktree path, `wt` is a `Git::Worktree`, and `info`
 is the `Git::WorktreeInfo` that replaces it.
 
 | Deprecated call (works in v5.x, removed in v6.0.0) | Replacement |
 |-----------------------------------------------------|-------------|
-| `g.worktrees_all` | `g.worktree_list.map { \|w\| [w.path, w.head] }` — includes a bare main worktree as `[path, nil]`; add `.reject(&:bare?)` before `map` to omit it as `worktrees_all` did |
-| `g.worktrees` | `g.worktree_list` — returns `Array<Git::WorktreeInfo>`; the deprecated call emits two warnings |
-| `g.worktrees[dir]` | `g.worktree_list.find { \|w\| w.path == dir }` — `nil` when not found; `dir` is the path as git reports it (absolute, with symlinks resolved), as before |
+| `g.worktrees_all` | `g.worktree_list.map { \|w\| [w.path, w.head] }`. Includes a bare main worktree as `[path, nil]`; add `.reject(&:bare?)` before `map` to omit it as `worktrees_all` did |
+| `g.worktrees` | `g.worktree_list`. Returns `Array<Git::WorktreeInfo>`; the deprecated call emits two warnings |
+| `g.worktrees[dir]` | `g.worktree_list.find { \|w\| w.path == dir }`. `nil` when not found; `dir` is the path as git reports it (absolute, with symlinks resolved), as before |
 | `g.worktrees.size` | `g.worktree_list.size` |
 | `g.worktrees.each { \|wt\| ... }` | `g.worktree_list.each { \|info\| ... }` |
 | `g.worktrees.to_s` | `g.worktree_list.map { \|w\| "#{w.path} #{w.head}\n" }.join` |
 | `g.worktrees.prune` | `g.worktree_prune` |
 | `g.worktree(dir).add` | `g.worktree_add(dir)` |
 | `g.worktree(dir, commitish).add` | `g.worktree_add(dir, commitish)` |
-| `g.worktree(dir).remove` | `g.worktree_remove(dir)` — or `g.worktree_remove(info)` |
-| `wt.gcommit` | `info.head` — always a `String`, or `nil` for a bare main worktree; `g.gcommit(info.head)` for the commit object |
+| `g.worktree(dir).remove` | `g.worktree_remove(dir)` or `g.worktree_remove(info)` |
+| `wt.gcommit` | `info.head`. Always a `String`, or `nil` for a bare main worktree; `g.gcommit(info.head)` for the commit object |
 | `wt.dir` | `info.path` |
-| `wt.full`, `wt.to_s` | `info.path` — or `"#{info.path} #{info.head}"` for the descriptor that entries from `g.worktrees` produced |
+| `wt.full`, `wt.to_s` | `info.path` or `"#{info.path} #{info.head}"` for the descriptor that entries from `g.worktrees` produced |
 | `wt.to_a` | `[info.path]` |
 
 #### `Git.clone` option renames
 
-Three `Git.clone` options were renamed in v5.x. The v4.x names still work. Each
-deprecated option present on a call emits its own deprecation warning, so a call
-that uses two of them warns twice. Each value is passed through to the
-replacement option, except that `:path` is dropped when `:chdir` is also given.
+Three `Git.clone` options were renamed in v5.x. The v4.x names still work in
+v5.x. Each deprecated option present on a call emits its own deprecation
+warning, so a call that uses two of them warns twice. Each value is passed
+through to the replacement option, except that `:path` is dropped when `:chdir`
+is also given.
 
 > **Precedence and value notes:**
 > - `:path` and `:chdir` both run `git clone` from inside the given directory.
@@ -1074,7 +1757,7 @@ replacement option, except that `:path` is dropped when `:chdir` is also given.
 | Deprecated call (works in v5.x, removed in v6.0.0) | Replacement |
 |-----------------------------------------------------|-------------|
 | `Git.clone(url, dir, path: p)` | `Git.clone(url, dir, chdir: p)` |
-| `Git.clone(url, dir, recursive: true)` | `Git.clone(url, dir, recurse_submodules: true)` — or a pathspec `String` or `Array<String>` for a subset of submodules |
+| `Git.clone(url, dir, recursive: true)` | `Git.clone(url, dir, recurse_submodules: true)` or a pathspec `String` or `Array<String>` for a subset of submodules |
 | `Git.clone(url, dir, remote: name)` | `Git.clone(url, dir, origin: name)` |
 
 #### `Git::Log` Enumerable interface deprecated
@@ -1091,7 +1774,7 @@ builder (`map`, `select`, `count`, `to_a`, `include?`, and so on) goes through t
 deprecated `each` and emits its warning. Move those calls to the result as well,
 not only the six named methods.
 
-> **Snapshot results:** `execute` returns a snapshot. The builder re-runs
+> **Snapshot results.** `execute` returns a snapshot. The builder re-runs
 > `git log` only when a query method (`since`, `max_count`, and so on) has been
 > called since the last run, even with the same value as before, so calling
 > `execute` twice on an untouched builder returns equal results without a second
@@ -1104,7 +1787,7 @@ In the table, `g` is a `Git::Repository`.
 |-----------------------------------------------------|-------------|
 | `g.log.each { \|c\| ... }` | `g.log.execute.each { \|c\| ... }` |
 | `g.log.size` | `g.log.execute.size` |
-| `g.log.to_s` | `g.log.execute.to_s` — commits joined with newlines, as before |
+| `g.log.to_s` | `g.log.execute.to_s`. Commits joined with newlines, as before |
 | `g.log.first`, `g.log.last` | `g.log.execute.first`, `g.log.execute.last` |
 | `g.log[i]`, `g.log[range]` | `g.log.execute[i]`, `g.log.execute[range]` |
 | any other `Enumerable` method on the log (`map`, `select`, `count`, `to_a`, `include?`, ...) | the same method on `g.log.execute` |
@@ -1136,40 +1819,4 @@ observable in the result. Delete the option from the call.
 |--------------------------------------------------------------------|-------------|
 | `Git.export(url, dir, remote: name)` | `Git.export(url, dir)` |
 
-#### Context helper blocks that declare no parameter deprecated
-
-`Git::Repository#with_index`, `#with_temp_index`, `#with_working`, and
-`#with_temp_working` yield `self` in v5.x, so a block could ignore the yielded
-value and call methods on the receiver. Calling one of these helpers with a block
-that declares no positional parameter (`do ... end`, `{ }`, `{ || }`, or a block
-with only keyword or block parameters) now emits a deprecation warning. The
-behavior is otherwise unchanged: the helpers still yield `self`, and a call with
-no block still raises `LocalJumpError`.
-
-In v6.0.0 these helpers yield a separate repository bound to the other index or
-working tree instead of rebinding the receiver, and they raise `ArgumentError` for
-a block that declares no positional parameter. A call with no block also raises
-`ArgumentError` in v6.0.0 instead of `LocalJumpError`. Declare a block parameter
-and call methods on it. The parameter is required even when the block never uses
-the repository, for example a `with_temp_working` block that only writes files
-(`do |_scratch|`). Blocks that already declare a positional parameter (`|repo|`,
-`|_|`, `|repo = nil|`, `|*args|`, or a symbol-to-proc such as `&:write_tree`) do
-not warn. Both versions read the block's parameter list rather than its arity, so
-the v5.x warning and the v6.0.0 error agree on every block form.
-
-The warning detects only the block's parameter list. Adding an unused parameter
-(`|_|`) silences it but does not fix a block that still calls methods on the outer
-repository; that block does not warn and acts on the wrong repository in v6.0.0,
-so review those blocks by hand.
-
-| Deprecated call (works in v5.x, raises in v6.0.0) | Replacement |
-|---------------------------------------------------|-------------|
-| `g.with_index(path) { g.read_tree('HEAD') }` | `g.with_index(path) { \|r\| r.read_tree('HEAD') }` |
-| `g.with_temp_index { g.read_tree('HEAD') }` | `g.with_temp_index { \|r\| r.read_tree('HEAD') }` |
-| `g.with_working(dir) { g.add('.') }` | `g.with_working(dir) { \|r\| r.add('.') }` |
-| `g.with_temp_working { g.add('.') }` | `g.with_temp_working { \|r\| r.add('.') }` |
-
-`chdir` is not part of this deprecation. It yields the directory path in both
-versions.
-
 ---