- Developers who already know basic commit and branch actions
- Readers who want to understand command boundaries and risk
Command Reference
git commit Tutorial
Explains how git commit creates new history nodes, how to write stronger messages, and when amend is safe versus risky.
- A basic mental model of worktree, index, and commits
- Comfort reading `git status` and a small commit graph
- Using local cleanup commands on already shared history
- Continuing to rewrite before confirming a recovery path
The short version
git commit turns the staged snapshot into a new commit object and moves the current branch to that new history point.
A useful commit is not just a saved diff. It is a stable checkpoint plus a message that explains why this checkpoint should exist.
What this command is really for
People sometimes talk about commit as if it were a save button.
That is too small a mental model.
A good commit gives you:
- a rollback point
- a reviewable unit of change
- a reusable change for cherry-pick or backport
- a readable step in the project story
That is why commit quality matters so much more than raw commit count.
Common usage
git commit -m "feat: add search dialog"
git commit --amend
git commit -m: create a new commit from the indexgit commit --amend: rewrite the most recent local commit
What to confirm before committing
Before you run git commit, check three things:
- is the index cleanly scoped to one logical change?
- does the message explain intent, not only mechanics?
- is this history still local, or already visible to others?
That third question matters because commits are easy to rewrite when private and much more expensive to rewrite when shared.
A stronger commit message pattern
Good commit messages are usually:
- specific
- action-oriented
- small enough to match the actual diff
For example:
- good:
fix: avoid infinite loading in doc search - weaker:
update search - weaker:
misc changes
The point is not following a strict grammar for its own sake.
The point is helping reviewers and future-you understand why this commit exists.
When amend is appropriate
git commit --amend is ideal when:
- you forgot one small file in the last local commit
- the message is misleading or incomplete
- you want to polish the latest commit before review
It becomes risky when:
- the commit was already pushed to a shared branch
- CI, review comments, or teammates now refer to that exact history
If the history is still private, amend is one of the cleanest ways to fix a commit without adding unnecessary noise.
A safer commit routine
When you want commits to stay useful, a practical routine is:
- inspect with
git status - inspect exact staged content with
git diff --staged - commit with a message that describes intent
- re-check the branch shape with
git log --oneline -5
For example:
git status
git diff --staged
git commit -m "fix: fall back to local search index on timeout"
git log --oneline -5
Diagram view
Working tree editsIndex snapshotCurrent branch
New commit objectMoved branch tipRecoverable checkpoint
If the resulting commit looks wrong, check the index first. Most commit mistakes start before the command itself.
Boundaries and common mistakes
git commitdoes not automatically include every visible file edit. It records what is staged.- A commit that mixes refactor, bug fix, and formatting work is harder to review and harder to revert safely.
- Rewriting a local commit is usually cheap; rewriting a published commit is a coordination decision.
If the commit message sounds vague because the change set is vague, the usual fix is not a better sentence. The usual fix is splitting the commit.
Try it yourself
This helps you see why staging and commit messages matter together.
git switch -c lab/commit-demo # make one real fix and one unrelated cleanupTry it
- Stage everything and imagine the resulting commit message.
- Reset the index, then stage only the real fix.
- Create a focused commit.
- Stage the cleanup separately and write a second message.
- You can compare one mixed commit with two focused commits.
- The branch history becomes easier to review.
- Future revert or cherry-pick actions become safer because each commit has one job.
- If you amend after pushing, make sure you understand whether the branch is shared.
- If the message feels generic, inspect whether the staged diff is too broad.
- If you are unsure what will be committed, run `git diff --staged` before committing.