git 4.3.2 → 5.0.0.beta.1

data/CONTRIBUTING.md

@@ -8,23 +8,39 @@
 - [Summary](#summary)
 - [How to contribute](#how-to-contribute)
 - [How to report an issue or request a feature](#how-to-report-an-issue-or-request-a-feature)
+- [Local development setup](#local-development-setup)
+  - [Prerequisites](#prerequisites)
+  - [Bootstrap the project](#bootstrap-the-project)
+  - [Verify the toolchain](#verify-the-toolchain)
+  - [Contributor validation policy](#contributor-validation-policy)
 - [How to submit a code or documentation change](#how-to-submit-a-code-or-documentation-change)
   - [Commit your changes to a fork of `ruby-git`](#commit-your-changes-to-a-fork-of-ruby-git)
   - [Create a pull request](#create-a-pull-request)
   - [Get your pull request reviewed](#get-your-pull-request-reviewed)
+  - [Before requesting review](#before-requesting-review)
 - [Branch strategy](#branch-strategy)
 - [AI-assisted contributions](#ai-assisted-contributions)
 - [Design philosophy](#design-philosophy)
-  - [Direct mapping to git commands](#direct-mapping-to-git-commands)
+- [Command-layer neutrality](#command-layer-neutrality)
+- [Wrapping a git command](#wrapping-a-git-command)
+  - [Method placement](#method-placement)
+  - [Method naming](#method-naming)
+  - [Result class naming](#result-class-naming)
   - [Parameter naming](#parameter-naming)
+  - [Parameter values](#parameter-values)
+    - [Options](#options)
+    - [Positional arguments](#positional-arguments)
   - [Output processing](#output-processing)
+  - [From design to implementation](#from-design-to-implementation)
+  - [Example implementations](#example-implementations)
 - [Coding standards](#coding-standards)
   - [Commit message guidelines](#commit-message-guidelines)
     - [What does this mean for contributors?](#what-does-this-mean-for-contributors)
     - [What to know about Conventional Commits](#what-to-know-about-conventional-commits)
+    - [Issue and PR references](#issue-and-pr-references)
   - [Unit tests](#unit-tests)
-  - [Continuous integration](#continuous-integration)
-  - [Documentation](#documentation)
+    - [RSpec best practices](#rspec-best-practices)
+    - [Unit tests vs Integration tests](#unit-tests-vs-integration-tests)
 - [Building a specific version of the Git command-line](#building-a-specific-version-of-the-git-command-line)
   - [Install pre-requisites](#install-pre-requisites)
   - [Obtain Git source code](#obtain-git-source-code)
@@ -44,8 +60,7 @@ If you have suggestions for improving these guidelines, please propose changes v
 pull request.
 
 Please also review and adhere to our [Code of Conduct](CODE_OF_CONDUCT.md) when
-participating in the project.
-Governance and maintainer expectations are described in
+participating in the project. Governance and maintainer expectations are described in
 [GOVERNANCE.md](GOVERNANCE.md).
 
 ## How to contribute
@@ -67,6 +82,60 @@ To report an issue or request a feature, please [create a `ruby-git` GitHub
 issue](https://github.com/ruby-git/ruby-git/issues/new). Fill in the template as
 thoroughly as possible to describe the issue or feature request.
 
+## Local development setup
+
+Before submitting a change, set up a working local development environment.
+`bin/setup` automates the bootstrap and fails fast with a clear message when a
+prerequisite is missing.
+
+### Prerequisites
+
+| Tool | Required version | Notes |
+| --- | --- | --- |
+| Ruby | `>= 3.2.0` (matches `required_ruby_version` in [`git.gemspec`](git.gemspec)) | A version manager such as [rbenv](https://github.com/rbenv/rbenv), [asdf](https://asdf-vm.com/), [chruby](https://github.com/postmodern/chruby), or [rvm](https://rvm.io/) is recommended so you can match the project's CI matrix. |
+| Bundler | Any 2.x or 4.x | Install with `gem install bundler`. |
+| git | `>= 2.28.0` (matches `git.gemspec` `requirements`) | Older git versions are not supported and the test suite will not pass against them. |
+| Node.js / npm | Optional | Required only to install the local Conventional Commit `commit-msg` hook (Husky + commitlint). If npm is missing, `bin/setup` will warn and continue — CI will still validate commit messages. |
+
+### Bootstrap the project
+
+From the project root, run:
+
+```shell
+bin/setup
+```
+
+`bin/setup` will:
+
+1. Verify the prerequisites above and exit with a non-zero status if any are
+   missing or out of date.
+2. Run `bundle install` to install Ruby gem dependencies.
+3. Run `npm install` (when npm is available) to install the Conventional Commit
+   `commit-msg` hook used by this project (Husky + commitlint). A separate
+   `pre-commit` hook is also installed that blocks direct commits to the
+   protected branches (`main`, `4.x`).
+4. Verify the toolchain by running `bundle exec rake --tasks`.
+
+### Verify the toolchain
+
+Once `bin/setup` succeeds, confirm the full test and lint suite passes locally:
+
+```shell
+bundle exec rake
+```
+
+This is the same default task that runs in CI and is the canonical way to
+validate a change before requesting review.
+
+### Contributor validation policy
+
+Contributors are expected to run `bundle exec rake` locally and confirm it
+passes before requesting review on a pull request — trivial documentation-only
+fixes (e.g., typo corrections in markdown files) are excepted. "CI passed" is
+not a substitute for local validation; it is a backstop. This applies equally to
+human-authored and AI-assisted contributions — see
+[AI-assisted contributions](#ai-assisted-contributions).
+
 ## How to submit a code or documentation change
 
 There is a three-step process for submitting code or documentation changes:
@@ -105,14 +174,28 @@ At least one approval from a project maintainer is required before your pull req
 can be merged. The maintainer is responsible for ensuring that the pull request meets
 [the project's coding standards](#coding-standards).
 
+### Before requesting review
+
+Before moving a pull request out of draft or requesting a review, confirm:
+
+- [ ] `bundle exec rake` passes locally on your branch (see
+  [Local development setup](#local-development-setup)).
+- [ ] New or changed code has accompanying tests under `spec/`
+  (see [Unit tests](#unit-tests)).
+- [ ] Every commit message follows [Conventional Commits](#commit-message-guidelines).
+- [ ] User-facing changes are documented in `README.md` and/or YARD as appropriate.
+
+These checks mirror what reviewers and CI will look for; running them locally
+first keeps the review cycle short.
+
 ## Branch strategy
 
 This project maintains two active branches:
 
 - **`main`**: Active development for the next major version (v5.0.0+). This branch
   may contain breaking changes.
-- **`4.x`**: Maintenance branch for the v4.x release series. This branch receives
-  bug fixes and backward-compatible improvements only.
+- **`4.x`**: Maintenance branch for the v4.x release series. This branch receives bug
+  fixes and backward-compatible improvements only.
 
 **Important:** Never commit directly to `main` or `4.x`. All changes must be
 submitted via pull requests from feature branches. This ensures proper code review,
@@ -126,15 +209,19 @@ When submitting a pull request:
 
 ## AI-assisted contributions
 
-AI-assisted contributions are welcome. Please review and apply our [AI Policy](AI_POLICY.md)
-before submitting changes. You are responsible for understanding and verifying any
-AI-assisted work included in PRs and ensuring it meets our standards for quality,
-security, and licensing.
+AI-assisted contributions are welcome. Please review and apply our [AI
+Policy](AI_POLICY.md) before submitting changes. You are responsible for
+understanding and verifying any AI-assisted work included in PRs and ensuring it
+meets our standards for quality, security, and licensing.
 
-## Design philosophy
+The **human submitter** — not the AI agent — is responsible for ensuring that
+`bundle exec rake` passes locally before requesting review. This is true even
+when the change was authored end-to-end by an agent. "The agent ran the tests"
+and "CI is green" are not substitutes for the submitter running
+[the local validation step](#contributor-validation-policy) themselves; CI is a
+backstop, not a primary validation surface.
 
-*Note: As of v2.x of the `git` gem, this design philosophy is aspirational. Future
-versions may include interface changes to fully align with these principles.*
+## Design philosophy
 
 The `git` gem is designed as a lightweight wrapper around the `git` command-line
 tool, providing Ruby developers with a simple and intuitive interface for
@@ -149,31 +236,280 @@ By following this philosophy, the `git` gem allows users to leverage their exist
 knowledge of Git while benefiting from the expressiveness and power of Ruby's syntax
 and paradigms.
 
-### Direct mapping to git commands
+## Command-layer neutrality
+
+Command classes (`Git::Commands::*`) are **faithful, neutral representations of the
+git CLI**. They declare every option via the DSL but never embed policy choices —
+output-control flags, editor suppression, progress output, verbose mode, etc.
+Policy decisions belong to the facade (`Git::Lib`), which sets safe defaults at
+each call site. Callers may override those defaults when they have a legitimate
+reason (e.g., running in a TTY-attached environment where an editor is desired).
+
+This principle serves two purposes: it keeps the command layer a reusable, unbiased
+interface to git, and it supports this gem's **non-interactive execution model** (git
+is never allowed to prompt for input, open an editor, or wait for TTY interaction
+by default). The execution layer provides an unconditional safety net regardless of
+what the caller passes.
+
+The three architectural layers each play a distinct role:
+
+| Layer | Responsibility | Mechanism |
+| --- | --- | --- |
+| **Command** (`Git::Commands::*`) | Neutral git CLI interface | Declares options via DSL (e.g. `flag_option :edit, negatable: true`) — no policy |
+| **Facade** (`Git::Lib`) | Safe defaults | Sets policy options at each call site (e.g. `edit: false`); callers may override |
+| **Execution** (`Git::CommandLine`) | Unconditional safety net | `GIT_EDITOR='true'` in every subprocess environment |
+
+> **Anti-pattern:** `literal '--no-edit'`, `literal '--verbose'`,
+> `literal '--no-progress'` inside a command class — embeds policy in the wrong layer.
+>
+> **Correct pattern:** `flag_option :edit, negatable: true` in the command;
+> `edit: false` passed from the facade call site.
+
+## Wrapping a git command
+
+> **Note:** This documentation reflects **Phase 2 (Strangler Fig)** of the architectural
+> redesign. It will be updated in **Phase 3** when `Git::Repository` becomes the primary
+> public API and `Git::Lib` is bypassed. Currently, `Git::Base` remains the public API
+> and `Git::Lib` acts as the delegation layer.
+
+This section guides you through wrapping a git command. The first subsections focus
+on **API design**: where methods belong, how to name them, and how to handle
+parameters and output. These describe the public interface that gem users will see.
 
-Git commands are implemented within the `Git::Base` class, with each method directly
-corresponding to a `git` command. When a `Git::Base` object is instantiated via
-`Git.open`, `Git.clone`, or `Git.init`, the user can invoke these methods to interact
-with the underlying Git repository.
+[From design to implementation](#from-design-to-implementation) then shows how to
+structure your code using the gem's three-layer architecture. Note that while we are
+transitioning to `Git::Repository`, the current public API is `Git::Base`, which
+delegates to `Git::Lib`, which in turn delegates to internal command classes.
 
-For example, the `git add` command is implemented as `Git::Base#add`, and the `git
-ls-files` command is implemented as `Git::Base#ls_files`.
+> **Note:** When adding new git command wrappers, **always use the new architecture**
+> described in "From design to implementation" with `Git::Commands::*` classes and
+> the Arguments DSL. The gem is being incrementally migrated from `Git::Lib` to this
+> pattern. Do not add new methods directly to `Git::Lib`.
 
-When a single Git command serves multiple distinct purposes, method names within the
-`Git::Base` class should use the `git` command name as a prefix, followed by a
-descriptive suffix to indicate the specific function.
+### Method placement
 
-For instance, `#ls_files_untracked` and `#ls_files_staged` could be used to execute
-the `git ls-files` command and return untracked and staged files, respectively.
+When implementing a git command, first determine what type of command it is. This
+determines where to implement it in the Ruby API:
+
+> **Note:** These placement guidelines define the **public API**. Always add public
+> methods to `Git` module or `Git::Base` (which acts as the current facade for
+> `Git::Repository`), even though the implementation will be in a `Git::Commands::*` class.
+
+**Repository factory methods** are implemented on the `Git` module. Use these to
+obtain a repository object for subsequent operations:
+
+```ruby
+repo = Git.clone('https://github.com/user/repo.git', 'local_path')
+repo = Git.init('new_repo')
+repo = Git.open('.')
+```
+
+**Repository-scoped commands** operate within a repository context. Implement these
+`Git::Base` instance methods:
+
+```ruby
+repo.add('file.txt')
+repo.commit('Add file')
+repo.log
+```
+
+**Non-repository commands** do not require a repository context. Implement these as
+methods on the `Git` module:
+
+```ruby
+Git.config_get('user.name', global: true)
+Git.config_set('user.email', 'user@example.com', global: true)
+```
+
+Some commands, like `git config`, can operate in multiple contexts:
+
+- **On the `Git` module**: A scope parameter (`global: true`, `system: true`) or
+  `file:` parameter is required. The `local:` and `worktree:` options are not allowed
+  since they require a repository.
+- **On a `Git::Base` instance**: The command defaults to the repository's local
+  scope. The `worktree: true` option is also available.
+
+### Method naming
+
+Each method corresponds directly to a `git` command. For example, the `git add`
+command is implemented as `Git::Base#add`, and the `git ls-files` command is
+implemented as `Git::Base#ls_files`.
+
+When a single Git command serves multiple distinct purposes, method names should use
+the git command name as a prefix, followed by a descriptive suffix indicating the
+specific function. The suffix should correspond to the git option that distinguishes
+the behavior.
+
+For example, `git config` supports `--get`, `--set`, `--list`, `--unset`, and other
+options. These are implemented as separate methods:
+
+```ruby
+repo.config_get('user.name')              # git config --get user.name
+repo.config_set('user.name', 'Scott')     # git config user.name Scott
+repo.config_list                          # git config --list
+repo.config_unset('user.name')            # git config --unset user.name
+repo.config_get_all('remote.origin.url')  # git config --get-all remote.origin.url
+```
 
 To enhance usability, aliases may be introduced to provide more user-friendly method
 names where appropriate.
 
+See also [Output processing](#output-processing) for when different output formats
+require separate methods.
+
+### Result class naming
+
+Parsed result objects returned from facade methods follow a reserved suffix convention:
+
+- **`*Info`** — a parsed metadata struct returned from a query (e.g., `BranchInfo`,
+  `TagInfo`, `StashInfo`, `DiffInfo`). Always lives in the top-level `Git::` namespace.
+- **`*Result`** — the outcome of a mutating or destructive operation (e.g.,
+  `BranchDeleteResult`, `TagDeleteResult`). Also lives in `Git::`.
+
+Do **not** use these suffixes on `Git::Commands::*` command classes — those are
+subprocess runners, not data objects. A reader seeing `Commands::Foo::BarInfo`
+expects a parsed struct, not a class that shells out to git.
+
 ### Parameter naming
 
 Parameters within the `git` gem methods are named after their corresponding long
 command-line options, ensuring familiarity and ease of use for developers already
-accustomed to Git. Note that not all Git command options are supported.
+accustomed to Git.
+
+For example, `git config --global` becomes `global: true`, and `git config --file`
+becomes `file: '/path/to/config'`.
+
+As a lightweight wrapper, the gem passes options directly to the git command-line.
+This means git itself will validate option combinations and report errors. This
+approach is preferred as long as the error messages returned by git are actionable
+and understandable for users of the gem.
+
+When multiple options are mutually exclusive (like `--global`, `--local`,
+`--system`), only one may be specified. Providing more than one will raise an
+`ArgumentError`.
+
+Note that not all Git command options are supported.
+
+### Parameter values
+
+This section defines how git command-line options and positional arguments map to
+Ruby method parameters. Contributors must follow these conventions:
+
+#### Options
+
+Git command-line options are passed as keyword arguments in the Ruby API. Methods
+accept these via an options splat parameter (e.g., `def replace(object, replacement,
+**options)`). Each option is mapped to a keyword argument as described below.
+
+- **Boolean flags**: Git options like `--global` or `--bare` are mapped to `global:
+  true` or `bare: true`. Omit the key or use `false` to leave the flag unset.
+  - `git config --global` → `global: true`
+
+- **Negated boolean flags**: Options like `--no-reflogs` are mapped to `no_reflogs:
+  true`.
+  - `git branch --no-reflogs` → `no_reflogs: true`
+
+- **Value options**: Options that take a value, such as `--file <path>` or `--author
+  <name>`, are mapped as `file: '/path'`, `author: 'Name'`.
+  - `git config --file /tmp/config` → `file: '/tmp/config'`
+
+- **Options with optional values**: If a git option can be used as a flag or with a
+  value (e.g., `--color` or `--color=always`), use `color: true` for the flag form,
+  or `color: 'always'` for the value form.
+  - `git log --color` → `color: true`
+  - `git log --color=always` → `color: 'always'`
+
+- **List/array options**: Options that can be repeated or take multiple values (e.g.,
+  `--exclude <pattern>`, `--pathspec-from-file <file>`) are mapped to arrays:
+  `exclude: ['foo', 'bar']`.
+  - `git ls-files --exclude=foo --exclude=bar` → `exclude: ['foo', 'bar']`
+
+- **Key-value pair options**: Options like `-c key=value` are mapped as `c: { 'key'
+  => 'value' }` or as an array of pairs if multiple are allowed.
+  - `git -c user.name=Scott` → `c: { 'user.name' => 'Scott' }`
+
+- **Mutually exclusive options**: If options are mutually exclusive (e.g.,
+  `--global`, `--local`, `--system`), only one may be used at a time. Setting more
+  than one raises `ArgumentError`. The DSL enforces this via `conflicts`
+  declarations at bind time. For **negatable flag options** (`negatable: true`),
+  passing `false` (which emits `--no-flag`) also counts as using that option in the
+  conflict check; non-negatable `false` is treated as absent.
+
+- **Forbidden value combinations (negatable flags)**: When two negatable flags may
+  both be present but only certain value pairings are contradictory, use
+  `forbid_values` declarations instead of (or in addition to) `conflicts`.
+  `conflicts` is presence-based and blocks all co-presence; `forbid_values` blocks
+  only the exact `name: value` tuples listed, leaving semantically equivalent pairs
+  valid. For example, `--all --no-ignore-removal` and `--no-all --ignore-removal`
+  are equivalent and should remain allowed, while `--all --ignore-removal` and
+  `--no-all --no-ignore-removal` are contradictory and should be rejected:
+
+  ```ruby
+  forbid_values all: true,  ignore_removal: true   # contradictory
+  forbid_values all: false, ignore_removal: false  # contradictory
+  ```
+
+  Unknown names raise `ArgumentError` at definition time. Alias names are
+  canonicalized automatically.
+
+- **Exactly-one required from a mutually exclusive group**: When exactly one of a
+  group of arguments must be provided (e.g., a command that accepts exactly one of
+  `--mode-a`, `--mode-b`, or `--mode-c`), omitting all of them or supplying more
+  than one raises `ArgumentError`. The DSL enforces this via
+  `requires_exactly_one_of` declarations, which combine `requires_one_of`
+  (at-least-one) and `conflicts` (at-most-one) in a single declaration.
+
+- **At-least-one required**: When at least one of a group of arguments (options or
+  positional) must be provided, but the group is not mutually exclusive, omitting
+  all of them raises `ArgumentError`. The DSL enforces this via `requires_one_of`
+  declarations at bind time.
+
+#### Positional arguments
+
+Arguments that are not options (e.g., file names, branch names) are passed as method
+arguments, not as keyword arguments.
+
+- **Only single-valued positional arguments**: If a command has one or more
+  single-valued positional arguments (e.g., `<arg1>` or `<arg1> <arg2>`), pass each
+  as a separate method argument, in the order they appear in the official git
+  documentation and CLI usage. Optional arguments (indicated by `[<arg>]`) should
+  default to `nil`.
+  - `git cmd <object>` → `def cmd(object)` (fictitious command)
+  - `git replace <object> <replacement>` → `def replace(object, replacement)`
+  - `git clone <repository> [<directory>]` → `def clone(repository, directory = nil)`
+
+- **Single multi-valued positional argument**: If a command has a single multi-valued
+  positional argument (e.g., `<pathspec>...` or `[<pathspec>...]`), use a splat
+  parameter to accept zero or more values (optional) or one or more values
+  (required).
+  - `git add [<pathspec>...]` → `def add(*paths)`
+
+- **Mixed single-valued and multi-valued positional arguments — `--` separated
+  (independently reachable groups)**: When a git command separates two optional
+  groups with `--` (e.g., `[<tree-ish>] [-- <pathspec>...]`), callers may want
+  to supply the post-`--` group *without* supplying the first group. Use the
+  single-valued argument as a regular optional parameter and the multi-valued
+  group as a keyword argument with an empty array default. The keyword argument
+  should accept a single value or an array; wrap a single value in an array
+  internally.
+  - `git checkout [<branch>] [-- <pathspec>...]` → `def checkout(branch = nil,
+    pathspecs: [])`
+  - `git diff [<tree-ish>] [-- <pathspec>...]` → `def diff(tree_ish = nil,
+    pathspec: [])`
+  - Callers can then do `checkout(pathspecs: ['file.rb'])` (no branch) or
+    `diff('HEAD~3', pathspec: ['file.rb'])` (both), with no ambiguity.
+
+- **Multiple optional single-valued positional arguments — pure nesting
+  (second only meaningful with first)**: When the git SYNOPSIS shows nested
+  optional brackets and the inner operand is only useful in the presence of the
+  outer one, both arguments may be regular optional parameters in left-to-right
+  order. A caller would never supply the second without the first.
+  - `git diff [<commit1> [<commit2>]]` → `def diff(commit1 = nil, commit2 = nil)`
+  - Callers can do `diff` (no args), `diff('HEAD~3')`, or `diff('HEAD~3', 'HEAD')`.
+    There is no case where someone would pass `commit2` without `commit1`.
+
+These conventions ensure the API is predictable and closely aligned with the git CLI.
+If a new option type is encountered, extend this section to document the mapping.
 
 ### Output processing
 
@@ -184,6 +520,222 @@ These Ruby objects often include methods that allow for further Git operations w
 useful, providing additional functionality while staying true to the underlying Git
 behavior.
 
+When a single git command can produce distinctly different output types based on its
+options, implement separate methods for each output type. Follow the same naming
+convention used for commands with multiple purposes: use the git command name as a
+prefix, followed by a suffix that describes the specific output type or
+functionality.
+
+For example, `git diff` can produce full diffs, statistical summaries, or path status
+information depending on the options used. These are implemented as separate methods:
+
+```ruby
+repo.diff_full('HEAD~1', 'HEAD')       # Full diff output (git diff -p)
+repo.diff_stats('HEAD~1', 'HEAD')      # Statistical summary (git diff --numstat)
+repo.diff_path_status('HEAD~1', 'HEAD') # File paths and status (git diff --name-status)
+```
+
+This approach ensures each method has a clear, predictable return type and allows for
+targeted parsing logic appropriate to each output format.
+
+### From design to implementation
+
+> **Note:** **Use this architecture for all new commands.** The gem is being
+> incrementally migrated using the "Strangler Fig" pattern:
+>
+> 1. **Phase 1 (completed)**: Foundation work to introduce the new command architecture
+>    and prepare the codebase for incremental migration.
+> 2. **Phase 2 (current)**: New `Git::Commands::*` classes are created, and `Git::Lib`
+>    methods delegate to them. `Git::Lib` remains but becomes a thin wrapper.
+> 3. **Phase 3 (planned)**: Public API (`Git::Base`) will be refactored to use
+>    `Git::Commands::*` directly, bypassing `Git::Lib`.
+> 4. **Phase 4 (planned)**: `Git::Lib` will be removed entirely.
+>
+> When adding new commands, create the `Git::Commands::*` class and have the
+> corresponding `Git::Lib` method delegate to it (see `Git::Lib#add` for an example).
+> When you encounter existing commands, you may optionally refactor them to this
+> pattern following the TDD workflow.
+
+The gem uses a three-layer architecture that separates the public API from internal
+implementation:
+
+1. **Facade layer (`Git::Base` and `Git` module)** — The current public interface.
+   Methods here are thin wrappers that delegate to `Git::Lib`, which in turn
+   delegates to internal command classes.
+
+2. **Command layer (`Git::Commands::*`)** — Internal classes that implement git
+   commands. Each command class handles argument building and output parsing.
+
+3. **Execution layer (`Git::ExecutionContext`)** — Runs raw git commands. Command
+   classes use this to execute git and receive output.
+
+When wrapping a new git command:
+
+1. **Design the public API** using the guidelines in this section (placement, naming,
+   parameters, output)
+
+2. **Create a command class** in `lib/git/commands/` that:
+   - Accepts an `ExecutionContext` and any required arguments
+   - Defines arguments using the Arguments DSL
+   - Parses the output into Ruby objects
+
+3. **Add the facade method** to `Git::Base` (or `Git` module) that delegates to
+   `Git::Lib`.
+
+Example structure for `git add`:
+
+```ruby
+# lib/git/commands/add.rb (internal)
+require 'git/commands/base'
+
+module Git
+  module Commands
+    class Add < Base
+      arguments do
+        literal 'add'
+        flag_option :all
+        flag_option :force
+        operand :paths, repeatable: true, default: [], separator: '--'
+      end
+
+      # Execute the git add command
+      #
+      # @overload call(*paths, all: nil, force: nil)
+      #
+      #   @param paths [Array<String>] files to be added
+      #
+      #   @param all [Boolean] Add, modify, and remove index entries to match the worktree
+      #
+      #   @param force [Boolean] Allow adding otherwise ignored files
+      #
+      # @return [Git::CommandLineResult] the result of the command
+      #
+      def call(...) = super # rubocop:disable Lint/UselessMethodDefinition
+    end
+  end
+end
+```
+
+**How `Base` works**: `Base` provides default `#initialize` (accepts an
+`execution_context`) and `#call` (binds arguments via the DSL, calls
+`execution_context.command`, validates exit status). Simple commands only need to
+declare `arguments do … end` and write `def call(...) = super` (which also serves as
+the YARD documentation anchor for per-command documentation). That forwarding method
+looks "useless" to RuboCop, so we disable `Lint/UselessMethodDefinition` on it; the
+method body must exist for YARD to attach command-specific docs, even though all work
+is delegated to `Base#call`.
+
+**Method Signature Convention**: Most commands use `def call(...) = super`, which
+forwards all arguments to `Base#call`. `Base#call` binds them via the Arguments DSL,
+calls `@execution_context.command(*args, **args.execution_options,
+raise_on_failure: false)`, and validates the exit status.
+
+Override `call` explicitly in three situations:
+
+1. **Input validation** — guard `ArgumentError` for invalid option combinations that
+   the DSL cannot express (e.g., empty operands without a compensating flag).
+2. **Stdin via IO pipe** — commands using the `--batch` / `--batch-check` protocol
+   must feed object names to the subprocess's stdin. Use the inherited
+   `Base#with_stdin(content)`, which opens an `IO.pipe`, writes the string content,
+   and yields the read end as `in:`. Do not open a pipe manually — `StringIO` is
+   not accepted by `Process.spawn` (it has no file descriptor).
+3. **Non-trivial option routing** — when multiple call shapes require different
+   argument sets built separately before dispatching.
+
+When overriding, work with `args_definition.bind(...)` directly and delegate
+exit-status handling to the inherited `validate_exit_status!`. Extract bulk logic
+into private helpers to satisfy Rubocop `Metrics` thresholds:
+
+```ruby
+def call(*objects, **options)
+  raise ArgumentError, '...' if objects.empty? && !options[:batch_all_objects]
+
+  bound = args_definition.bind(**options)
+  with_stdin(objects.map { |o| "#{o}\n" }.join) { |reader| run_batch(bound, reader) }
+end
+
+private
+
+def run_batch(bound, reader)
+  result = @execution_context.command(*bound, in: reader, **bound.execution_options, raise_on_failure: false)
+  validate_exit_status!(result)
+  result
+end
+```
+
+Validation of supported options is handled by the `Arguments` DSL, which raises
+`ArgumentError` for unsupported keywords. The public API in `Git::Lib` handles the
+translation from single values or arrays to the splat format.
+
+> **YARD Documentation Note:** When using anonymous keyword forwarding (`**`), YARD
+> cannot infer the method signature. Use the `@overload` directive with **explicit
+> keyword parameters** (e.g., `@overload call(paths, all: nil, force: nil)`) and
+> document each keyword with its own `@param` tag. Do not use `@option` with
+> `@overload`. See the example above for the pattern.
+>
+> **Testing Requirement:** When defining arguments with the DSL, you must write RSpec
+> tests that verify each argument handles valid values correctly (booleans, strings,
+> arrays) and handles invalid values appropriately. Use a separate `context` block for
+> testing each option to ensure clarity and isolation. See
+> `spec/unit/git/commands/add_spec.rb` for examples of comprehensive argument testing.
+
+```ruby
+# lib/git/lib.rb (delegation)
+class Git::Lib
+  # Git::Lib may accept an options hash for backward compatibility
+  def add(paths = '.', options = {})
+    # Convert to splat + keyword arguments when calling the command class
+    Git::Commands::Add.new(self).call(*Array(paths), **options)
+  end
+end
+
+# lib/git/base.rb (public facade)
+class Git::Base
+  def add(paths = '.', **options)
+    lib.add(paths, options)
+  end
+end
+```
+
+For factory methods and non-repository commands, the pattern is similar but differs
+in how the `ExecutionContext` is obtained:
+
+```ruby
+# Factory method (Git.clone) — creates context, runs command, returns repository
+module Git
+  def self.clone(url, path = nil, **options)
+    # logic to call Git::Commands::Clone via Git::Lib
+  end
+end
+
+# Non-repository command (Git.global_config) — standalone context
+module Git
+  def self.global_config(name, value = nil)
+    Git::Lib.new.global_config(name, value)
+  end
+end
+```
+
+> **Note:** The `Git::Lib` class currently acts as the execution context. In the new
+> architecture, `Git::Lib` methods delegate to `Git::Commands::*` classes, passing `self`
+> (the `Git::Lib` instance) as the execution context.
+
+### Example implementations
+
+The following command classes demonstrate patterns for implementing new commands.
+See `lib/git/commands/` and `spec/unit/git/commands/` for the full implementations:
+
+- **Simple command**: `Git::Commands::Add` — straightforward argument building with
+  the Arguments DSL
+- **Command with output parsing**: `Git::Commands::Fsck` — parses git output into
+  structured Ruby objects
+- **Factory command**: `Git::Commands::Clone` — returns data for creating a
+  repository object
+- **Multiple outputs**: `Git::Commands::Diff::*` — subclasses for different output
+  formats (planned)
+- **Multi-context**: `Git::Commands::Config` — handles both module and instance
+  variants (planned)
+
 ## Coding standards
 
 To ensure high-quality contributions, all pull requests must meet the following
@@ -213,8 +765,11 @@ Commits standard](https://www.conventionalcommits.org/en/v1.0.0/). Commits not
 adhering to this standard will cause the CI build to fail. PRs will not be merged if
 they include non-conventional commits.
 
-A git pre-commit hook may be installed to validate your conventional commit messages
-before pushing them to GitHub by running `bin/setup` in the project root.
+A git `commit-msg` hook (Husky + commitlint) that validates your Conventional
+Commit messages locally is installed automatically as part of the project
+bootstrap — see [Local development setup](#local-development-setup). The hook
+depends on Node.js and npm; if those are not installed, `bin/setup` will warn
+and skip the hook, and commit-message validation will only run in CI.
 
 #### What to know about Conventional Commits
 
@@ -236,7 +791,7 @@ Examples of valid commits:
 Commits that include breaking changes must include an exclaimation mark before the
 colon:
 
-- `feat!: removed Git::Base.commit_force`
+- `feat!: removed Git::Repository#commit_force`
 
 The commit messages will drive how the version is incremented for each release:
 
@@ -267,44 +822,130 @@ by not acted upon.
 See [the Conventional Commits
 specification](https://www.conventionalcommits.org/en/v1.0.0/) for more details.
 
+#### Issue and PR references
+
+Due to a parser limitation in commitlint, using `#<number>` anywhere in the commit
+**body** causes everything from that line onward to be treated as a footer, which
+triggers a `footer-leading-blank` error.
+
+To avoid this:
+
+- **In the body**, omit the `#` when mentioning an issue or PR — write `issue 1000`
+  not `issue #1000`.
+- **In the footer**, always include `#` for closing references:
+  `Closes #1000`, `Fixes #1000`, or `Resolves #1000`.
+- If you only want to mention an issue for context (not close it), omit the `#` in
+  the body — no footer line is needed.
+
+To validate a commit message before committing:
+
+```bash
+npx commitlint --format @commitlint/format < commit_msg.txt
+```
+
+To see how commitlint has parsed a commit message:
+
+```bash
+cat commit_msg.txt | node -e "
+const parse = require('@commitlint/parse');
+let msg = '';
+process.stdin.on('data', d => msg += d);
+process.stdin.on('end', () =>
+  parse.default(msg.trim()).then(r => console.log(JSON.stringify(r, null, 2)))
+);
+" | jq
+```
+
 ### Unit tests
 
 - All changes must be accompanied by new or modified unit tests.
 - The entire test suite must pass when `bundle exec rake default` is run from the
   project's local working copy.
 
-While working on specific features, you can run individual test files or a group of
-tests using `bin/test`:
+This project uses two test frameworks:
+
+- **RSpec** (`spec/`) - **Primary framework for all new tests.**
+- **Test::Unit** (`tests/units/`) - **Legacy test suite.** Maintained for existing
+  coverage but should not be extended for new features unless absolutely necessary.
+
+#### RSpec best practices
+
+- **Public methods**: Use a separate `describe '#method_name'` block for each public
+  method.
+- **Contexts**: Use separate `context` blocks for different scenarios.
+- **Options**: For methods accepting options (like commands), use a separate
+  `context` for each option to ensure isolation and comprehensiveness.
+- **One assertion per test**: Each test should verify one specific aspect of
+  behavior. Exceptions include: (a) testing that an object has expected attributes
+  after creation (e.g., verifying multiple fields of a returned object), (b)
+  verifying expected side effects of a single operation (e.g., a method that both
+  returns a value and modifies state), (c) testing that multiple related
+  assertions hold for the same setup (e.g., boundary conditions).
+
+#### Unit tests vs Integration tests
+
+This project uses two types of RSpec tests, organized by directory:
+
+- **Unit tests** (`spec/unit/`) - Test individual classes and methods with mocked
+  execution context. These verify that the gem builds correct git command arguments
+  and properly handles git output. Unit tests should mock `@execution_context` to
+  avoid calling real git commands.
+
+- **Integration tests** (`spec/integration/`) - Test the gem's behavior against real
+  git repositories. These verify that mocked assumptions in unit tests match actual
+  git behavior. Integration tests create temporary repositories using `Dir.mktmpdir`
+  and run real git commands through the gem's public API.
+
+**Purpose of integration tests**: Integration tests validate that the gem correctly
+interacts with git, not that git itself works correctly. They should verify:
+
+- That the gem's mocked command expectations match real git output format
+- That the gem correctly handles real git behavior (e.g., unicode in branch names)
+- That command options produce expected git behavior
+- Edge cases that are difficult to mock reliably
+
+**Integration test guidelines**:
+
+- Keep tests **minimal and purposeful** - only create what's needed for the test
+- Focus on **key behaviors** that unit tests can't verify
+- Don't test git's functionality - test the gem's interaction with git
+- Use the shared context `'in an empty repository'` for temporary repo setup
+- Use `Git::IntegrationTestHelpers` methods for file operations
+- Each test should verify one specific git interaction pattern
+
+**Example**: An integration test for branch listing should verify that the gem
+correctly parses git's branch list format, not that git can create branches.
+
+While working on specific features, you can run tests using:
 
 ```bash
-# run a single file (from tests/units):
-$ bin/test test_object
+# Run all tests (TestUnit + RSpec):
+$ bundle exec rake test_all
 
-# run multiple files:
-$ bin/test test_object test_archive
+# Run only TestUnit integration tests:
+$ bundle exec rake test
 
-# run all unit tests:
-$ bin/test
+# Run only RSpec tests (unit + integration):
+$ bundle exec rake spec
 
-# run unit tests with a different version of the git command line:
-$ GIT_PATH=/Users/james/Downloads/git-2.30.2/bin-wrappers bin/test
-```
+# Run only RSpec unit tests:
+$ bundle exec rake spec:unit
 
-### Continuous integration
+# Run only RSpec integration tests:
+$ bundle exec rake spec:integration
 
-All tests must pass in the project's [GitHub Continuous Integration
-build](https://github.com/ruby-git/ruby-git/actions?query=workflow%3ACI) before the
-pull request will be merged.
+# Run a single TestUnit file (from tests/units):
+$ bin/test test_object
 
-The [Continuous Integration
-workflow](https://github.com/ruby-git/ruby-git/blob/master/.github/workflows/continuous_integration.yml)
-runs both `bundle exec rake default` and `bundle exec rake test:gem` from the
-project's [Rakefile](https://github.com/ruby-git/ruby-git/blob/master/Rakefile).
+# Run multiple TestUnit files:
+$ bin/test test_object test_archive
 
-### Documentation
+# Run a specific RSpec file:
+$ bundle exec rspec spec/unit/git/commands/add_spec.rb
 
-New and updated public methods must include [YARD](https://yardoc.org/)
-documentation.
+# Run TestUnit tests with a different version of the git command line:
+$ GIT_PATH=/Users/james/Downloads/git-2.30.2/bin-wrappers bin/test
+```
 
 New and updated public-facing features should be documented in the project's
 [README.md](README.md).
@@ -364,7 +1005,7 @@ require 'git'
 Git.configure { |c| c.binary_path = '/Users/james/Downloads/git-2.30.2/bin-wrappers/git' }
 
 # Validate the version (if desired)
-assert_equal([2, 30, 2], Git.binary_version)
+assert_equal(Git::Version.new(2, 30, 2), Git.git_version)
 ```
 
 Tests can be run using the newly built Git version as follows: