Your commit history is the only narrative that survives. Code comments rot. READMEs go stale. Architecture diagrams become lies the moment they are exported to PNG. But git log tells the truth — if you write it with intention. A clean commit history is not vanity. It is a communication tool for your future self and your team.
Code is read ten times more than it is written. Commit messages are read a hundred times more.
The conventional commits specification is the baseline. It gives structure to chaos. A commit message should answer three questions: what changed, why it changed, and what the side effects are. The subject line is a command, not a description. fix: resolve race condition in auth middleware is better than fixed bug.
feat(api): add rate limiting middleware

- Implement token bucket algorithm with Redis backend
- Default limit: 100 requests per minute per IP
- Returns 429 with Retry-After header when exceeded

Closes #342

BREAKING CHANGE: X-RateLimit headers now use standard
RFC 6585 naming instead of custom x-ratelimit-* format.
Atomic commits are non-negotiable. One logical change per commit. If you are fixing a bug and refactoring nearby code, those are two commits. If you are adding a feature and updating documentation, those are two commits. The goal is bisectability — the ability to find the exact commit that introduced a regression with git bisect.
Interactive rebase is your friend, not your enemy. Squash fixup commits. Reorder commits so the narrative flows. Split commits that do too much. The golden rule is simple: never rewrite history that has been pushed to a shared branch. But on your feature branch? Rewrite until it tells a story worth reading.
# Clean up your feature branch before opening a PR
git rebase -i main

# In the editor:
# - pick the first commit
# - squash fixups into their parent
# - reword unclear messages
# - reorder for narrative flow

# Then force-push to update the PR
git push --force-with-lease origin feature-branch
The most productive engineers I know spend time on their commit history. Not because they are perfectionists, but because they have been burned by sloppy history. When production breaks at 3 AM and you need to find the regression in thirty seconds, a clean git log is the difference between a quick fix and a career-limiting outage. Write your history like someone else's sleep depends on it. Because it does.