A useful commit is a small, understandable checkpoint. It contains one logical change, excludes unrelated files and secrets, records a descriptive message, and follows relevant verification.
Define the change before staging
State the outcome in one sentence:
Add input validation for an empty student name.
If the sentence requires “and” to join unrelated outcomes, consider separate commits. A single logical change may touch code, tests, and documentation when they jointly implement one outcome.
Run git status, inspect git diff, and stage explicit paths. Then inspect
git diff --staged. The staged view is the proposed commit, not merely a list
of everything edited today.
Verify at the right level
Run the smallest credible check plus any required project suite:
- execute the changed behavior;
- run focused tests;
- run formatting or static checks required by the project;
- inspect generated output when it is part of the result; and
- reread documentation for accuracy.
Record what you actually ran. Never claim a test passed when it was not run.
Exclude secrets and noise
Do not commit passwords, tokens, private keys, recovery codes, .env secrets,
student records, or restricted course data. If a secret enters history, simply
deleting it in a later commit may not remove it from earlier history. Stop and
follow the service’s revocation and repository-cleanup guidance.
Generated files belong only when project policy or reproducibility requires them. Caches, local configuration, and build output often create noise. Use the project’s ignore rules deliberately; do not assume ignored means disposable.
Write a message that explains the outcome
A concise imperative subject works well:
Reject empty student names
Avoid changes, fix stuff, or a transcript of filenames. Add a body when the
reason, constraint, or non-obvious trade-off will help a future reader.
Git’s git commit documentation describes
how the command records the current index. This is why reviewing the staged diff
immediately before committing matters.
Use the commit checklist
- [ ] One logical outcome is defined.
- [ ] `git status` contains no unexplained file.
- [ ] Unstaged and staged diffs were reviewed.
- [ ] Secrets, private data, caches, and unintended outputs are excluded.
- [ ] Relevant checks were run and recorded honestly.
- [ ] The subject describes the outcome.
- [ ] The resulting commit was inspected.
After committing, run git status and inspect the latest commit summary and
diff. A commit succeeds technically even when it contains the wrong files.
Common mistakes
- Staging everything to make status quiet.
- Combining formatting, feature work, and unrelated cleanup.
- Writing the message before inspecting the staged diff.
- Claiming verification performed by an AI tool without evidence.
- Committing a generated deliverable but losing its source.
- Treating a commit as a backup without another copy of the repository.
Do this now
Make one safe change in a practice repository. Complete the checklist, commit it, and explain the commit to another person using only its message and diff.
Log what you learned
Record only:
- Result: What did the action produce?
- Evidence: What observation, test, or source supports that result?
- Next action or unresolved question: What should happen next?
The next post explains how GitHub adds remote collaboration around Git history.