glossary

Atomic Commits

A commit that encapsulates exactly one logical change, making it independently understandable, revertable, and reviewable without affecting unrelated parts of the codebase.

explanation

An atomic commit follows the single-responsibility principle applied to version control. Each commit should represent one complete, coherent idea: adding a feature, fixing a bug, or updating a dependency. A commit is atomic when reverting it with git revert does not break unrelated functionality and when reading its diff in isolation tells a complete story. Atomic commits improve code review quality because reviewers can evaluate each change in isolation. They make bisecting regressions faster because git bisect can pinpoint a single commit as the source of a bug. They also enable cleaner cherry-picking when backporting fixes to release branches. Common violations include "big-bang" commits that mix feature additions, refactors, and bug fixes, and "WIP" commits that checkpoint work in progress without logical boundaries. Tools like git add -p help manually create atomic commits from a large working tree; git-agent automates this process.

examples

feat(auth): add JWT verification middleware

fix(db): close connection pool on process SIGTERM

refactor(logger): extract formatLogLine into separate module

test(cart): add unit tests for discount calculation edge cases

chore(deps): pin lodash to 4.17.21 to resolve CVE-2021-23337

how git-agent helps

git-agent's core feature is atomic commit splitting. When you stage multiple unrelated changes, git-agent analyses the diff, plans logically separate commit groups, then stages and commits each group independently — without any manual git add -p sessions.

brew install gitagenthq/tap/git-agent

FAQ

How small should an atomic commit be?

An atomic commit should be as small as the single logical change it represents, which may be one line or one hundred lines. Size is less important than logical cohesion — all changes in a commit should be necessary and sufficient for the change's stated purpose.

Is it bad practice to have a large number of commits in a pull request?

No, provided each commit is atomic. Many small, focused commits make review easier than a few large mixed commits. Some teams squash on merge for a clean main branch while preserving atomic commits during review.

Can I create atomic commits after the fact using git rebase?

Yes. Interactive rebase (git rebase -i) lets you split, reorder, and squash commits. git-agent avoids the need for this by splitting atomically at commit time.

Commit splitting Conventional Commits Squash commits