git 5.3.0 → 5.4.1

data/UPGRADING.md

@@ -16,14 +16,24 @@ to update your code when upgrading from the preceding major version.
     - [`Git::CommandLineResult` deprecated](#gitcommandlineresult-deprecated)
   - [Deprecated methods](#deprecated-methods)
     - [Facade method renames](#facade-method-renames)
+    - [`Git::Repository` method renames](#gitrepository-method-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)
+    - [Module-level `Git` function deprecations](#module-level-git-function-deprecations)
     - [`Git::Author` deprecated](#gitauthor-deprecated)
     - [`Git::Branch#stashes` deprecated](#gitbranchstashes-deprecated)
+    - [Legacy stash API deprecated](#legacy-stash-api-deprecated)
     - [`Git::Repository#remotes` deprecated](#gitrepositoryremotes-deprecated)
     - [`Git::Remote` deprecated](#gitremote-deprecated)
     - [`Git::Commands::CatFile::Raw` `allow_unknown_type` option deprecated](#gitcommandscatfileraw-allow_unknown_type-option-deprecated)
     - [`Git::Branch` and `Git::Branches` deprecated](#gitbranch-and-gitbranches-deprecated)
+    - [`Git::Object::Tag` deprecated](#gitobjecttag-deprecated)
+    - [`Git::Status` deprecated](#gitstatus-deprecated)
+    - [`Git::Worktree` and `Git::Worktrees` deprecated](#gitworktree-and-gitworktrees-deprecated)
+    - [`Git.clone` option renames](#gitclone-option-renames)
+    - [`Git::Log` Enumerable interface deprecated](#gitlog-enumerable-interface-deprecated)
+    - [`Git::Object::Commit#set_commit` deprecated](#gitobjectcommitset_commit-deprecated)
 
 ## Upgrading to v6.0.0
 
@@ -234,7 +244,7 @@ to the replacement shown to silence it.
 | `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.stashes_all` |
+| `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)` |
@@ -266,7 +276,7 @@ shim cannot forward them). Update call sites directly:
 
 | v4.x call | Notes |
 |-----------|-------|
-| `g.lib.list_files(ref_dir)` | Walked `.git/refs/` directly. Use `g.branch_list`, `g.tags`, or `g.remote_list` instead. |
+| `g.lib.list_files(ref_dir)` | Walked `.git/refs/` directly. Use `g.branch_list`, `g.tag_list`, or `g.remote_list` instead. |
 
 ##### Internal plumbing methods (no replacement)
 
@@ -350,18 +360,89 @@ The old names continue to work but emit deprecation warnings:
 | `g.add_tag(name, ...)` | `g.tag_add(name, ...)` |
 | `g.delete_tag(name)` | `g.tag_delete(name)` |
 
+#### `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
+replacement returns, except `branches_all`.
+
+> **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
+> `Array<Git::BranchInfo>` with `refname` (always the full ref: `refs/heads/main`
+> or `refs/remotes/origin/main`), `short_name`, `remote_name`, `remote?`,
+> `current?`, `other_worktree?`, `symref`, `target_oid`, and `upstream`. This
+> expression reproduces the legacy tuples:
+>
+> ```ruby
+> g.branch_list.map do |i|
+>   refname = i.remote? ? "remotes/#{i.remote_name}/#{i.short_name}" : i.short_name
+>   [refname, i.current?, i.other_worktree?, i.symref]
+> end
+> ```
+
+| 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.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 |
+
+#### `Git::Repository` option renames
+
+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
+> 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
+> `:force` is also given, `:force` is raised to `2` (a `:force` already at `2`
+> is unchanged). An invalid `:force` value such as `0` is passed through
+> unchanged and still raises `ArgumentError`; the deprecated key does not mask
+> it.
+
+> **`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
+> both the positional argument and `must_exist:` are given, they are OR'ed so
+> the more restrictive value wins.
+
+| Deprecated call (works in v5.x, removed in v6.0.0) | Replacement |
+|-----------------------------------------------------|-------------|
+| `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.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,
-purpose-named methods.
-
-> **Return type change:** The v4.x `g.config(name)` returned a `String` and
-> `g.config` returned a `Hash`. The v5.x replacements `config_get` and
-> `config_list` return `Git::ConfigEntryInfo` and `Array<Git::ConfigEntryInfo>`
+purpose-named methods. The same applies to the module-level
+`Git.global_config`, which is replaced by `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)`
+> 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)
+>
+> 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 |
 |-----------------------------------------------------|-------------|
@@ -371,8 +452,9 @@ purpose-named methods.
 | `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)` |
-| `g.parse_config(file)` | `g.config_list(file: file)` |
-| `g.stash_list` | `g.stashes_all` |
+| `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
 
@@ -381,13 +463,43 @@ as bare methods is deprecated:
 
 | Deprecated usage | Replacement |
 |-----------------|-------------|
-| `include Git; config(name)` | `Git.open(Dir.pwd).config_get(name)` |
-| `include Git; config(name, value)` | `Git.open(Dir.pwd).config_set(name, value)` |
-| `include Git; config` | `Git.open(Dir.pwd).config_list` |
+| `include Git; config(name)` | `Git.config_get(name)` |
+| `include Git; config(name, value)` | `Git.config_set(name, value)` |
+| `include Git; config` | `Git.config_list` |
 | `include Git; global_config(name)` | `Git.config_get(name, global: true)` |
 | `include Git; global_config(name, value)` | `Git.config_set(name, value, global: true)` |
 | `include Git; global_config` | `Git.config_list(global: true)` |
 
+`Git.config_get`, `Git.config_set`, and `Git.config_list` run `git config` in
+the current directory, which is what the mixin `config` method did. The
+return types differ as described under
+[v4.x-style configuration methods](#v4x-style-configuration-methods).
+
+#### Module-level `Git` function deprecations
+
+Two module-level functions on `Git` accept a legacy call shape or return a
+legacy type that is deprecated:
+
+- `Git.ls_remote` defaults its repository argument to `'.'`. Passing `nil`
+  explicitly still works but warns; omit the argument or pass `'.'`. The
+  options hash is positional, so when you pass options you must also pass the
+  repository: `Git.ls_remote('.', opts)`, not `Git.ls_remote(opts)`.
+- `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
+> `[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
+> `Git.ls_remote` is unchanged.
+
+| Deprecated call (works in v5.x, removed in v6.0.0) | Replacement |
+|-----------------------------------------------------|-------------|
+| `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(binary_path)` | `Git.git_version(binary_path)` |
+
 #### `Git::Author` deprecated
 
 Starting in v5.3.0, methods that return author, committer, or tagger data —
@@ -413,34 +525,97 @@ Constructing `Git::Author` directly emits a deprecation warning naming
 
 `Git::Branch#stashes` ignores the branch it is called on and returns every stash
 in the repository, so `g.branch('feature').stashes` and `g.branch('main').stashes`
-return the same entries. Call `Git::Repository#stashes_all` instead; it is the
+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`
-> collection of `Git::Stash` objects, newest first. `g.stashes_all` returns an
-> array of `[index, message]` pairs, oldest first. Code that read `stash.message`
-> from each entry should read the second element of each pair instead. Code that
-> iterated or indexed the collection must reverse the order first, because
-> `Git::Stashes` yields and indexes newest first while `g.stashes_all` is oldest
-> first.
+> 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;
+> `Git::StashInfo#message` keeps the full message and exposes the branch name as
+> `Git::StashInfo#branch`.
 
 `Git::Stashes` also exposes `save`, `apply`, and `clear`. Those map to the
-repository's `stash_save`, `stash_apply`, and `stash_clear`, which are not
-deprecated. `Git::Stashes#apply(i)` already passed `i` to git as `stash@{i}`
-(`0` = newest), and `g.stash_apply(i)` does the same, so that index needs no
-conversion.
+repository's `stash_push`, `stash_apply`, and `stash_clear`. `Git::Stashes#apply(i)`
+already passed `i` to git as `stash@{i}` (`0` = newest), and `g.stash_apply(i)` does
+the same, so that index needs no conversion. The `Git::Stashes` class is deprecated
+as well; [Legacy stash API deprecated](#legacy-stash-api-deprecated) maps each of
+its methods.
 
 | Deprecated call (works in v5.x, removed in v6.0.0) | Replacement |
 |-----------------------------------------------------|-------------|
-| `g.branch(name).stashes` | `g.stashes_all` — returns `[[index, message], ...]` |
-| `g.branch(name).stashes.each { \|s\| puts s.message }` | `g.stashes_all.reverse_each { \|_index, message\| puts message }` |
-| `g.branch(name).stashes.all` | `g.stashes_all` |
-| `g.branch(name).stashes.size` | `g.stashes_all.size` |
-| `g.branch(name).stashes[i].message` (`0` = newest, `i` coerced with `to_i`) | `g.stashes_all.reverse[i.to_i][1]` |
-| `g.branch(name).stashes.save(message)` | `g.stash_save(message)` |
+| `g.branch(name).stashes` | `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.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` |
+| `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
+
+Starting in v5.4.0, the stash methods on `Git::Repository` are built around the
+immutable `Git::StashInfo` value object. `g.stash_infos` returns every entry as a
+`Git::StashInfo`, and `stash_push`, `stash_pop`, `stash_drop`, `stash_show`,
+`stash_branch`, `stash_create`, and `stash_store` each map onto the `git stash`
+subcommand of the same name. Every method that takes a stash (`stash_apply`,
+`stash_pop`, `stash_drop`, `stash_show`, `stash_branch`) accepts a `Git::StashInfo`,
+a `stash@{N}` name, an Integer index (`0` = newest), or `nil` for the newest entry.
+
+The legacy methods and classes are deprecated and removed in v6.0.0:
+`Git::Repository#stashes_all`, `Git::Repository#stash_save`,
+`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
+> 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
+> 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
+> `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
+> in its message. `branch` is `nil` only when the message has no branch prefix at
+> all, as for a `stash_store` entry with a custom message.
+
+`g.stash_save(message)` returned `true` when it created a stash and `false` when
+there were no local changes to save. `g.stash_push(message: message)` returns the
+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.
+
+| 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.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_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 |
+| `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 |
+| `Git::Stashes.new(g)` | `g.stash_infos` |
+| `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` |
+
 #### `Git::Repository#remotes` deprecated
 
 `Git::Repository#remotes` is deprecated in favor of `Git::Repository#remote_list`
@@ -646,6 +821,300 @@ can resolve a local branch of that name and is only used where git expects it
 | `b.update_ref(commit)` (remote-tracking) | `g.update_ref("remotes/#{remote}/#{name}", commit)` |
 | `b.archive(file, opts)` | `g.archive(name, file, opts)` — pass `info.refname` for a remote-tracking branch |
 | `b.in_branch(message) { ... }` | `g.in_branch(name, message) { ... }` — local `b` only; see the differences above |
-| `b.stashes` | `g.stashes_all` — see [`Git::Branch#stashes` deprecated](#gitbranchstashes-deprecated) |
+| `b.stashes` | `g.stash_infos` — see [`Git::Branch#stashes` deprecated](#gitbranchstashes-deprecated) |
+
+#### `Git::Object::Tag` deprecated
+
+`Git::Object::Tag`, `Git::Repository#tag`, `Git::Repository#tags`, and
+`Git::Repository#tag_add` are deprecated and are removed in v6.0.0. Read tag data
+through `Git::Repository#tag_list`, which returns one `Git::TagInfo` value object per
+tag, create tags with `Git::Repository#tag_create`, which returns the new tag's
+`Git::TagInfo`, and call the repository-level operations (`archive`, `log`, `diff`,
+`cat_file_contents`, and so on) with the tag's object ID,
+`info.oid || info.target_oid`, which is the object a `Git::Object::Tag` pinned when
+it was constructed. Calling `g.tag`, `g.tags`, or
+`g.tag_add`, and constructing a `Git::Object::Tag`, each emit one deprecation
+warning; their return values are unchanged. `g.add_tag` already warned, pointing at
+`g.tag_add`, and now emits two warnings for a creation call, one for itself and one
+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`,
+> `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`
+> and `email`, but `tagger.date` differs: `t.tagger.date` is a `Time` in the
+> process's local zone, while `info.tagger.date` keeps the UTC offset recorded in
+> the tag object. Both name the same instant. `message` differs for an annotated
+> tag created with an empty message (`message: ''`): `t.message` returns `""` and
+> `info.message` returns `nil`, the same value a lightweight tag has. `t.sha` and
+> `t.objectish` are the tag object's ID for an annotated tag and
+> the tagged object's ID for a lightweight tag. `Git::TagInfo` separates the two:
+> `oid` is the tag object's ID (`nil` for a lightweight tag) and `target_oid` is
+> the ID of the object the tag points to (set for both kinds), so
+> `info.oid || info.target_oid` reproduces `t.sha`. The target is usually a
+> commit, but a tag can point at any git object, and `info.objecttype` reports
+> 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
+> has that name. `g.tag_list(name).first` returns `nil`.
+>
+> **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` 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
+> 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
+> supplied `sha` as that ID; the other forms look it up from the ref. `annotated?`,
+> `message`, and `tagger` always read the ref `name`. `Git::TagInfo` describes the
+> ref only: `g.tag_list(name).first` returns whatever `name` points at now, or
+> `nil` once the tag is deleted. Keep the same identity by passing `id` (see the
+> table) rather than `name` to the operation replacements; they accept any object.
+> To read an annotated tag object by ID without going through its ref, use
+> `g.cat_file_tag(id)`, which returns the tag object's `object`, `type`, `tag`,
+> `tagger`, and `message`.
+
+In the table, `name` is the tag name, `t` is a `Git::Object::Tag`, `info` is the
+`Git::TagInfo` that replaces it, and `id` is `info.oid || info.target_oid` (or the
+`sha` given to the three-argument constructor), the object `t` pinned.
+
+| 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.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, 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 |
+| `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 |
+| `t.name` | `info.name` |
+| `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.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.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_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)` |
+| `t.log(count)` | `g.log(count).object(id)` |
+| `t.archive(file, opts)` | `g.archive(id, file, opts)` |
+
+#### `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
+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
+deprecation warning, and so does constructing a `Git::Status` directly.
+
+`Git::StatusInfo` keeps the `changed`, `added`, `deleted`, and `untracked`
+readers and the `changed?`, `added?`, `deleted?`, and `untracked?` predicates,
+so code that only uses those can change `status` to `status_info` and needs
+no other edit, subject to the category differences below. The readers now
+return `Hash{String => Git::StatusFileInfo}`, and a new `unmerged` reader
+lists conflicted paths, which `Git::Status` did not report. The predicates
+still compare paths case-insensitively when `core.ignoreCase` is `true`.
+`Git::StatusInfo` is not `Enumerable`; iterate `status_info.files`, an
+`Array<Git::StatusFileInfo>` in git's output order.
+
+The categories are derived differently. `Git::Status` gave each file one
+`type`, and `changed` held only files whose type was `M`, so `changed`,
+`added`, and `deleted` were disjoint: a file staged as new and then modified
+in the working tree was only `added`. `Git::StatusInfo` derives the
+categories from both status characters, so `changed` also includes type
+changes (`T`), and one path can be in more than one category: that same file
+(`AM`) is in both `added` and `changed`, and a file modified in the index and
+then deleted from the working tree (`MD`) is in both `changed` and `deleted`.
+Code that relied on the sets being disjoint should test `index_status` and
+`worktree_status` directly.
+
+`Git::StatusInfo` holds only the paths `git status` reports. `Git::Status`
+also held an entry for every clean tracked file, seeded from `git ls-files`,
+so `status[path]` returned a `Git::Status::StatusFile` with a `nil` type for an
+unchanged path and `status.each` yielded one. `status_info[path]` returns `nil`
+for a clean path and `status_info.files` omits it. Code that inspected clean
+files should read `g.ls_files`, which still returns the index mode and SHA of
+every tracked path.
+
+`Git::StatusFileInfo` replaces the single `type` character with the two status
+characters of the porcelain v2 format, `index_status` (HEAD versus index) and
+`worktree_status` (index versus working tree), plus the `changed?`, `added?`,
+`deleted?`, `renamed?`, `unmerged?`, `untracked?`, and `ignored?` predicates:
+`added?` is true when `index_status` is `A`, `deleted?` when either status is
+`D`, and `changed?` when either status is `M` or `T`. It holds no repository
+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
+> 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
+> working tree against: the index in a repository with no commits, and HEAD
+> once a commit exists (the factory applied `git diff-index HEAD` last). The
+> new names follow git: `sha_head` and `mode_head` are the HEAD side,
+> `sha_index` and `mode_index` are the index (staged) side, and
+> `mode_worktree` is the working-tree mode. There is no working-tree SHA
+> because `git status` does not compute one; `worktree_status` says whether
+> the working tree differs from the index.
+
+In the table, `g` is a `Git::Repository`, `status` is the `Git::Status` from
+`g.status`, `file` is a `Git::Status::StatusFile`, and `info` is the
+`Git::StatusFileInfo` that replaces it.
+
+| Deprecated call (works in v5.x, removed in v6.0.0) | Replacement |
+|-----------------------------------------------------|-------------|
+| `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?(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.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 |
+| `file.untracked` | `info.untracked?` |
+| `file.stage` | gone; `info.unmerged?` and `info.unmerged_stages` describe conflicted entries |
+| `file.sha_repo` | `info.sha_head`, or `info.sha_index` in a repository with no commits |
+| `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 |
+
+#### `Git::Worktree` and `Git::Worktrees` deprecated
+
+`Git::Worktree`, `Git::Worktrees`, `Git::Repository#worktree`,
+`Git::Repository#worktrees`, and `Git::Repository#worktrees_all` are deprecated
+and are removed in v6.0.0. Read worktree data through
+`Git::Repository#worktree_list`, which returns one `Git::WorktreeInfo` value
+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`,
+`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.
+`g.worktrees` emits two warnings, one for itself and one for the `Git::Worktrees`
+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
+> 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
+> or bare), `bare?`, `detached?`, `locked?` with `lock_reason`, and `prunable?`
+> with `prune_reason`. It includes the bare main worktree, with `head` and
+> `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
+> `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
+> given at construction to the path, so entries from `g.worktrees` read
+> `"/path/to/wt <sha>"`. `Git::WorktreeInfo#to_s` is the path alone.
+
+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.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 |
+| `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.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.
+
+> **Precedence and value notes:**
+> - `:path` and `:chdir` both run `git clone` from inside the given directory.
+>   When both are given, `:chdir` wins and `:path` is dropped.
+> - `:recursive` carries its value over to `:recurse_submodules` unchanged.
+>   `:recurse_submodules` also accepts a pathspec `String` or `Array<String>`
+>   to initialize only a subset of submodules, which `:recursive` never did.
+> - `:remote` and `:origin` have the same effect (`git clone --origin name`).
+
+| 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, remote: name)` | `Git.clone(url, dir, origin: name)` |
+
+#### `Git::Log` Enumerable interface deprecated
+
+`Git::Log` is a query builder. Calling `each`, `size`, `to_s`, `first`, `last`, or
+`[]` directly on it runs the query and emits a deprecation warning; those methods
+are removed in v6.0.0. Call `Git::Log#execute` instead. It runs the query and
+returns a `Git::Log::Result`, which includes `Enumerable` and provides the same
+six methods. The chainable query methods on `Git::Log` (`since`, `author`,
+`between`, `path`, `max_count`, and so on) are unchanged.
+
+`Git::Log` includes `Enumerable`, so every `Enumerable` method called on the
+builder (`map`, `select`, `count`, `to_a`, `include?`, and so on) goes through the
+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
+> `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
+> `git log`. Keep the result object when a chain of operations needs the same
+> commits rather than calling `g.log` again, which builds a new query.
+
+In the table, `g` is a `Git::Repository`.
+
+| Deprecated call (works in v5.x, removed in v6.0.0) | Replacement |
+|-----------------------------------------------------|-------------|
+| `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.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` |
+
+#### `Git::Object::Commit#set_commit` deprecated
+
+`Git::Object::Commit#set_commit` is deprecated and is removed in v6.0.0. Call
+`from_data` instead; it takes the same parsed commit data hash and has the same
+effect.
+
+| Deprecated call (works in v5.x, removed in v6.0.0) | Replacement |
+|-----------------------------------------------------|-------------|
+| `commit.set_commit(data)` | `commit.from_data(data)` |
 
 ---

data/lib/git/branch.rb

@@ -132,22 +132,26 @@ module Git
     #
     # The result is memoized after the first call.
     #
-    # @example Iterate over stash entries
+    # @example Iterate over stash entries (deprecated)
     #   git.branch('main').stashes.each { |s| puts s }
     #
+    # @example The replacement
+    #   repo.stash_infos.each { |info| puts info.message }
+    #
     # @return [Git::Stashes] the stash list
     #
-    # @deprecated Use {Git::Repository#stashes_all} instead
+    # @deprecated Use {Git::Repository#stash_infos} instead
     #
-    # @see Git::Repository#stashes_all
+    # @see Git::Repository#stash_infos
     #
     def stashes
       Git::Deprecation.warn(
         'Git::Branch#stashes is deprecated and will be removed in v6.0.0. ' \
         'It ignores the branch and returns all repository stashes. ' \
-        'Use Git::Repository#stashes_all instead.'
+        'Use Git::Repository#stash_infos instead.'
       )
-      @stashes ||= Git::Stashes.new(branch_repository)
+      # Git::Stashes is deprecated too; silence it so one stashes call emits one warning
+      @stashes ||= Git::Deprecation.silence { Git::Stashes.new(branch_repository) }
     end
 
     # Checks out this branch, attempting to create it first if it does not already exist