Version Control Hygiene (Git)
Git history is the project's record: how we understand why the code is the way it is, review changes, and recover when things go wrong. Small, focused commits with clear messages, and never committing secrets or generated files, make that record useful. A messy history and a leaked secret in a commit are both expensive to undo.
Good version-control habits make everything else easier. Reviews are clearer, you can search the history to find a bug, reverting is clean, and a teammate can read the history to understand a decision. For newer engineers the most valuable habits are simple: commit small and often, write a message that says why, and never commit a secret.
This goes with how we work day to day: short-lived branches integrated to trunk often (see Trunk-Based Development), changes small enough to review well (see Code Review), and the pipeline as the only path to production (see CI/CD & Deployment).
Commit with care
- DoMake small, focused commits, one logical change each, so the history is readable and a single change can be reviewed, reverted, or cherry-picked cleanly.
- DoWrite clear commit messages: a short summary plus the why for anything non-obvious. The diff shows what changed; the message explains why.
- DoKeep branches short-lived and integrate to trunk often. Pull and rebase often, so conflicts stay small (see Trunk-Based Development).
- DoUse a .gitignore so build output, dependencies, local config, and generated files do not get committed.
- ConsiderReviewing your own diff before pushing. You will catch stray debug code, accidental files, and secrets.
Never commit these
- NeverCommit secrets (keys, passwords, connection strings, tokens, certificates) to any repo, even briefly or in a private one. If you do, treat it as compromised: rotate it and tell security (see Secrets at Rest & in Transit).
- NeverCommit real customer or personal data (fixtures, dumps, screenshots) into the repository (see Test Data & Environments).
- DoLet automated secret scanning catch mistakes, but do not depend on it. Keep secrets out in the first place (see CI/CD & Deployment).
- AvoidRewriting or force-pushing shared history (for example main or a shared branch). It breaks everyone else's clone (see Schema Versioning for the same principle in migrations).
- AvoidLarge, mixed-purpose commits that bundle unrelated changes. They are hard to review and impossible to revert cleanly.
git commit -am "stuff"
// includes: feature + refactor + a committed appsettings with a real key
Impossible to review (everything at once), a useless message, and a live secret now in the history forever. Deleting it later does not make it safe; it must be rotated.
git commit -m "Fail closed when screening times out
Previously a timeout was treated as 'clear'. Now we block-and-escalate
so an unscreened customer can't be auto-approved."
// secret stays in Key Vault; .gitignore excludes local config
One logical change, a message that explains the why, and no secret in the repo. A readable history that helps the next person.
Self-review checklist
- AskIs there a secret or real customer data anywhere in this commit?
- AskIs this one focused change, or several bundled together?
- AskDoes my message explain why, not just what?
- AskAm I about to rewrite or force-push history other people share?