git 5.1.0 → 5.2.0

data/redesign/config_design.rb

@@ -1,501 +0,0 @@
-# frozen_string_literal: true
-
-# This is a forward looking document (in Ruby format) on the evolution of `git
-# config` methods in Ruby Git. Here is how `git config` methods will change in
-# v5.x and v6.x.
-#
-# In v5.x, `Git.config` and `Git.global_config` will continue to work as they do in
-# v4.x but will be deprecated. New methods in the Git::Configuring module will be
-# introduced in Git and Git::Repository to provide structured access to configuration
-# entries. These will not be strict drop-in replacements for the existing deprecated
-# methods.
-#
-# In v6.x, the deprecated methods will be removed.
-
-# Top level Git module
-module Git
-  # Represents a single Git configuration entry
-  #
-  # @example
-  #   scope = 'local'
-  #   origin = 'path/to/config'
-  #   key = 'remote.origin.url'
-  #   value = 'https://github.com/ruby-git/ruby-git'
-  #   entry = Git::ConfigEntryInfo.new(scope:, origin:, key: , value:)
-  #
-  # @!attribute [r] scope
-  #
-  #   The scope of the configuration entry
-  #
-  #   May be one of "system", "global", "local", "worktree", "file", or "blob".
-  #
-  #   @return [String]
-  #
-  # @!attribute [r] origin
-  #
-  #   Where the configuration entry originates
-  #
-  #   The origin is in the format: `<origin-type>:<actual-origin>`. It is never
-  #   blank.
-  #
-  #   ### `origin-type`
-  #
-  #   This prefix explains the context of the configuration source. The four possible
-  #   types are `file:`, `blob:`, `command line:`, and `standard input:`.
-  #
-  #   ### `actual-origin`
-  #
-  #   This provides the specific location for the configuration source. Only the
-  #   `file:` and `blob:` origin types have an actual origin. For `command line:` and
-  #   `standard input:`, Git drops this portion entirely and places the tab character
-  #   immediately after the colon.
-  #
-  #   #### Path Resolution
-  #
-  #   When the origin type is a file, the actual origin can be formatted as either an
-  #   absolute or relative path depending on how Git resolves it.
-  #
-  #     - **Absolute Paths**: Git outputs the full system path for system-level configurations,
-  #       global configurations, explicitly provided absolute paths, or absolute
-  #       paths used in [include] directives.
-  #     - **Relative Paths**: Git outputs a relative path for local repository configurations,
-  #       explicitly provided relative paths, or relative paths used in [include]
-  #       directives.
-  #     - **Relative Anchors**: Local repository paths are relative to the repository
-  #       root. Command-line relative paths are relative to your current working
-  #       directory. Relative paths from an [include] directive are anchored to
-  #       the parent configuration file that included them.
-  #
-  #   @return [String]
-  #
-  # @!attribute [r] key
-  #
-  #   The full key name of the configuration entry (e.g., remote.origin.url)
-  #
-  #   @return [String]
-  #
-  # @!attribute [r] value
-  #
-  #   The value of the configuration entry
-  #
-  #   @return [String]
-  #
-  # @api public
-  #
-  ConfigEntryInfo = Data.define(:scope, :origin, :key, :value) do
-    # Everything up to the first dot in the {key}
-    #
-    # Returns an empty string if {key} contains no dot.
-    #
-    # @example
-    #   entry.section # => 'remote'
-    #
-    # @return [String]
-    #
-    def section = first_dot ? key[0...first_dot] : ''
-
-    # Everything between the first and last dot in the {key}
-    #
-    # Returns an empty string if {key} has no subsection (zero or one dot).
-    #
-    # @example
-    #   entry.subsection # => 'origin'
-    #
-    # @return [String]
-    #
-    def subsection = first_dot && first_dot != last_dot ? key[(first_dot + 1)...last_dot] : ''
-
-    # Everything after the last dot in the {key}
-    #
-    # Returns the full {key} if {key} contains no dot.
-    #
-    # @example
-    #   entry.variable # => 'url'
-    #
-    # @return [String]
-    #
-    def variable = last_dot ? key[(last_dot + 1)..] : key
-
-    private
-
-    def first_dot = key.index('.')
-
-    def last_dot = key.rindex('.')
-  end
-
-  module Parsers
-    # Parser for `git config --get` and `git config --list` output
-    # when called with `--show-scope --show-origin --null`.
-    #
-    # @api private
-    #
-    module ConfigEntry
-      module_function
-
-      # Parse `git config --get --show-scope --show-origin --null` output.
-      #
-      # Output format (per entry): `scope\0origin\0value\0`
-      # The key name is not present in --get output; it must be supplied.
-      #
-      # @param key [String] the config key name that was queried
-      # @param output [String] raw stdout from the command
-      # @return [Git::ConfigEntryInfo, nil] the parsed entry, or nil if not found
-      #
-      def parse_get(key, output)
-        return nil if output.empty?
-
-        scope, origin, value = output.split("\0", -1)
-        Git::ConfigEntryInfo.new(scope: scope, origin: origin, key: key, value: value)
-      end
-
-      # Parse `git config --get-all --show-scope --show-origin --null` output.
-      #
-      # Output format (per entry): `scope\0origin\0value\0`
-      # The key name is not present in --get-all output; it must be supplied.
-      # Entries repeat back-to-back in the same string.
-      #
-      # @param key [String] the config key name that was queried
-      # @param output [String] raw stdout from the command
-      # @return [Array<Git::ConfigEntryInfo>] the parsed entries
-      #
-      def parse_get_all(key, output)
-        return [] if output.empty?
-
-        tokens = output.split("\0", -1)
-        tokens.pop if tokens.last && tokens.last.empty?
-        tokens.each_slice(3).map do |scope, origin, value|
-          Git::ConfigEntryInfo.new(scope: scope, origin: origin, key: key, value: value)
-        end
-      end
-
-      # Parse `git config --list --show-scope --show-origin --null` output.
-      #
-      # Also used for `--get-regexp` and `--get-urlmatch` output, which share
-      # the same format.
-      #
-      # Output format (per entry): `scope\0origin\0key\nvalue\0`
-      # Entries repeat back-to-back in the same string.
-      #
-      # @param output [String] raw stdout from the command
-      # @return [Array<Git::ConfigEntryInfo>] the parsed entries
-      #
-      def parse_list(output)
-        return [] if output.empty?
-
-        tokens = output.split("\0", -1)
-        tokens.pop if tokens.last && tokens.last.empty?
-        tokens.each_slice(3).map do |scope, origin, key_value|
-          key, value = key_value.split("\n", 2)
-          Git::ConfigEntryInfo.new(scope: scope, origin: origin, key: key, value: value || '')
-        end
-      end
-    end
-  end
-
-  # Designed to be included in the Git module and the Git::Repository module
-  #
-  # The including/extending class must implement {#execution_context} and
-  # {#assert_valid_scope!}.
-  #
-  module Configuring # rubocop:disable Metrics/ModuleLength
-    # @!group Read Operations
-
-    CONFIG_GET_ALLOWED_OPTS = %i[global system local worktree file f blob includes no_includes type default].freeze
-    private_constant :CONFIG_GET_ALLOWED_OPTS
-
-    # @return [Git::ConfigEntryInfo, nil] nil if the key is not found
-    def config_get(name, value_regex = nil, **options)
-      Private.assert_valid_opts!(CONFIG_GET_ALLOWED_OPTS, **options)
-      assert_valid_scope!(**options)
-      options = options.merge(show_scope: true, show_origin: true, null: true)
-      cmd = Git::Commands::ConfigOptionSyntax::Get.new(execution_context)
-      output = cmd.call(name, value_regex, **options).stdout
-      Git::Parsers::ConfigEntry.parse_get(name, output)
-    end
-
-    CONFIG_GET_ALL_ALLOWED_OPTS = %i[global system local worktree file f blob includes no_includes type].freeze
-    private_constant :CONFIG_GET_ALL_ALLOWED_OPTS
-
-    # @return [Array<Git::ConfigEntryInfo>]
-    def config_get_all(name, value_regex = nil, **options)
-      Private.assert_valid_opts!(CONFIG_GET_ALL_ALLOWED_OPTS, **options)
-      assert_valid_scope!(**options)
-      options = options.merge(show_scope: true, show_origin: true, null: true)
-      cmd = Git::Commands::ConfigOptionSyntax::GetAll.new(execution_context)
-      output = cmd.call(name, value_regex, **options).stdout
-      Git::Parsers::ConfigEntry.parse_get_all(name, output)
-    end
-
-    # `git config --get --type=color [--default=<default>]` is preferred over
-    # --get-color
-    #
-    # def config_get_color(name, default = nil, **)
-    #   ...
-    # end
-
-    CONFIG_GET_COLORBOOL_ALLOWED_OPTS = %i[global system local worktree file f blob includes no_includes].freeze
-    private_constant :CONFIG_GET_COLORBOOL_ALLOWED_OPTS
-
-    # @return [String] always 'true' or 'false'
-    def config_get_colorbool(name, stdout_is_tty = nil, **)
-      Private.assert_valid_opts!(CONFIG_GET_COLORBOOL_ALLOWED_OPTS, **)
-      assert_valid_scope!(**)
-      cmd = Git::Commands::ConfigOptionSyntax::GetColorBool.new(execution_context)
-      cmd.call(name, stdout_is_tty, **).stdout.chomp
-    end
-
-    CONFIG_GET_REGEXP_ALLOWED_OPTS = %i[global system local worktree file f blob includes no_includes type].freeze
-    private_constant :CONFIG_GET_REGEXP_ALLOWED_OPTS
-
-    # @return [Array<Git::ConfigEntryInfo>]
-    def config_get_regexp(name_regex, value_regex = nil, **options)
-      Private.assert_valid_opts!(CONFIG_GET_REGEXP_ALLOWED_OPTS, **options)
-      assert_valid_scope!(**options)
-      options = options.merge(show_scope: true, show_origin: true, null: true)
-      cmd = Git::Commands::ConfigOptionSyntax::GetRegexp.new(execution_context)
-      output = cmd.call(name_regex, value_regex, **options).stdout
-      Git::Parsers::ConfigEntry.parse_list(output)
-    end
-
-    CONFIG_GET_URLMATCH_ALLOWED_OPTS = %i[global system local worktree file f blob includes no_includes type].freeze
-    private_constant :CONFIG_GET_URLMATCH_ALLOWED_OPTS
-
-    # @return [Array<Git::ConfigEntryInfo>]
-    def config_get_urlmatch(name, url, **options)
-      Private.assert_valid_opts!(CONFIG_GET_URLMATCH_ALLOWED_OPTS, **options)
-      assert_valid_scope!(**options)
-      options = options.merge(show_scope: true, show_origin: true, null: true)
-      cmd = Git::Commands::ConfigOptionSyntax::GetUrlmatch.new(execution_context)
-      output = cmd.call(name, url, **options).stdout
-      Git::Parsers::ConfigEntry.parse_list(output)
-    end
-
-    CONFIG_LIST_ALLOWED_OPTS = %i[global system local worktree file f blob includes no_includes type].freeze
-    private_constant :CONFIG_LIST_ALLOWED_OPTS
-
-    # @return [Array<Git::ConfigEntryInfo>]
-    def config_list(**options)
-      Private.assert_valid_opts!(CONFIG_LIST_ALLOWED_OPTS, **options)
-      assert_valid_scope!(**options)
-      options = options.merge(show_scope: true, show_origin: true, null: true)
-      cmd = Git::Commands::ConfigOptionSyntax::List.new(execution_context)
-      output = cmd.call(**options).stdout
-      Git::Parsers::ConfigEntry.parse_list(output)
-    end
-
-    # @!endgroup
-
-    # @!group Write Operations
-
-    CONFIG_ADD_ALLOWED_OPTS = %i[global system local worktree file f blob type].freeze
-    private_constant :CONFIG_ADD_ALLOWED_OPTS
-
-    # @return [void]
-    #
-    # @raise [ArgumentError] if unsupported options are provided
-    #
-    # @raise [Git::FailedError] if git exits with a non-zero exit status
-    def config_add(name, value, **)
-      Private.assert_valid_opts!(CONFIG_ADD_ALLOWED_OPTS, **)
-      assert_valid_scope!(**)
-      cmd = Git::Commands::ConfigOptionSyntax::Add.new(execution_context)
-      cmd.call(name, value, **)
-      nil
-    end
-
-    CONFIG_REMOVE_SECTION_ALLOWED_OPTS = %i[global system local worktree file f blob].freeze
-    private_constant :CONFIG_REMOVE_SECTION_ALLOWED_OPTS
-
-    # @return [void]
-    #
-    # @raise [ArgumentError] if unsupported options are provided
-    #
-    # @raise [Git::FailedError] if git exits with a non-zero exit status
-    def config_remove_section(name, **)
-      Private.assert_valid_opts!(CONFIG_REMOVE_SECTION_ALLOWED_OPTS, **)
-      assert_valid_scope!(**)
-      cmd = Git::Commands::ConfigOptionSyntax::RemoveSection.new(execution_context)
-      cmd.call(name, **)
-      nil
-    end
-
-    CONFIG_RENAME_SECTION_ALLOWED_OPTS = %i[global system local worktree file f blob].freeze
-    private_constant :CONFIG_RENAME_SECTION_ALLOWED_OPTS
-
-    # @return [void]
-    #
-    # @raise [ArgumentError] if unsupported options are provided
-    #
-    # @raise [Git::FailedError] if git exits with a non-zero exit status
-    def config_rename_section(old_name, new_name, **)
-      Private.assert_valid_opts!(CONFIG_RENAME_SECTION_ALLOWED_OPTS, **)
-      assert_valid_scope!(**)
-      cmd = Git::Commands::ConfigOptionSyntax::RenameSection.new(execution_context)
-      cmd.call(old_name, new_name, **)
-      nil
-    end
-
-    CONFIG_REPLACE_ALL_ALLOWED_OPTS = %i[global system local worktree file f blob type].freeze
-    private_constant :CONFIG_REPLACE_ALL_ALLOWED_OPTS
-
-    # @return [void]
-    #
-    # @raise [ArgumentError] if unsupported options are provided
-    #
-    # @raise [Git::FailedError] if git exits with a non-zero exit status
-    def config_replace_all(name, value, value_regex = nil, **)
-      Private.assert_valid_opts!(CONFIG_REPLACE_ALL_ALLOWED_OPTS, **)
-      assert_valid_scope!(**)
-      cmd = Git::Commands::ConfigOptionSyntax::ReplaceAll.new(execution_context)
-      cmd.call(name, value, value_regex, **)
-      nil
-    end
-
-    CONFIG_SET_ALLOWED_OPTS = %i[global system local worktree file f blob type].freeze
-    private_constant :CONFIG_SET_ALLOWED_OPTS
-
-    # @return [void]
-    #
-    # @raise [ArgumentError] if unsupported options are provided
-    #
-    # @raise [Git::FailedError] if git exits with a non-zero exit status
-    def config_set(name, value, **)
-      Private.assert_valid_opts!(CONFIG_SET_ALLOWED_OPTS, **)
-      assert_valid_scope!(**)
-      cmd = Git::Commands::ConfigOptionSyntax::Set.new(execution_context)
-      cmd.call(name, value, **)
-      nil
-    end
-
-    CONFIG_UNSET_ALLOWED_OPTS = %i[global system local worktree file f blob].freeze
-    private_constant :CONFIG_UNSET_ALLOWED_OPTS
-
-    # @return [void]
-    #
-    # @raise [ArgumentError] if unsupported options are provided
-    #
-    # @raise [Git::FailedError] if git exits with a non-zero exit status
-    def config_unset(name, value_regex = nil, **)
-      Private.assert_valid_opts!(CONFIG_UNSET_ALLOWED_OPTS, **)
-      assert_valid_scope!(**)
-      cmd = Git::Commands::ConfigOptionSyntax::Unset.new(execution_context)
-      cmd.call(name, value_regex, **)
-      nil
-    end
-
-    CONFIG_UNSET_ALL_ALLOWED_OPTS = %i[global system local worktree file f blob].freeze
-    private_constant :CONFIG_UNSET_ALL_ALLOWED_OPTS
-
-    # @return [void]
-    #
-    # @raise [ArgumentError] if unsupported options are provided
-    #
-    # @raise [Git::FailedError] if git exits with a non-zero exit status
-    def config_unset_all(name, value_regex = nil, **)
-      Private.assert_valid_opts!(CONFIG_UNSET_ALL_ALLOWED_OPTS, **)
-      assert_valid_scope!(**)
-      cmd = Git::Commands::ConfigOptionSyntax::UnsetAll.new(execution_context)
-      cmd.call(name, value_regex, **)
-      nil
-    end
-
-    # @!endgroup
-
-    private
-
-    # @abstract Including/extending class must implement execution_context
-    #
-    # @return [Git::ExecutionContext]
-    #
-    def execution_context
-      raise NotImplementedError
-    end
-
-    # @abstract Including/extending class must implement assert_valid_scope!
-    #
-    # Called before every config operation to validate that the requested scope
-    # is appropriate for the context (e.g., repository-specific scopes such as
-    # `local` are not valid when called without a repository).
-    #
-    # @raise [ArgumentError] if the scope is not permitted in this context
-    #
-    # @return [void]
-    #
-    def assert_valid_scope!(**)
-      raise NotImplementedError
-    end
-
-    # Internal helpers local to {Git::Configuring}
-    #
-    # @api private
-    #
-    module Private
-      module_function
-
-      # Validate that `options` contains only keys listed in `allowed`
-      #
-      # @example Reject an undocumented option
-      #   Private.assert_valid_opts!(%i[all force], bogus: true)
-      #   #=> raises ArgumentError: Unknown options: bogus
-      #
-      # @param allowed [Array<Symbol>] the keys permitted by the facade method
-      #
-      # @param options [Hash] the options hash provided by the caller
-      #
-      # @return [void]
-      #
-      # @raise [ArgumentError] when `options` contains any key not in `allowed`
-      #
-      def assert_valid_opts!(allowed, **options)
-        unknown = options.keys - allowed
-        return if unknown.empty?
-
-        raise ArgumentError, "Unknown options: #{unknown.join(', ')}"
-      end
-    end
-    private_constant :Private
-  end
-
-  REPOSITORY_SPECIFIC_SCOPES = %i[local worktree blob].freeze
-  private_constant :REPOSITORY_SPECIFIC_SCOPES
-
-  # Reopens Git::Repository to mix in config read/write operations.
-  #
-  # In the real implementation this `include` lives in
-  # `lib/git/repository/configuring.rb` and is picked up by the
-  # `Git::Repository` class definition in `lib/git/repository.rb`.
-  class Repository
-    # Mixes in config_get, config_list, config_set, etc.
-    include Git::Configuring
-
-    private
-
-    # @return [Git::ExecutionContext::Repository]
-    attr_reader :execution_context
-
-    # All scopes are permitted when called with a repository context.
-    def assert_valid_scope!(**)
-      # All scopes allowed
-    end
-  end
-
-  # Enables calling Git.config_get('user.name')
-  extend Git::Configuring
-
-  # Returns a global execution context for non-repository config operations.
-  #
-  # Overrides the abstract {Git::Configuring#execution_context} for the
-  # module-level case.
-  #
-  # @return [Git::ExecutionContext::Global]
-  def self.execution_context
-    Git::ExecutionContext::Global.new
-  end
-  private_class_method :execution_context
-
-  def self.assert_valid_scope!(**options)
-    repo_scopes = options.keys.select { |k| options[k] && REPOSITORY_SPECIFIC_SCOPES.include?(k) }
-    raise ArgumentError, "scope #{repo_scopes.first} requires a repository" if repo_scopes.any?
-  end
-  private_class_method :assert_valid_scope!
-end

data/redesign/index.md

@@ -1,34 +0,0 @@
-# Architectural Redesign Project
-
-[This project was announced in the project's README](../README.md#2025-07-09-architectural-redesign)
-
-The git gem is undergoing a significant architectural redesign for the upcoming
-v5.0.0 release. The current architecture has several design challenges that make it
-difficult to maintain and evolve. This redesign aims to address these issues by
-introducing a clearer, more robust, and more testable structure.
-
-We have prepared detailed documents outlining the analysis of the current
-architecture and the proposed changes. We encourage our community and contributors to
-review them:
-
-1. [Analysis of the Current Architecture](1_architecture_existing.md): A
-   breakdown of the existing design and its challenges.
-2. [The Proposed Redesign](2_architecture_redesign.md): An overview of the
-   new three-layered architecture.
-3. [Implementation Plan](3_architecture_implementation.md): The step-by-step
-   plan for implementing the redesign.
-
-Your feedback is welcome! Please feel free to open an issue to discuss the proposed
-changes.
-
-> **DON'T PANIC!**
->
-> While this is a major internal refactoring, our goal is to keep the primary public
-API on the main repository object as stable as possible. Most users who rely on
-documented methods like `g.commit`, `g.add`, and `g.status` should find the
-transition to v5.0.0 straightforward.
->
-> The breaking changes will primarily affect users who have been relying on the
-internal g.lib accessor, which will be removed as part of this cleanup. For more
-details, please see the "Impact on Users" section in [the redesign
-> document](2_architecture_redesign.md).

data/redesign/info_object_migration_plan.md

@@ -1,126 +0,0 @@
-# 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.