git 5.0.1 → 5.0.3

data/CONTRIBUTING.md

@@ -20,35 +20,33 @@
   - [Before requesting review](#before-requesting-review)
 - [Branch strategy](#branch-strategy)
 - [AI-assisted contributions](#ai-assisted-contributions)
+  - [Agent configuration](#agent-configuration)
   - [Agent skills](#agent-skills)
 - [Design philosophy](#design-philosophy)
 - [Layered architecture](#layered-architecture)
-  - [Command layer responsibilities](#command-layer-responsibilities)
-- [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)
+- [Implementing a git command](#implementing-a-git-command)
+  - [API design](#api-design)
+    - [Method placement](#method-placement)
+    - [Method naming](#method-naming)
+    - [Result class naming](#result-class-naming)
+    - [Parameter naming](#parameter-naming)
+    - [Parameter values](#parameter-values)
+    - [Output processing](#output-processing)
+  - [Implementation](#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)
-    - [RSpec best practices](#rspec-best-practices)
+  - [Testing guidelines](#testing-guidelines)
+    - [Test coverage policy](#test-coverage-policy)
     - [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)
   - [Build git](#build-git)
   - [Use the new Git version](#use-the-new-git-version)
-- [Licensing](#licensing)
 
 ## Summary
 
@@ -199,10 +197,6 @@ This project maintains two active branches:
 - **`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,
-CI validation, and maintains a clean commit history.
-
 When submitting a pull request:
 
 - **New features and breaking changes**: Target the `main` branch
@@ -223,6 +217,27 @@ 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.
 
+### Agent configuration
+
+Agent configuration is shared: each piece of guidance is stored once and surfaced to
+every supported agent.
+
+| Content | Canonical location | Also read by |
+| --- | --- | --- |
+| Project instructions | [`.github/copilot-instructions.md`](.github/copilot-instructions.md) | Claude Code, via an import in [`CLAUDE.md`](CLAUDE.md) |
+| Skills | [`.github/skills/`](.github/skills/) | Claude Code, via the `.claude/skills` symlink |
+| Prompts | [`.github/prompts/`](.github/prompts/) | Claude Code, via wrappers in `.claude/commands/` |
+| Setup hook | [`.github/hooks/run-bin-setup-once.sh`](.github/hooks/run-bin-setup-once.sh) | Claude Code, via `.claude/settings.json` |
+
+Always edit the canonical file. The Claude Code side is a pointer in every case, so
+changes reach both agents without a sync step.
+
+One caveat: `.claude/skills` is a committed symlink. Git for Windows only
+materializes symlinks when `core.symlinks` is enabled (which requires Developer Mode
+or an elevated shell). Without it, Windows contributors get a plain text file there
+and Claude Code silently loads no skills; either enable symlinks or point your agent
+at [`.github/skills/`](.github/skills/) directly. Copilot is unaffected.
+
 ### Agent skills
 
 If you use an AI coding agent that understands repository skills, the
@@ -256,7 +271,11 @@ guidance that mirrors maintainer expectations:
 
 ## Design philosophy
 
-The `git` gem is designed as a lightweight wrapper around the `git` command-line
+The `git` gem follows a design philosophy that allows users to leverage their
+existing knowledge of Git while benefiting from the expressiveness and power of
+Ruby's syntax and paradigms.
+
+Its public API is designed as a lightweight wrapper around the `git` command-line
 tool, providing Ruby developers with a simple and intuitive interface for
 programmatically interacting with Git.
 
@@ -265,44 +284,51 @@ introduce unnecessary abstraction layers or modify Git's core functionality. Ins
 the gem maintains a close alignment with the existing `git` command-line interface,
 avoiding extensions or alterations that could lead to unexpected behaviors.
 
-By following this philosophy, the `git` gem allows users to leverage their existing
-knowledge of Git while benefiting from the expressiveness and power of Ruby's syntax
-and paradigms.
+`git` commands generally translate to `Git::Repository` methods of the same name.
+Positional arguments map to the `git` CLI operands (such as paths, SHAs, etc.) in the
+same order. Keyword arguments map to `git` CLI options by long OR short name.
+
+Some examples:
+
+- To execute `git clone <url> --depth=1`, call `Git.clone(url, depth: 1)`
+- To execute `git add <path> --force`, call `Git::Repository#add(path, force: true)`
 
 ## Layered architecture
 
-The three architectural layers each play a distinct role:
+The `git` gem is organized into three architectural layers:
 
 | Layer | Responsibility | Mechanism |
 | --- | --- | --- |
-| **Facade** (`Git::Repository::*` and `Git` module) | Public API and policy | Normalizes Ruby arguments, sets safe defaults, calls one or more `Git::Commands::*` classes, and may parse output into public Ruby objects |
-| **Command** (`Git::Commands::*`) | Neutral git CLI interface | Declares CLI arguments via the [Arguments DSL](lib/git/commands/arguments.rb), executes git, and returns `Git::CommandLine::Result` |
-| **Execution** (`Git::ExecutionContext`) | Execution context and subprocess defaults | Carries repository/global execution settings such as working directory, environment, timeout, binary path, and logging; runs the git CLI with subprocess defaults such as `GIT_EDITOR='true'` |
-
-### Command layer responsibilities
+| **Facade** (`Git::Repository` and `Git`) | Public API | Normalizes Ruby arguments, sets safe defaults, calls one or more `Git::Commands::*` classes, and may parse output into public Ruby objects |
+| **Command** (`Git::Commands::*`) | Neutral git CLI interface | Declares CLI arguments via the [Arguments DSL](lib/git/commands/arguments.rb), builds the git argv and executes git via `#call`, and returns `Git::CommandLine::Result` |
+| **Execution** (`Git::ExecutionContext::*`) | Execution context and subprocess defaults | Carries execution settings such as working directory, environment, timeout, binary path, and logging; runs the git CLI with default global options (such as `-c color.ui=false`) and subprocess environment variables (such as `LC_ALL=en_US.UTF-8`) |
 
 Command classes (`Git::Commands::*`) are **faithful, neutral representations of the
 git CLI**. Each command class does the following:
 
-- Declares every CLI argument/option via the [Arguments DSL](lib/git/commands/arguments.rb)
-- Binds `#call` parameters with the [Arguments DSL](lib/git/commands/arguments.rb) to
-  build the git argv
-- Executes a git CLI command via `Git::ExecutionContext`
-- Returns the raw git CLI result as a `Git::CommandLine::Result` object
-
-Command classes should not embed policy choices such as output-control flags, editor
-suppression, progress output, or verbose mode. These policy decisions belong to the
-`Git::Repository::*` facade methods, which set safe defaults at each call site when
-policy is needed. In most cases, the facade gives callers the choice to override those
-defaults when they have a legitimate reason (e.g., running in a TTY-attached
+- Declares acceptable CLI arguments and options via the
+  [Arguments DSL](lib/git/commands/arguments.rb)
+- Defines a `#call` method which:
+  - Maps its parameters to the git argv using the declared arguments
+  - Executes a git CLI command via `Git::ExecutionContext`
+  - Returns the unprocessed git CLI result as a `Git::CommandLine::Result` object
+
+Command classes should not embed choices such as output format flags, editor
+suppression, progress output, or verbose mode. These decisions belong to the facade
+layer which sets them as needed. The facade layer may give callers the choice to
+override those decisions when appropriate (e.g., running in a TTY-attached
 environment where an editor is desired).
 
 For example:
 
-- **Anti-pattern:** `literal '--no-edit'`, `literal '--verbose'`, or
-  `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
+- **Anti-pattern:** declaring non-overidable and non-default options in the Arguments
+  DSL to control output such as `literal '--no-edit'`, `literal '--verbose'`, or
+  `literal '--no-progress'` inside a command class. This embeds policy in the wrong
+  layer.
+- **Correct pattern:** declaring options which allow the user of the command (often a
+  facade method) to set desired values such as: `flag_option :edit, negatable: true`.
+  This allows the facade to either accept the default or to hard code `edit: false`
+  if it is needed.
 
 This separation keeps command classes reusable across facade methods with different
 policy needs. For example, a facade method that parses command output may pass
@@ -311,41 +337,41 @@ a stable, parseable output shape. Those parser-contract options belong at the fa
 call site, not as hard-coded literals in the command class. Other facade methods can
 reuse the same command class with different options.
 
-## Wrapping a git command
+## Implementing a git command
 
-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.
+Start with the official git documentation page for the command (e.g., `man git-add`
+or the [git-scm.com](https://git-scm.com/docs) reference page). Its SYNOPSIS line
+identifies the positional operands, and its OPTIONS section identifies the flags and
+value options the Ruby method must expose.
 
-[From design to implementation](#from-design-to-implementation) then shows how to
-structure your code using the gem's three-layer architecture. The public API is
-`Git::Repository` (and the `Git` module), whose facade methods delegate directly to
-internal `Git::Commands::*` classes.
+Implementing the command has two major tasks: [API design](#api-design) and
+[Implementation](#implementation).
 
-> **Note:** When adding new git command wrappers, **always use the architecture**
-> described in "From design to implementation" with `Git::Commands::*` classes and
-> the [Arguments DSL](lib/git/commands/arguments.rb).
+### API design
 
-### Method placement
+The section focuses on deciding where git command methods belong, how to name them,
+and how to handle parameters and output. These describe the public interface that gem
+users will see.
 
-When implementing a git command, first determine what type of command it is. This
-determines where to implement it in the Ruby API:
+#### Method placement
 
-> **Note:** These placement guidelines define the **public API**. Always add public
-> methods to the `Git` module or `Git::Repository` (the facade), even though the
-> implementation will be in a `Git::Commands::*` class.
+The public API is `Git::Repository` (and the `Git` module). These facade methods must
+be exposed there, even when their implementation lives in private mixin modules or
+`Git::Commands::*` classes.
 
-**Repository factory methods** are implemented on the `Git` module. Use these to
-obtain a repository object for subsequent operations:
+**Repository factory commands** are exposed via `Git` as module methods and
+are usually implemented in the `Git::Factories` mixin. These methods return a
+`Git::Repository` object for subsequent operations:
 
 ```ruby
 repo = Git.clone('https://github.com/user/repo.git', 'local_path')
-repo = Git.init('new_repo')
+repo = Git.init('new_repo', initial_branch: 'main')
 repo = Git.open('.')
 ```
 
-**Repository-scoped commands** operate within a repository context. Implement these
-`Git::Repository` instance methods:
+**Repository-scoped commands** require a repository context. These methods are
+exposed via `Git::Repository` instance methods and are usually implemented in a
+`Git::Repository::*` mixin.
 
 ```ruby
 repo.add('file.txt')
@@ -353,23 +379,26 @@ repo.commit('Add file')
 repo.log
 ```
 
-**Non-repository commands** do not require a repository context. Implement these as
-methods on the `Git` module:
+**Global commands** do not require a repository context. Expose 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:
+Some commands, like `git config` commands, can be called either in a global or
+repository scope. Here is how that was solved for the config commands:
+
+- When called via the `Git` module, a scope parameter such as `global: true`,
+  `system: true`, or `file: <filename>` MUST be given. `local` and `worktree`
+  scopes are not allowed.
 
-- **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::Repository` instance**: The command defaults to the repository's local
-  scope. The `worktree: true` option is also available.
+- When called via a `Git::Repository` instance, `local: true` and `worktree: true`
+  scope parameters may be given, with `local` being the default if no scope is given.
+  `global`, `system`, and `file` scopes are also allowed.
 
-### Method naming
+#### Method naming
 
 Each method corresponds directly to a `git` command. For example, the `git add`
 command is implemented as `Git::Repository#add`, and the `git ls-files` command is
@@ -397,12 +426,14 @@ names where appropriate.
 See also [Output processing](#output-processing) for when different output formats
 require separate methods.
 
-### Result class naming
+#### Result class naming
 
-Parsed result objects returned from facade methods follow a reserved suffix convention:
+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.
+  `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::`.
 
@@ -410,7 +441,7 @@ Do **not** use these suffixes on `Git::Commands::*` command classes — those ar
 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
+#### 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
@@ -424,18 +455,12 @@ 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
+#### Parameter values
 
 This section defines how git command-line options and positional arguments map to
 Ruby method parameters. Contributors must follow these conventions:
 
-#### Options
+##### 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,
@@ -504,7 +529,7 @@ accept these via an options splat parameter (e.g., `def replace(object, replacem
   all of them raises `ArgumentError`. The DSL enforces this via `requires_one_of`
   declarations at bind time.
 
-#### Positional arguments
+##### Positional arguments
 
 Arguments that are not options (e.g., file names, branch names) are passed as method
 arguments, not as keyword arguments.
@@ -551,7 +576,7 @@ arguments, not as keyword arguments.
 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
+#### Output processing
 
 The `git` gem translates the output of many Git commands into Ruby objects, making it
 easier to work with programmatically.
@@ -578,7 +603,7 @@ repo.diff_path_status('HEAD~1', 'HEAD') # File paths and status (git diff --name
 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
+### Implementation
 
 The gem uses the three-layer architecture described in
 [Layered architecture](#layered-architecture). When wrapping a git command, keep the
@@ -596,6 +621,10 @@ layer responsibilities separate:
    facade policy, calls the command class, and parses the raw result when returning
    structured Ruby objects.
 
+Steps 2 and 3 correspond to the Command and Facade layers, respectively. The
+Execution layer (`Git::ExecutionContext::*`) already exists — a command class only
+consumes it via `@execution_context`; it is not authored per command.
+
 Example structure for `git add`:
 
 ```ruby
@@ -614,33 +643,54 @@ module Git
         operand :pathspec, repeatable: true
       end
 
-      # @!method call(*, **)
+      # @overload call(*pathspec, **options)
       #
-      #   @overload call(*pathspec, **options)
+      #   Execute the `git add` command
       #
-      #     Execute the `git add` command
+      #   @param pathspec [Array<String>] files to be added to the repository
+      #     (relative to the worktree root)
       #
-      #     @param pathspec [Array<String>] files to be added to the repository
-      #       (relative to the worktree root)
+      #   @param options [Hash] command options
       #
-      #     @param options [Hash] command options
+      #   @option options [Boolean, nil] :verbose (nil) be verbose
       #
-      #     @option options [Boolean, nil] :verbose (nil) be verbose
+      #     Alias: :v
       #
-      #       Alias: :v
+      #   @option options [Boolean, nil] :force (nil) allow adding otherwise ignored
+      #     files
       #
-      #     @option options [Boolean, nil] :force (nil) allow adding otherwise ignored
-      #       files
+      #     Alias: :f
       #
-      #       Alias: :f
+      #   @return [Git::CommandLine::Result] the result of calling `git add`
       #
-      #     @return [Git::CommandLine::Result] the result of calling `git add`
+      #   @raise [ArgumentError] if unsupported options are provided
       #
-      #     @raise [ArgumentError] if unsupported options are provided
+      #   @raise [Git::FailedError] if git exits with a non-zero exit status
       #
-      #     @raise [Git::FailedError] if git exits with a non-zero exit status
+      #   @api public
       #
-      #     @api public
+      def call(*, **)
+        super
+      end
+    end
+  end
+end
+```
+
+Here is the corresponding facade method that calls it:
+
+```ruby
+# lib/git/repository/staging.rb (facade — a topic module included into Git::Repository)
+module Git
+  class Repository
+    module Staging
+      ADD_ALLOWED_OPTS = %i[all force].freeze
+      private_constant :ADD_ALLOWED_OPTS
+
+      def add(paths = '.', **)
+        SharedPrivate.assert_valid_opts!(ADD_ALLOWED_OPTS, **)
+        Git::Commands::Add.new(@execution_context).call(*Array(paths), **).stdout
+      end
     end
   end
 end
@@ -678,7 +728,7 @@ into private helpers to satisfy RuboCop `Metrics` thresholds:
 def call(*objects, **options)
   raise ArgumentError, '...' if objects.empty? && !options[:batch_all_objects]
 
-  bound = args_definition.bind(**options)
+  bound = args_definition.bind(*objects, **options)
   with_stdin(objects.map { |o| "#{o}\n" }.join) { |reader| run_batch(bound, reader) }
 end
 
@@ -711,25 +761,9 @@ also handles translation from single values or arrays to the splat format.
 > 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/repository/staging.rb (facade — a topic module included into Git::Repository)
-module Git
-  class Repository
-    module Staging
-      ADD_ALLOWED_OPTS = %i[all force].freeze
-      private_constant :ADD_ALLOWED_OPTS
-
-      def add(paths = '.', **)
-        SharedPrivate.assert_valid_opts!(ADD_ALLOWED_OPTS, **)
-        Git::Commands::Add.new(@execution_context).call(*Array(paths), **).stdout
-      end
-    end
-  end
-end
-```
-
 For factory methods and module-level commands, the pattern is the same but
-`Git::ExecutionContext::Global` is used instead of the repository's `@execution_context`:
+`Git::ExecutionContext::Global` is used instead of the repository's
+`@execution_context`:
 
 ```ruby
 # Factory method (Git.clone) — creates a global context, runs the command, returns a repository
@@ -743,8 +777,9 @@ end
 ```
 
 > **Note:** `Git::Repository` facade methods pass `@execution_context` (a
-> `Git::ExecutionContext::Repository`) to each command class they invoke. Module-level
-> methods such as `Git.clone` construct a `Git::ExecutionContext::Global` instead.
+> `Git::ExecutionContext::Repository`) to each command class they invoke.
+> Module-level methods such as `Git.clone` construct a
+> `Git::ExecutionContext::Global` instead.
 
 ### Example implementations
 
@@ -884,27 +919,145 @@ process.stdin.on('end', () =>
 " | jq
 ```
 
-### Unit tests
+### Testing guidelines
+
+- All changes must be accompanied by new or modified unit and integration tests as
+  appropriate.
+- The entire test suite must pass when `bundle exec rake` is run from the project's
+  local working copy.
+- Test runs are covered by SimpleCov by default. Set `COVERAGE=false` (or `0`/`no`/
+  `off`) to skip coverage, e.g. `COVERAGE=false bundle exec rake spec`.
+  `rake spec:integration` always disables coverage, regardless of `COVERAGE`:
+  integration tests aren't meant to be exhaustive, so tracking their coverage would
+  misleadingly suggest that low integration coverage is a problem to fix.
+- `rake spec:integration` runs in parallel (via `parallel_tests`) on MRI. Set
+  `PARALLEL_TESTS=false` (or `0`/`no`/`off`) to force serial execution, e.g.
+  `PARALLEL_TESTS=false bundle exec rake spec:integration`. A run narrowed by `SPEC`
+  to a single spec file always runs serially — there is nothing to divide across
+  workers, and serial execution gives per-example (documentation) output.
+- Set `SPEC=<glob>` to run specific files instead of a task's whole directory, e.g.
+  `SPEC=spec/unit/git/version_spec.rb bundle exec rake spec:unit`.
+- Each task runs only the matches that live under its own directory, so one glob
+  spanning `spec/unit/` and `spec/integration/` can drive `bundle exec rake spec` and
+  exercise both layers of an area in a single command:
+
+  ```bash
+  # Unit and integration specs for the add command
+  SPEC=spec/**/git/commands/add_spec.rb bundle exec rake spec
+
+  # Unit and integration specs for every command class
+  SPEC=spec/**/git/commands bundle exec rake spec
+  ```
 
-- 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.
+  The glob is expanded by Rake, not the shell, so `**` works the same in any shell.
+  A task whose directory contains none of the matches is skipped with a message —
+  `SPEC=spec/unit/...` on `rake spec` runs the unit specs and skips
+  `spec:integration`. A glob matching nothing anywhere fails the task outright.
+
+This project uses **RSpec** (`spec/`) as its sole test framework. Structure,
+naming, setup, stubbing, and coverage rules for unit specs are defined in the
+[`rspec-unit-testing-standards`](.github/skills/rspec-unit-testing-standards/SKILL.md)
+skill — follow it when writing or reviewing specs under `spec/unit/`.
+
+#### Test coverage policy
+
+**Every pull request to `main` must keep `bundle exec rake spec:unit` at 100% line
+coverage and 100% branch coverage of `lib/`.** CI fails the build when it drops
+below either threshold.
+
+This is enforceable without being onerous because unit coverage in this project is
+deterministic: `lib/` has no Ruby-version, Ruby-engine, or platform conditionals, and
+no unit spec is conditionally skipped. Every supported MRI runtime measures exactly
+the same lines and branches, so a coverage failure is always something the pull
+request introduced.
+
+What the policy does and does not cover:
+
+- **Scope is the unit suite on MRI.** Integration specs are deliberately not
+  exhaustive and are not measured (`rake spec:integration` always disables coverage).
+  JRuby and TruffleRuby do not produce reliable coverage data and are not measured.
+- **Enforcement applies to full-suite runs.** A focused run
+  (`SPEC=<glob> bundle exec rake spec:unit`, or `bundle exec rspec <file>`) still
+  reports coverage but will not fail on it, so the usual edit-test loop is unaffected.
+  Set `FAIL_ON_LOW_COVERAGE=true` to force enforcement on for a focused run.
+- **A focused run lists gaps only in the code it is about.** The reported percentage is
+  always for the whole of `lib/`, but the list of uncovered lines and branches is scoped
+  to the files the run tests — the classes it describes, plus the `lib/` file each spec
+  file mirrors. So a focused run answers "is what I just changed fully covered?" without
+  waiting for CI:
+
+  ```text
+  Reporting uncovered lines and branches for 1 of 225 files.
+
+  No uncovered lines and branches in this file.
+  ```
 
-This project uses **RSpec** (`spec/`) as its sole test framework.
+  Ignore the percentage on a focused run; it is low because `spec_helper` loads all of
+  `lib/`, not because anything is wrong. Set `LIST_UNCOVERED_FILES=all` to list gaps for
+  every file instead.
+- **The thresholds do not move.** Do not lower `minimum_coverage` and do not add a
+  SimpleCov filter to exclude a file. The only sanctioned escape hatch is a
+  `# simplecov:disable` directive.
+- **Every file under `lib/` is measured.** SimpleCov only tracks files loaded after it
+  starts, so a file loaded earlier is silently absent from the report rather than
+  counted as uncovered. This is why `git.gemspec` reads the version string out of
+  `lib/git/version.rb` instead of `require`ing it: the `Gemfile` uses `gemspec`, so
+  requiring it there would load it on every `bundle exec`, before SimpleCov starts.
+  Keep new code out of the load path that runs ahead of `spec_helper`.
+
+When a branch is hard to cover, apply these in order:
+
+1. **Reach it through the public interface.** If a branch is reachable, test it.
+2. **Delete it.** A branch that cannot be reached through the public interface is
+   usually dead code, and removing it is preferable to excluding it. See commit
+   `74e919a4` ("fix: remove unreachable nil check in `Git::Parsers::Grep.parse`") for
+   the pattern.
+3. **Exclude it with `# simplecov:disable`.** Reserved for defensive guards that could
+   only be reached by breaking an OS-level invariant. Cover the smallest possible span,
+   state why the code is unreachable, and expect a reviewer to question it. `lib/`
+   currently contains no coverage directives.
+
+   Use the inline form wherever the exclusion is a single line — it applies only to the
+   line it sits on and needs no matching `enable`, which makes it impossible to leave a
+   region accidentally open:
+
+   ```ruby
+   raise 'unreachable' # simplecov:disable defensive guard; only reachable on OOM
+   ```
+
+   The block form covers a span and stays in effect until the matching
+   `# simplecov:enable` (or end of file, if you forget it):
+
+   ```ruby
+   # simplecov:disable branch platform-specific fallback; not reachable on MRI
+   ...
+   # simplecov:enable branch
+   ```
+
+   Always name the narrowest criterion that solves the problem — `line`, `branch`,
+   `method`, or a comma-separated combination — and spell it exactly. A word SimpleCov
+   does not recognize is treated as free-form reason text, which silently widens the
+   directive to all three criteria instead of failing. Write the reason after the
+   criteria, so the required justification lives in the directive itself.
+
+**Coverage is a floor on evidence, not a proof of correctness.** A test written only
+to execute a line, without asserting a meaningful outcome, violates Rule 24 of the
+[`rspec-unit-testing-standards`](.github/skills/rspec-unit-testing-standards/SKILL.md)
+skill and will be rejected in review even though it turns the report green. The
+threshold exists to surface untested behavior, not to be satisfied.
+
+To see exactly what is uncovered:
 
-#### RSpec best practices
+```bash
+# Names every uncovered line and branch (printed automatically when a full run fails)
+$ LIST_UNCOVERED_DETAIL=true bundle exec rake spec:unit
+
+# Browsable HTML report, also uploaded as a CI artifact when a build fails
+$ open coverage/index.html
+```
 
-- **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).
+This policy applies to `main` only. The `4.x` maintenance branch predates it and is
+not held to these thresholds.
 
 #### Unit tests vs Integration tests
 
@@ -959,9 +1112,6 @@ $ bundle exec rspec spec/unit/git/commands/add_spec.rb
 $ GIT_PATH=/Users/james/Downloads/git-2.30.2/bin-wrappers bundle exec rake spec
 ```
 
-New and updated public-facing features should be documented in the project's
-[README.md](README.md).
-
 ## Building a specific version of the Git command-line
 
 To test with a specific version of the Git command-line, you may need to build that
@@ -1027,11 +1177,3 @@ GIT_PATH=/Users/james/Downloads/git-2.30.2/bin-wrappers bundle exec rake spec
 ```
 
 Note: `GIT_PATH` refers to the directory containing the `git` executable.
-
-## Licensing
-
-`ruby-git` uses [the MIT license](https://choosealicense.com/licenses/mit/) as
-declared in the [LICENSE](LICENSE) file.
-
-Licensing is critical to open-source projects as it ensures the software remains
-available under the terms desired by the author.