Making Good Commits

Commit as snapshot plus explanation

Git commits are snapshots, not file-by-file save commands. When you run git commit, Git records the content staged in the index as the next point in history. The working tree can contain other unfinished edits; those are not part of the commit unless they were staged first.

That last sentence is the practical reason to make good commits. You are not only preserving code; you are creating handles for future action. A commit that says "fix stuff" and changes eight unrelated files gives the future reader very little to grab. A commit that says Validate email before saving profile and contains only that change can be reviewed, blamed, reverted, and understood without spelunking.

The most useful mental model is: stage the story you want to tell, then commit that story with a title and context. This keeps Git from feeling like a mysterious filing cabinet. The index becomes your drafting table.

Atomic commits

An atomic commit makes one coherent change. "One" does not necessarily mean one file, one line, or one tiny patch. It means one reason. If all the changed lines must travel together for the project to make sense, they probably belong in the same commit. If two changes could be reviewed, reverted, or explained independently, they probably want separate commits.

Atomic commits help in four ordinary ways. Reviewers can check intent against implementation. You can bisect history when a bug appears. You can revert one bad decision without removing unrelated work. And you can read the history later as a sequence of design choices rather than a pile of timestamps.

Staging as composition

git add is better understood as "add this content to the next commit" than "add this file forever." The distinction matters because the index stores the version of a file as it looked when you staged it. If you edit the file again afterward, Git can show the same file as both staged and unstaged: one version is ready for the commit, and a later version is still only in the working tree.

git status
git diff              # what is still unstaged
git diff --staged     # what will be committed
git add -p            # choose hunks interactively
git commit

The command git add -p is the workhorse for good commits. It lets you review hunks and choose which ones enter the index. When a file contains both a real fix and a drive-by cleanup, patch staging lets you commit the fix now and leave the cleanup for a separate commit.

Think of staging as an editorial step. You are not just telling Git that files changed. You are deciding which exact lines belong in the next historical unit.

Message shape

A commit message has two jobs. The subject line names the change when history is skimmed. The body, when needed, explains the context a diff cannot show: why the change was made, what alternatives were rejected, what side effects matter, and how to verify it.

Validate email before saving profile

Profiles were accepting malformed email addresses when imported from
older CSV exports. That made password reset delivery fail later, far
from the original import error.

Reject invalid addresses at the profile boundary and add coverage for
the legacy importer path.

The subject line should be short enough to scan in git log --oneline. Imperative phrasing usually reads well because it describes what applying the commit does: Add retry timeout, Reject expired tokens, Remove unused avatar cache. The body is optional. Use it when the diff answers "what" but not "why."

Do not stuff every detail into the subject. A compact subject plus a body is easier to search, easier to review, and kinder to the person reading the history during an incident.

Commit anatomy

A commit object is small but information-dense. It ties a snapshot to history and explains who did what. You do not need the internals every day, but knowing the shape clarifies several confusing behaviors: why amending changes the commit ID, why author and committer can differ, and why two commits with the same patch are still distinct objects.

git cat-file -p HEAD

The author and committer are often the same person. They diverge when someone applies a patch written by someone else, rebases or cherry-picks work, or uses options such as --author or --reset-author. In a team, that distinction is not trivia. It preserves credit for the original change while also recording who integrated it into the current history.

The commit hash is derived from the commit object's content and metadata. Change the tree, the parent, the dates, the author, or the message, and you have a different object with a different ID. That is why history editing is powerful locally and disruptive after publication.

Amend, empty commits, and published history

git commit --amend replaces the tip of the current branch with a new commit. It is perfect when the latest local commit has a typo, missed file, or weak message. It is not a magic edit-in-place operation; the old commit is abandoned and a new commit takes its place.

git add forgotten-test.js
git commit --amend

Use amend freely before you share the commit. After you push or otherwise publish it, amending rewrites history that someone else may already have based work on. That can still be acceptable in coordinated workflows, but it is no longer a private cleanup. You are changing the name of a commit other people may be using.

Empty commits are a special case. Git usually prevents a commit whose tree is identical to its parent because that is often a mistake. git commit --allow-empty bypasses that guard. Use it only when a history event matters without a content change: triggering a deployment, marking a migration boundary, or recording a coordination point in a repository-driven process.

git commit --allow-empty -m "Trigger staging deployment"

Common pitfalls

Worked examples

git diff
git add -p src/profile/validation.js test/profile-validation.test.js
git diff --staged
git commit -m "Validate imported profile emails"

git add src/profile/profile.css src/profile/ProfileView.jsx
git diff --staged
git commit -m "Rename profile form email class"

fix api

Bound checkout API retries

Checkout requests could retry indefinitely when the payment gateway
timed out before returning a response. Cap retries so failed payments
surface to the user and stop holding worker slots.

git status
git add test/checkout-retry.test.js
git commit --amend

git commit --allow-empty -m "Trigger production smoke test"