Deprecate Git::Branch and Git::Branches (and Git::Repository#branch/#branches) in favor of the BranchInfo API

[jcouball]

Summary

Deprecate the ActiveRecord-style branch objects and their facade entry points in favor of the Git::BranchInfo-based API, following the same pattern used for remotes.

Scope of deprecation:

• Git::Branch (class)
• Git::Branches (collection class)
• Git::Repository#branch — returns Git::Branch
• Git::Repository#branches — returns Git::Branches

Not deprecated: the rest of Git::Repository::Branching. That module is the replacement — branch_list, checkout, branch_new, branch_delete, branch_contains, update_ref, current_branch, etc. all stay. Only the two methods that hand back AR objects (#branch, #branches) are in scope.

Proposed timeline: deprecate as early as 5.0.0, remove in 6.0.0.

Motivation

Git::BranchInfo (immutable, remote-aware) already exists and is returned by Git::Repository#branch_list. Git::Branch/Git::Branches are the legacy def initialize(base, …) rich objects that both hold data and perform operations. Steering users to branch_list + facade operations aligns branches with the *Info DAO direction (see umbrella #1636) and sidesteps the legacy string-constructor bug in #1631.

Capability audit — no gap

Every Git::Branch operation is already a thin delegate to an existing Git::Repository facade method that accepts a name/string:

Git::Branch method	Facade equivalent
checkout	Git::Repository#checkout (see note on create-if-missing)
create	Git::Repository#branch_new
delete	Git::Repository#branch_delete
current	Git::Repository#current_branch
contains?	Git::Repository#branch_contains
update_ref	Git::Repository#update_ref
merge	Git::Repository#merge (see note on the merge(branch) overload)
archive	Git::Repository#archive
gcommit	Git::Repository#gcommit
stashes	Git::Repository#stashes_all (tracked separately in #1637)
full / name / remote	Git::BranchInfo#refname / #short_name / #remote_name

Git::Branches (collection): each/[]/local/remote/size map onto Git::Repository#branch_list (which returns Array<Git::BranchInfo>) plus array operations.

Preconditions (do before deprecating the composites)

Two Git::Branch methods are multi-step conveniences with no single facade equivalent. Provide replacements first so the deprecation notes can point somewhere real:

1. in_branch(message) { … } — temp checkout → commit-or-reset → restore original branch. Re-home as a Git::Repository#in_branch facade method (or document a recipe).
2. merge(branch) overload — "merge X into branch Y without checking out Y first." The bare facade #merge merges into the current branch, so add a facade path or document the recipe.

Semantic wrinkles to document in the deprecation notes

• checkout auto-creates: Git::Branch#checkout calls check_if_create before checking out; Git::Repository#checkout(name) does not. Call this out so migrators aren't surprised.
• Return-shape change: #branches returns an enumerable of Git::Branch; branch_list returns Array<Git::BranchInfo>. Access shifts from branch.name to info.short_name, etc.
• #stashes is a latent-bug method (ignores the branch, returns all repo stashes) — already split out to Deprecate Git::Branch#stashes in favor of Git::Repository#stashes_all #1637.

Per-method deprecation messages (draft)

Each warning should name the exact replacement, e.g.:

• git.branch('x') → "Use repo.branch_list / repo.branch_contains / name-based facade methods instead."
• git.branch('x').delete → repo.branch_delete('x')
• git.branch('x').checkout → repo.checkout('x') (note: no auto-create)
• git.branches → repo.branch_list
• git.branches['x'] → repo.branch_list.find { |b| b.short_name == 'x' }

Use the existing Git::Deprecation.warn pattern (as in Git::Repository#stash_list).

Suggested sequencing

1. Land the in_branch and merge-into-branch facade replacements.
2. Deprecate the 1:1-replaceable methods/accessors first (#branch, #branches, and the Git::Branch operation methods that already have exact facade equivalents).
3. Hold deprecation of in_branch / merge(branch) until step 1 ships.
4. Ensure deprecation messages don't point at other about-to-be-deprecated APIs (e.g., don't route #stashes users through Git::Stashes).

Blast radius

Git::Branch, Git::Branches, #branch, #branches are core, high-traffic, @api public. Expect significant deprecation-warning volume; phasing (above) keeps 5.0.0 warnings honest and each pointed at a real replacement.

Testing

• Unit specs asserting each deprecation warning fires (mirror the stash_list deprecation test).
• Specs for the new in_branch / merge-into-branch facade methods.
• UPGRADING.md migration section with the per-method mapping above.

Affected files (initial)

• lib/git/branch.rb, lib/git/branches.rb
• lib/git/repository/branching.rb (#branch, #branches; new in_branch/merge path)
• spec/unit/git/branch_spec.rb, spec/unit/git/branches_spec.rb, spec/unit/git/repository/branching_spec.rb
• UPGRADING.md

Related

• Resolve slash-containing remote names in Git::Branch string constructor path #1631 — slash-remote bug in Git::Branch string constructor (supports moving users to the BranchInfo path)
• Deprecate Git::Branch#stashes in favor of Git::Repository#stashes_all #1637 — deprecate Git::Branch#stashes (sub-case of this effort)
• [post-7.x] Migrate remaining ActiveRecord-style classes to *Info DAO objects (umbrella) #1636 — umbrella *Info/DAO migration
• redesign/branch_parse_refactor_plan.md