git 5.3.0 → 5.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aedbda16896f72f7adc9320f2e1ade684cd1f4a49a392929ce3eb64d0320ca31
-  data.tar.gz: 8a77684970cde47e1ce927b2c4dab8c1e3c7b9356d876bbcb66a79c5d39769f4
+  metadata.gz: 1b0ec11636ea561f0c879744f4c7b94fd12f2a2fae29da23ac22f338edefe9fe
+  data.tar.gz: b70d5290d89c34293b3dd47b839b1a6d091f7d081236623b844160269e07e2ae
 SHA512:
-  metadata.gz: 37f051a10d8fad9eb51e3bebd2cefd84d523ca5961bb1fabc619f01a2db28f9c271a2a97701e8a575d2ab2e3244c5c1ee36b97bf9b94f45caa29f2f4a46340c1
-  data.tar.gz: 8c9cb46f8a7a74eff2488ef24e3641a3f6dccadee4735009290450630f3aab6bc90402e333c45c5061d8cb276767971eb316cba00196a1b7c3f3a6d7ad4fda85
+  metadata.gz: 449e637646f9faba003af92629c11dbf3a42703f4331a331c3bf03f218659335fd1abd17344bc74f91ffd78a9e4823c3f4dd6cb1ac9a2546a5884cd673dd2a47
+  data.tar.gz: f2a797c6f9a56ae2c877c01a3b7f3da3db46f5d82b5b930de44998035404255692a44c012efb610d4032e5b8d72231f782cf7e5ba921de344c94dde4c5c7b52a

data/CHANGELOG.md

@@ -5,6 +5,22 @@
 
 # Change Log
 
+## [5.4.0](https://github.com/ruby-git/ruby-git/compare/v5.3.0...v5.4.0) (2026-09-04)
+
+
+### Features
+
+* **stash:** Add the StashInfo facade surface and deprecate the legacy stash API ([3cc4c6b](https://github.com/ruby-git/ruby-git/commit/3cc4c6bdc58203eedf7f3207f8b915e52ebc6eee)), closes [#1730](https://github.com/ruby-git/ruby-git/issues/1730)
+* **status:** Add Git::StatusInfo and Git::StatusFileInfo and deprecate Git::Status ([b0a376b](https://github.com/ruby-git/ruby-git/commit/b0a376b19fb3ac100a11b8fa5f07b0700a6f4ce6)), closes [#1720](https://github.com/ruby-git/ruby-git/issues/1720)
+* **tag:** Add tag_list and tag_create and deprecate the Git::Object::Tag returns ([6f9c55c](https://github.com/ruby-git/ruby-git/commit/6f9c55c7d2e845c7ec595b9db5ad8117b28e90f8)), closes [#1719](https://github.com/ruby-git/ruby-git/issues/1719)
+* **worktree:** Add WorktreeInfo, cover every subcommand, and deprecate the legacy API ([581d6ad](https://github.com/ruby-git/ruby-git/commit/581d6ad908fb746a3b5e1726157da3d33a04bae4)), closes [#1731](https://github.com/ruby-git/ruby-git/issues/1731)
+
+
+### Other Changes
+
+* **release:** Move the workflow description into comments ([a5d90bd](https://github.com/ruby-git/ruby-git/commit/a5d90bdd7b9e07859007942eb07f9b153e9c9e0a)), closes [#1734](https://github.com/ruby-git/ruby-git/issues/1734)
+* **tag:** Add failing specs for TagInfo facade methods and Object::Tag deprecation ([749c327](https://github.com/ruby-git/ruby-git/commit/749c327bf793fd8f4b06b7a2dd1740aa977e9b57)), closes [#1719](https://github.com/ruby-git/ruby-git/issues/1719)
+
 ## [5.3.0](https://github.com/ruby-git/ruby-git/compare/v5.2.0...v5.3.0) (2026-09-03)
 
 

data/README.md

@@ -98,7 +98,7 @@ Clone, read status, and log:
 require 'git'
 
 repo = Git.clone('https://github.com/ruby-git/ruby-git.git', 'ruby-git')
-repo.status.changed.each { |f| puts "changed: #{f.path}" }
+repo.status_info.changed.each_key { |path| puts "changed: #{path}" }
 repo.log(5).execute.each { |c| puts c.message }
 ```
 

data/UPGRADING.md

@@ -20,10 +20,14 @@ to update your code when upgrading from the preceding major version.
     - [`Git` module mixin deprecations](#git-module-mixin-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)
 
 ## Upgrading to v6.0.0
 
@@ -234,7 +238,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 +270,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)
 
@@ -372,7 +376,7 @@ purpose-named methods.
 | `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` |
+| `g.stash_list` | `g.stash_infos` — returns `Array<Git::StashInfo>`; see [Legacy stash API deprecated](#legacy-stash-api-deprecated) |
 
 #### `Git` module mixin deprecations
 
@@ -413,34 +417,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 +713,237 @@ 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]` |
 
 ---

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

data/lib/git/object.rb

@@ -538,6 +538,18 @@ module Git
     # Annotated tags contain additional metadata such as the tagger's name, email, and
     # the date when the tag was created, along with a message.
     #
+    # @deprecated Use {Git::Repository::ObjectOperations#tag_list} and
+    #   {Git::TagInfo} instead
+    #
+    #   {Git::TagInfo} is an immutable value object carrying the tag's `name`,
+    #   `oid`, `target_oid`, `annotated?`, `message`, and `tagger`. Call the
+    #   corresponding {Git::Repository} method (e.g. `archive`, `log`, `diff`,
+    #   `cat_file_contents`) with `info.oid || info.target_oid` for operations
+    #   on a tag; that is the object this class resolves and pins at
+    #   construction, so a later move of the tag does not redirect an existing
+    #   object, whereas the tag name would. Constructing a `Git::Object::Tag`
+    #   emits a deprecation warning.
+    #
     class Tag < AbstractObject
       # @return [String] the tag name
       #
@@ -551,6 +563,13 @@ module Git
       #
       # @overload initialize(base, sha, name)
       #
+      #   `sha` is kept as the object that the inherited operations (`size`,
+      #   `contents`, `grep`, `diff`, `log`, `archive`) run against; `annotated?`,
+      #   `message`, and `tagger` read the ref `name`. {Git::TagInfo} describes a
+      #   ref, so there is no OID-based replacement for this form: pass `sha` to
+      #   the {Git::Repository} operation directly, or read the tag object with
+      #   {Git::Repository::ObjectOperations#cat_file_tag}.
+      #
       #   @param base [Git::Repository] the git repository
       #
       #   @param sha [String] the SHA of the tag object
@@ -558,12 +577,11 @@ module Git
       #   @param name [String] the name of the tag
       #
       def initialize(base, sha, name = nil)
-        if name.nil?
-          name = sha
-          sha = base.tag_sha(name)
-          raise Git::UnexpectedResultError, "Tag '#{name}' does not exist." if sha == ''
-        end
-
+        Git::Deprecation.warn(
+          'Git::Object::Tag is deprecated and will be removed in v6.0.0. ' \
+          'Use Git::Repository#tag_list and Git::TagInfo instead.'
+        )
+        sha, name = resolve_sha_and_name(base, sha, name)
         super(base, sha)
 
         @name = name
@@ -609,6 +627,31 @@ module Git
 
       private
 
+      # Resolves the two-argument constructor form to a SHA and a tag name
+      #
+      # In the two-argument form `sha` carries the tag name and the SHA is
+      # looked up from the repository.
+      #
+      # @param base [Git::Repository] the git repository
+      #
+      # @param sha [String] the SHA of the tag object, or the tag name in the
+      #   two-argument form
+      #
+      # @param name [String, nil] the tag name, or `nil` in the two-argument form
+      #
+      # @return [Array(String, String)] the resolved `[sha, name]` pair
+      #
+      # @raise [Git::UnexpectedResultError] if the tag does not exist
+      #
+      def resolve_sha_and_name(base, sha, name)
+        return [sha, name] unless name.nil?
+
+        resolved = base.tag_sha(sha)
+        raise Git::UnexpectedResultError, "Tag '#{sha}' does not exist." if resolved == ''
+
+        [resolved, sha]
+      end
+
       # Loads annotated tag data when available
       #
       # @return [void]
@@ -663,14 +706,19 @@ module Git
     #
     # @return [Git::Object::Tag] the tag object wrapper
     #
-    # @deprecated use `Git::Object::Tag.new` instead
+    # @deprecated Use {Git::Repository::ObjectOperations#tag_list} instead
+    #
+    #   The warning names `Git::Object::Tag.new`, the replacement this path
+    #   shipped with, and the {Git::Object::Tag} constructor is deprecated as
+    #   well; this method silences it so one call emits one warning. Go
+    #   straight to `Git::Repository#tag_list(name).first`.
     #
     private_class_method def self.new_tag(base, objectish)
       Git::Deprecation.warn(
         'Git::Object.new with is_tag argument is deprecated and will be removed in v6.0.0. ' \
         'Use Git::Object::Tag.new instead.'
       )
-      Git::Object::Tag.new(base, objectish)
+      Git::Deprecation.silence { Git::Object::Tag.new(base, objectish) }
     end
 
     # Returns the repository used for object lookup