---
name: small-focused-commits
description: Every commit does one thing, is understandable in isolation, and passes tests on its own. Bisectable-by-default policy.
when_to_use: Before every `git commit` — check that the commit is a single reviewable unit.
tags: [foundation, git, review]
---

# Small, focused commits

A commit's job is to make ONE change that a reviewer can hold in their head, that CI can green, and that `git bisect` can meaningfully cross.

## Test yourself before you commit

1. **Can you describe the change in one sentence with no `and`?** If not, split.
2. **Does the diff exceed ~300 lines net, excluding generated/mechanical?** If yes, split unless every line is genuinely part of the same idea (renaming a symbol across a codebase counts).
3. **Would `git bisect` on this commit be meaningful?** If the commit combines a bug fix + a refactor, bisect can't isolate the bug — split.
4. **Does the commit compile + tests pass on its own?** If no, you're building a broken bisect landscape — reorder or squash so every commit is green.

## Splitting patterns

- **Mechanical then semantic** — rename first, behavior second. Two commits, each trivially reviewable.
- **Add then use** — introduce the new abstraction as an unused module first, then wire callers in a follow-up. Reviewers can validate the shape before opining on integration.
- **Refactor then feature** — never `refactor + add feature` in one commit. It hides what the feature actually cost.
- **Test then implementation** — TDD writes the test first; commit the failing test, then the passing impl (see [[tdd-red-green-refactor]]).

## What a good commit message looks like

```
<INT-NN> <imperative one-liner, ≤72 chars>

<paragraph explaining WHY the change is needed; what problem it solves;
what alternatives were considered and why they were rejected>

<optional: performance/security notes, migration guidance, follow-ups>

Refs: INT-NN
```

The subject is what shows up in `git log --oneline`. Make it stand alone.

## Anti-patterns

- `wip` / `fix` / `update stuff` — never merge these; if that's what you have locally, squash before push.
- One commit per file — commits are about ideas, not filesystem layout.
- 40-line commit that touches 22 files — probably a rename that should be its own commit (see above).