git 5.0.0.beta.5 → 5.0.0

data/lib/git/repository/remote_operations.rb

@@ -7,6 +7,7 @@ require 'git/commands/pull'
 require 'git/commands/push'
 require 'git/commands/remote'
 require 'git/parsers/ls_remote'
+require 'git/parsers/remote'
 require 'git/remote'
 
 require 'git/repository/shared_private'
@@ -330,11 +331,11 @@ module Git
       # @option opts [String, nil] :track (nil) track only the given branch during
       #   fetch (`-t`)
       #
-      # @return [Git::Remote] the newly added remote
+      # @return [void]
       #
       # @raise [ArgumentError] when unsupported option keys are provided
       #
-      # @raise [Git::FailedError] when git exits with a non-zero status
+      # @raise [Git::FailedError] if git exits with a non-zero exit status
       #
       def remote_add(name, url, opts = {})
         url = url.repo.to_s if url.is_a?(Git::Repository)
@@ -342,7 +343,7 @@ module Git
         SharedPrivate.assert_valid_opts!(REMOTE_ADD_ALLOWED_OPTS, **opts)
         Git::Commands::Remote::Add.new(@execution_context).call(name, url, **opts)
 
-        Git::Remote.new(self, name)
+        nil
       end
 
       # @param name [String] the name for the new remote
@@ -367,7 +368,7 @@ module Git
       #
       # @raise [ArgumentError] when unsupported option keys are provided
       #
-      # @raise [Git::FailedError] when git exits with a non-zero status
+      # @raise [Git::FailedError] if git exits with a non-zero exit status
       #
       # @deprecated Use {#remote_add} instead
       #
@@ -377,6 +378,7 @@ module Git
           'Use Git::Repository#remote_add instead.'
         )
         remote_add(name, url, opts)
+        Git::Remote.new(self, name)
       end
 
       # Removes a remote from this repository
@@ -431,15 +433,15 @@ module Git
       #   A {Git::Repository} instance is accepted for local references and converted
       #   to `url.repo.to_s`.
       #
-      # @return [Git::Remote] the updated remote
+      # @return [void]
       #
-      # @raise [Git::FailedError] when git exits with a non-zero status
+      # @raise [Git::FailedError] if git exits with a non-zero exit status
       #
       def remote_set_url(name, url)
         url = url.repo.to_s if url.is_a?(Git::Repository)
         Git::Commands::Remote::SetUrl.new(@execution_context).call(name, url)
 
-        Git::Remote.new(self, name)
+        nil
       end
 
       # @param name [String] the name of the remote to update
@@ -451,7 +453,7 @@ module Git
       #
       # @return [Git::Remote] the updated remote
       #
-      # @raise [Git::FailedError] when git exits with a non-zero status
+      # @raise [Git::FailedError] if git exits with a non-zero exit status
       #
       # @deprecated Use {#remote_set_url} instead
       #
@@ -461,6 +463,7 @@ module Git
           'Use Git::Repository#remote_set_url instead.'
         )
         remote_set_url(name, url)
+        Git::Remote.new(self, name)
       end
 
       # Configures which branches are fetched for a remote
@@ -529,6 +532,34 @@ module Git
         end
       end
 
+      # List all configured remotes as {Git::RemoteInfo} objects
+      #
+      # Reads the repository configuration via {Git::Configuring#config_list} and
+      # returns one {Git::RemoteInfo} per configured remote, preserving the order
+      # in which remotes appear in the config. Multi-value fields (`:url`,
+      # `:push_url`, `:fetch`, `:push`) are always `Array<String>` (never `nil`).
+      #
+      # @example List all remotes
+      #   repo.remote_list
+      #   # => [#<data Git::RemoteInfo name="origin" ...>,
+      #   #      #<data Git::RemoteInfo name="upstream" ...>]
+      #
+      # @example Get fetch URLs for all remotes
+      #   repo.remote_list.map { |r| [r.name, r.url] }.to_h
+      #
+      # @return [Array<Git::RemoteInfo>] one entry per configured remote
+      #
+      #   Returns an empty array when no remotes are configured.
+      #
+      # @raise [ArgumentError] if a `remote.*` config entry carries an
+      #   unrecognized boolean value (e.g. `remote.origin.prune=maybe`)
+      #
+      # @raise [Git::FailedError] if git exits with a non-zero exit status
+      #
+      def remote_list
+        Git::Parsers::Remote.parse_list(config_list)
+      end
+
       # Returns a {Git::Remote} object for the named remote
       #
       # @example Get the default 'origin' remote
@@ -563,6 +594,31 @@ module Git
         result.stdout.split("\n").map { |name| Git::Remote.new(self, name) }
       end
 
+      # Returns the names of all configured remotes
+      #
+      # Lists remote names by running `git remote`. This is a lightweight
+      # alternative to {#remote_list} when only names are needed — in
+      # particular, it returns the raw name (e.g. `"team/upstream"`) preserving
+      # any slashes in the remote name.
+      #
+      # @example Get all remote names
+      #   repo.remote_names  #=> ["origin", "upstream"]
+      #
+      # @example With a slash-containing remote name
+      #   repo.remote_names  #=> ["origin", "team/upstream"]
+      #
+      # @return [Array<String>] the configured remote names
+      #
+      #   Returns an empty array when no remotes are configured.
+      #
+      # @raise [Git::FailedError] if git exits with a non-zero exit status
+      #
+      # @api public
+      #
+      def remote_names
+        Git::Commands::Remote::List.new(@execution_context).call.stdout.split("\n")
+      end
+
       # Option keys accepted by {#ls_remote}
       #
       # @return [Array<Symbol>]

data/lib/git/repository/staging.rb

@@ -118,8 +118,8 @@ module Git
       #
       def reset_hard(commitish = nil, opts = {})
         Git::Deprecation.warn(
-          'Git::Repository::Staging#reset_hard is deprecated and will be removed in a future version. ' \
-          'Use #reset(commitish, hard: true) instead.'
+          'Git::Repository#reset_hard is deprecated and will be removed in v6.0.0. ' \
+          'Use Git::Repository#reset(commitish, hard: true) instead.'
         )
         reset(commitish, **opts, hard: true)
       end
@@ -438,8 +438,17 @@ module Git
         # @raise [ArgumentError] when a deprecated value is not `true`, `false`, or `nil`
         #
         def migrate_clean_legacy_options(opts)
-          opts = deprecate_clean_option(:ff, ':ff option is deprecated. Use force: 2 instead.', opts)
-          deprecate_clean_option(:force_force, ':force_force option is deprecated. Use force: 2 instead.', opts)
+          opts = deprecate_clean_option(
+            :ff,
+            ':ff option is deprecated and will be removed in v6.0.0. Use force: 2 instead.',
+            opts
+          )
+
+          deprecate_clean_option(
+            :force_force,
+            ':force_force option is deprecated and will be removed in v6.0.0. Use force: 2 instead.',
+            opts
+          )
         end
 
         # Translate a single deprecated clean option key onto `:force`

data/lib/git/repository/stashing.rb

@@ -65,7 +65,7 @@ module Git
       #
       def stash_list
         Git::Deprecation.warn(
-          'Git::Repository#stash_list is deprecated and will be removed in a future version. ' \
+          'Git::Repository#stash_list is deprecated and will be removed in v6.0.0. ' \
           'Use Git::Repository#stashes_all instead.'
         )
         result = Git::Commands::Stash::List.new(@execution_context).call

data/lib/git/repository/status_operations.rb

@@ -58,7 +58,7 @@ module Git
       #
       def empty?
         Git::Deprecation.warn(
-          'Git::Repository#empty? is deprecated and will be removed in a future version. ' \
+          'Git::Repository#empty? is deprecated and will be removed in v6.0.0. ' \
           'Use Git::Repository#no_commits? instead.'
         )
         no_commits?

data/lib/git/version.rb

@@ -4,7 +4,7 @@ module Git
   # The current gem version
   #
   # @return [String] the current gem version
-  VERSION = '5.0.0.beta.5'
+  VERSION = '5.0.0'
 
   # Represents a git version with major, minor, and patch components
   #

data/lib/git.rb

@@ -72,11 +72,13 @@ require 'git/file_ref'
 require 'git/fsck_object'
 require 'git/fsck_result'
 require 'git/parsers/ls_remote'
+require 'git/parsers/remote'
 require 'git/version_constraint'
 require 'git/commands'
 require 'git/log'
 require 'git/object'
 require 'git/remote'
+require 'git/remote_info'
 require 'git/repository'
 require 'git/status'
 require 'git/stash'
@@ -116,7 +118,7 @@ module Git
   # `Git::Base` is a module included in {Git::Repository}, so any instance
   # methods added to `Git::Base` are automatically available on
   # {Git::Repository} instances. A deprecation warning is emitted for each
-  # method added, encouraging migration to {Git::Repository}.
+  # method added, encouraging migration to an application-owned extension module.
   #
   # @example Monkeypatching Git::Base (deprecated)
   #   module Git::Base
@@ -124,16 +126,17 @@ module Git
   #   end
   #   Git.open('.').my_helper  # => "hello"
   #
-  # @deprecated Define instance methods on {Git::Repository} instead.
+  # @deprecated Move custom methods to an application-owned extension module and
+  #   include or prepend it into {Git::Repository}.
   #
   # @api public
   Base = Module.new do
     # Emit a deprecation warning each time a method is defined in Git::Base so
-    # that authors of monkeypatches are nudged toward Git::Repository.
+    # that authors of monkeypatches are nudged toward application-owned extensions.
     def self.method_added(method_name)
       Git::Deprecation.warn(
         'Monkeypatching Git::Base is deprecated and will be removed in v6.0.0. ' \
-        "Define #{method_name} in Git::Repository instead."
+        "Move #{method_name} to an application-owned extension module for Git::Repository."
       )
       super
     end
@@ -751,7 +754,7 @@ module Git
   def self.binary_version(binary_path = nil)
     binary_path ||= Git::Config.instance.binary_path
     Git::Deprecation.warn(
-      'Git.binary_version is deprecated and will be removed in 6.0. ' \
+      'Git.binary_version is deprecated and will be removed in v6.0.0. ' \
       'Use Git.git_version instead, which returns a Git::Version ' \
       '(not an Array). For the legacy array shape, call: Git.git_version.to_a. ' \
       'The optional binary_path argument is preserved: Git.git_version(binary_path).'

data/redesign/branch_parse_refactor_plan.md

@@ -0,0 +1,163 @@
+# Plan: Fix Issue #919 — BranchInfo slash-remote parsing (PR series)
+
+## Goal
+Fix `BranchInfo#remote_name` and `#short_name` for remote names containing `/`
+(e.g. `team/upstream`). Root cause: `BRANCH_REFNAME_REGEXP` uses `[^/]+` which
+can only capture one path segment. Fix: resolve at parse time using the configured
+remote list.
+
+## PR sequence overview
+- **PR 1** — Add `remote_names` facade method. Independent. No deps.
+- **PR 2** — `BranchInfo` stored fields + remote-aware parser. Independent. No deps.
+- **PR 3** — Wire `branch_list` end-to-end (closes #919). Depends on PR 1 + PR 2.
+
+PR 1 and PR 2 can be developed in parallel. PR 3 merges last.
+
+```
+PR1 ─┐
+     ├─> PR3 (closes #919)
+PR2 ─┘
+```
+
+---
+
+## PR 1 — Add `remote_names` to RemoteOperations
+**Branch:** `feat/remote-names`
+**Depends on:** nothing
+**Value:** new public API `repo.remote_names` → `Array<String>` (lightweight; no RemoteInfo).
+
+### Changes
+- `lib/git/repository/remote_operations.rb`: add `remote_names` near `remotes` (~line 592).
+  - Calls `Git::Commands::Remote::List.new(@execution_context).call`, splits stdout on `"\n"`.
+  - Returns `Array<String>`. Empty array when no remotes.
+  - Full YARD with `@api public`, `@example`, `@return`, `@raise [Git::FailedError]`.
+
+### Tests
+- `spec/unit/git/repository/remote_operations_spec.rb`: stub `Commands::Remote::List` →
+  stdout `"origin\nteam/upstream\n"`, assert `["origin", "team/upstream"]`; empty-stdout → `[]`.
+- `spec/integration/git/repository/remote_operations_spec.rb`: real repo with two remotes
+  (one slash name), assert both names are returned.
+
+### Done when
+- Unit + integration green; RuboCop clean; YARD coverage clean.
+
+---
+
+## PR 2 — BranchInfo stored fields + remote-aware parser
+**Branch:** `feat/branchinfo-slash-remote-parsing`
+**Depends on:** nothing (backward compatible; default behavior unchanged)
+**Value:** `Git::Parsers::Branch.parse_list(stdout, remote_names: [...])` resolves slash
+remotes correctly; `BranchInfo` can carry an explicit `remote_name` (with `short_name` derived).
+
+### Changes — `lib/git/branch_info.rb`
+- **Alt 1-lite: store ONLY `:remote_name` as a new `Data.define` member; keep `short_name`
+  DERIVED (not a member).**
+- Add `:remote_name` to the `Data.define` member list (NOT `:short_name`).
+- Add `initialize` override inside the block using private `UNSET = Object.new.freeze`
+  sentinel: when `remote_name:` not supplied, derive via `BRANCH_REFNAME_REGEXP`
+  (preserves all existing `BranchInfo.new` callsites); when supplied, store as given.
+- Keep `short_name` as a COMPUTED method: derive from `refname` given the (now reliable)
+  `remote_name` — strip `(refs/)?remotes/<remote_name>/` for remote branches, or
+  `refs/heads/` for local branches. Deterministic from `refname` + `remote_name`, so it
+  never needs storing and stays out of `Data` equality/hash/with.
+- Remove only the `remote_name` computed method body (now a field accessor); `short_name`
+  stays a method (rewritten to use `remote_name`).
+- Keep `detached?`, `unborn?`, `remote?`, `current?`, `other_worktree?`, `symref?`, `to_s`.
+- YARD: add `@!attribute` doc for the single new stored field `remote_name`; keep `short_name`
+  documented as a derived method; soften the `BRANCH_REFNAME_REGEXP` `@note` (now a fallback
+  used inside `initialize`, not the sole path).
+
+### Changes — `lib/git/parsers/branch.rb`
+- Add private `resolve_remote_name(refname, remote_names)`:
+  - `nil` if refname is not under `(refs/)?remotes/`.
+  - Strip `(refs/)?remotes/` prefix; select configured names that are a prefix of `path + "/"`;
+    pick the LONGEST match.
+  - When `remote_names` empty OR no match (stale ref): fall back to single-segment regex.
+- `build_branch_info(fields, remote_names: [])`: call `resolve_remote_name`; pass only
+  `:remote_name` explicitly to `BranchInfo.new` (`short_name` is derived by BranchInfo).
+- Thread `remote_names:` through `parse_branch_line(line, remote_names: [])` and
+  `parse_list(stdout, remote_names: [])`. Default `[]` = current behavior (regex fallback).
+- YARD `@param remote_names` on the three methods.
+- Note: no separate `resolve_short_name` helper needed — BranchInfo derives `short_name`
+  from `refname` + the resolved `remote_name`.
+
+### Tests
+- `spec/unit/git/branch_info_spec.rb`: existing callsites unchanged (fallback); add examples
+  that an explicit `remote_name:` is stored and that `short_name` is correctly derived from it
+  (incl. slash-remote case); equality note (`Data#==` now includes ONE new member,
+  `remote_name` — for non-slash remotes regex==explicit so still equal). Audit for `.with` usage.
+- `spec/unit/git/parsers/branch_spec.rb`: update stubs to new signature; add
+  `parse_list(stdout, remote_names: ['team/upstream'])` correctness (both `remote_name` and the
+  derived `short_name`); longest-prefix example (both `team` and `team/upstream` configured →
+  `team/upstream` wins); stale-ref fallback example.
+- `spec/integration/git/parsers/branch_spec.rb`: repo with `team/upstream` remote,
+  `remote_names: ['team/upstream']` → correct `remote_name`/`short_name`.
+
+### Done when
+- All existing branch specs still green (no behavior change at default); new specs green;
+  RuboCop + YARD clean.
+
+---
+
+## PR 3 — Wire `branch_list` end-to-end (closes #919)
+**Branch:** `fix/919-branch-list-slash-remote`
+**Depends on:** PR 1 (`remote_names`) + PR 2 (parser accepts `remote_names:`)
+**Value:** `repo.branch_list`, `repo.branches`, `branches_all`, and `Git::Branches#[]` all
+report correct remote/branch split for slash remotes. Closes #919.
+
+### Changes — `lib/git/repository/branching.rb`
+- `branch_list(*patterns, remote_names: nil)`:
+  - When `remote_names` nil, call `self.remote_names` to fetch automatically.
+  - Pass `remote_names:` to `Git::Parsers::Branch.parse_list`.
+
+### Changes — docs / scope note
+- `lib/git/branch.rb`: update the `@note` on `BRANCH_NAME_REGEXP` (the string-constructor path)
+  to state slash remotes are not resolved there and reference #919 + the follow-up issue.
+
+### Tests
+- `spec/unit/git/repository/branching_spec.rb` `#branch_list`: update `parse_list` stub
+  expectations to `(stdout, remote_names: [...])`; add test that `remote_names` is auto-called
+  when not given; add test that explicit `remote_names:` bypasses the auto call.
+- `spec/integration/git/repository/branching_spec.rb`: repo with `team/upstream` remote →
+  `branch_list` returns `BranchInfo` with `remote_name == 'team/upstream'`, `short_name == 'main'`.
+- `spec/unit/git/branches_spec.rb` (or integration): `Git::Branches#[]` lookup with a slash
+  remote resolves correctly (`branch.full` = `remotes/team/upstream/main`, and the
+  `remotes/`-stripped key works).
+
+### Finalize
+- File a follow-up issue for the `Git::Branch` string-constructor path
+  (`BRANCH_NAME_REGEXP`) and link it from the `@note` and from #919.
+- Confirm #919 acceptance examples (`remote_name` → `'team/upstream'`, `short_name` →
+  `'feature/foo'`) are covered by integration tests.
+
+### Done when
+- Full suite green; RuboCop + YARD clean; #919 examples demonstrably fixed; follow-up issue filed.
+
+---
+
+## Accepted decisions (finalized)
+1. String path (`Git::Branch::BRANCH_NAME_REGEXP`): leave as documented limitation (PR 3 note +
+   follow-up issue). Not fixed in this series.
+2. Design is **Alt 1-lite**: store ONLY `remote_name` as a new `Data.define` member; keep
+   `short_name` derived from `refname` + `remote_name`. One new member → smaller
+   equality/hash/with footprint than storing both.
+3. Stale `refs/remotes/` ref matching no configured remote: fall back to single-segment regex.
+4. Keyword arg named `remote_names:` everywhere (parser + facade).
+5. Add BOTH unit and integration tests for `remote_names`.
+6. Defer the two-pass "only fetch remotes if refs/remotes present" optimization.
+7. Full YARD updates in each PR.
+8. Add a `Git::Branches#[]` slash-remote lookup test (PR 3).
+9. #919 is satisfied by PR 3 (issue is scoped to `BranchInfo#remote_name`/`#short_name`).
+
+## Relevant files
+- `lib/git/repository/remote_operations.rb` — PR 1 (`remote_names`)
+- `lib/git/branch_info.rb` — PR 2 (fields, `initialize`, YARD)
+- `lib/git/parsers/branch.rb` — PR 2 (`remote_names:` threading, resolve helpers)
+- `lib/git/repository/branching.rb` — PR 3 (`branch_list`)
+- `lib/git/branch.rb` — PR 3 (string-path `@note` only; no code fix)
+- specs: remote_operations (PR1), branch_info + parsers/branch (PR2), branching + branches (PR3)
+
+## Not changing (auto-correct after PR 3)
+- `branches_all` — uses `info.remote_name`/`#short_name`; values become correct.
+- `Git::Branch#initialize_from_branch_info` — uses these; values become correct.
+- All existing `BranchInfo.new` callsites — `initialize` fallback keeps them working.

data/redesign/info_object_migration_plan.md

@@ -0,0 +1,126 @@
+# Plan: Migrate ActiveRecord-style classes to `*Info` value objects
+
+This document is the durable summary and issue index for the effort to migrate
+ruby-git's "ActiveRecord-style" domain classes (rich objects constructed with
+`def initialize(base, ...)` that both hold data **and** perform git operations)
+toward immutable `*Info` value objects (DAOs), following the pattern established
+by `Git::BranchInfo` and `Git::RemoteInfo`.
+
+It captures analysis and decisions so they are not re-derived in future sessions.
+It is a planning/index document, not a specification — each tracked issue owns the
+detailed design for its area.
+
+## Contents
+
+- [Motivation](#motivation)
+- [The pattern](#the-pattern)
+- [Status of each class](#status-of-each-class)
+- [Issue index](#issue-index)
+- [Versioning and sequencing](#versioning-and-sequencing)
+- [Key decisions](#key-decisions)
+- [Open threads / not yet tracked](#open-threads--not-yet-tracked)
+
+## Motivation
+
+The modern facade design returns immutable, parser-built value objects
+(`Git::BranchInfo`, `Git::RemoteInfo`, `Git::StashInfo`, `Git::TagInfo`,
+`Git::ConfigEntryInfo`, the `Diff*Info` family, …). Several older classes predate
+this and mix data with operations while holding a repository reference (`@base`).
+They are harder to test, encourage stateful usage, and (in some cases) carry
+latent bugs. Migrating them to `*Info` value objects plus name-based facade
+operations aligns the whole API and unblocks cleaner deprecations.
+
+The recurring "tell" for a migration candidate is a `def initialize(base, ...)`
+constructor combined with operation methods — the object both *is* data and
+*does* work.
+
+## The pattern
+
+For each domain:
+
+1. **Value object** — an immutable `Data.define` `*Info` at the top-level `Git::`
+   namespace holding only parsed metadata, with `#to_s` returning the string a
+   caller can pass back to git-facing methods (e.g. a refname or stash selector).
+2. **Parser** — a `Git::Parsers::*` that builds `Array<*Info>` from raw git output.
+3. **Facade** — `Git::Repository::*` methods that return the value objects and that
+   accept names / `*Info` / any `#to_s` for operations.
+4. **Deprecation** — the legacy AR class, its collection, and the facade methods
+   that return them are deprecated (additive, non-breaking) in one major and
+   removed in the next.
+
+## Status of each class
+
+| Domain | AR class(es) | Value object | State |
+| --- | --- | --- | --- |
+| Branch | `Git::Branch` / `Git::Branches` | `Git::BranchInfo`, `Git::DetachedHeadInfo` | Value object + `branch_list` shipped; deprecation of AR classes tracked (#1639) |
+| Remote | `Git::Remote` | `Git::RemoteInfo` | `RemoteInfo` + parser shipped; `remotes` deprecation tracked (#1640); `Git::Remote` class deprecation tracked (#1643) |
+| Stash | `Git::Stash` / `Git::Stashes` | `Git::StashInfo` (exists) | Redesign tracked (#1634); `Git::Branch#stashes` cleanup (#1637) |
+| Worktree | `Git::Worktree` / `Git::Worktrees` | *(needs `Git::WorktreeInfo`)* | Redesign tracked (#1635) — value object + parser do not exist yet |
+| Tag | `Git::Object::Tag` | `Git::TagInfo` (exists) | Half-migrated; finish tracked under umbrella (#1636) |
+| Commit / Tree / Blob | `Git::Object::Commit/Tree/Blob` | *(none)* | Deferred, umbrella (#1636) |
+| Status | `Git::Status` / `Git::Status::StatusFile` | *(none)* | Deferred, umbrella (#1636) |
+| Author | `Git::Author` (mutable) | *(none)* | Deferred, umbrella (#1636) |
+| Diff / Log | `Git::Diff`, `Git::Log` | many `Diff*Info`, `Git::Log::Result` | Value layer largely exists; return-type audit deferred (#1636) |
+
+## Issue index
+
+- **#1631** — bug: slash-containing remote names in the `Git::Branch` string
+  constructor path. Kept open; resolution is to route users to the `BranchInfo`
+  path (folds into #1639).
+- **#1634** — redesign `Git::Repository::Stashing` around `Git::StashInfo`.
+- **#1635** — redesign `Git::Repository::WorktreeOperations` around a new
+  `Git::WorktreeInfo` (needs value object + parser first).
+- **#1636** — umbrella tracker for post-7.x AR→`*Info` migrations
+  (Commit/Tree/Blob, finish Tag, Status, Author, Diff/Log audit).
+- **#1637** — deprecate `Git::Branch#stashes` (ignores the branch, returns all
+  repo stashes) in favor of `Git::Repository#stashes_all`.
+- **#1639** — deprecate `Git::Branch` / `Git::Branches` and
+  `Git::Repository#branch` / `#branches` in favor of the `BranchInfo` API.
+- **#1640** — deprecate `Git::Repository#remotes` in favor of `#remote_list`
+  (from `remote_refactor_plan.md` PR 3, Step 5).
+- **#1641** — add `Git::Repository#in_branch` and a merge-into-branch facade path
+  (preconditions for #1639).
+- **#1643** — deprecate `Git::Remote` (and `Git::Repository#remote`) in favor of
+  the `RemoteInfo` API (remote analog of #1639; depends on #1640).
+
+## Versioning and sequencing
+
+- Each migration is **additive + deprecate** in one major, **remove** in the next
+  (e.g. deprecate in 5.x → remove in 6.x, or the analogous later pair).
+- Stash (#1634) and Worktree (#1635) are the in-flight redesigns; the remaining
+  candidates in #1636 are intentionally deferred until after the 7.x cycle.
+- **Guardrail during any major:** do not add *new* public APIs that return
+  AR-style objects that are already destined for deprecation. When touching these
+  areas, prefer adding the value-object-returning method. The `Git::Object::Tag`
+  vs `Git::TagInfo` split is the most important to watch (already half-migrated).
+
+## Key decisions
+
+- **`Git::WorktreeInfo` should capture the full porcelain record** — `path`,
+  `head`, `branch`, `bare`, `detached`, `locked` (+reason), `prunable` (+reason) —
+  not just the `[dir, sha]` tuple `worktrees_all` returns today.
+- **Branch has no capability gap.** An audit confirmed every `Git::Branch`
+  operation already delegates to an existing `Git::Repository` facade method that
+  accepts a name/string. The only missing pieces are two composites — `in_branch`
+  and the `merge(branch)` overload — tracked in #1641 as deprecation preconditions.
+- **`checkout` semantic wrinkle:** `Git::Branch#checkout` auto-creates the branch
+  first; `Git::Repository#checkout(name)` does not. Deprecation notes must call
+  this out.
+- **`Git::Branch#stashes` is effectively a latent bug** — it ignores the branch
+  receiver and returns all repository stashes — so it is "deprecate and delete,"
+  not "migrate" (#1637).
+- **`Git::Repository::Branching` / `RemoteOperations` / `WorktreeOperations` are
+  the replacements, not deprecation targets.** Only the specific methods that
+  return AR objects (`#branch`, `#branches`, `#remotes`, `#worktree`,
+  `#worktrees`) are deprecated; the operation methods stay.
+- **Stashes are not branch-scoped in git**, so no branch-scoped stash API is
+  warranted.
+
+## Open threads
+
+All previously loose threads are now tracked within the issues above:
+
+- **`Git::Repository#worktree` / `#worktrees` factory deprecation** — in scope of
+  #1635 (confirmed in its transition plan).
+- **`config_remote` relationship to `remote_list`** — folded into #1640 as an open
+  question to resolve during that work.