A small commit tells one story. That story can be reviewed, reverted, or searched without carrying unrelated decisions along with it.
A useful commit boundary
Try to keep one commit focused on one of these:
- a behavior change;
- a refactor with no behavior change;
- documentation;
- a test or fixture;
- a dependency update.
Mixing all five makes the change harder to understand.
feat: render Markdown articles from the blog collection
fix: preserve empty state when no posts are published
docs: describe the article frontmatter formatReview gets faster
| Large mixed change | Focused change |
|---|---|
| Hard to identify intent | Intent is visible |
| Revert risks collateral changes | Revert is predictable |
| Reviewers scan everything | Reviewers follow one path |
| Debugging has many candidates | Bisect has useful boundaries |
The goal is not tiny commits at any cost. The goal is a sequence that explains how the code arrived at its current shape.