Git Best Practices
Git is forgiving about how you use it day-to-day, but a handful of habits make the difference between a repository history that's actually useful for debugging and one that's just noise. These practices matter most on any project with more than one contributor.
Last updated 2026-09-08
Write commit messages that explain why, not just what
The diff itself already shows what changed — a commit message that just restates the diff ('updated file.js') adds nothing. A good message explains the reasoning: why this change was needed, what problem it solves, what alternative was considered and rejected.
"Fix race condition in upload retry logic by adding a mutex lock""fix bug" / "updates" / "wip"Commit small, logically-scoped changes rather than large mixed ones
A commit that mixes a bug fix, a refactor, and a new feature together is hard to review, hard to revert cleanly, and hard to understand later with `git blame`. Smaller, focused commits make history genuinely useful as a debugging and archaeology tool.
Never commit secrets, even temporarily
An API key or password committed and later 'removed' in a follow-up commit is still recoverable from git history indefinitely, unless the history itself is explicitly rewritten (which is disruptive on a shared repository). Use environment variables and a properly configured .gitignore from the start.
Use feature branches, not direct commits to main
Working directly on main (or master) means every in-progress change is immediately live in the branch everyone else pulls from. A feature branch, merged via pull request once reviewed and tested, keeps main in a consistently deployable state.
Pull/rebase before pushing to avoid unnecessary merge commits
Pushing without first incorporating others' recent changes often produces an unnecessary merge commit that adds noise to history. Rebasing onto the latest main before pushing (on a personal feature branch, not a shared one) keeps history linear and easier to follow.
Use .gitignore properly from the start of a project
Build artifacts, dependency folders (node_modules), and local environment files committed accidentally bloat the repository and cause unnecessary merge conflicts. Set up a proper .gitignore before the first commit, not after the damage is already in history.
Tag releases
A git tag marking each released version gives you an unambiguous, permanent reference point — genuinely useful when trying to determine exactly what code was live at a specific point in time, especially while debugging a production issue reported against an older release.
Common Mistakes to Avoid
- ⚠Vague commit messages like 'fix', 'update', or 'wip' that give future-you no useful context
- ⚠Committing an API key or secret, then 'removing' it in a later commit while it's still in history
- ⚠Working directly on main instead of a feature branch
- ⚠One giant commit mixing an unrelated bug fix, refactor, and new feature together
- ⚠No .gitignore set up from the start, leading to node_modules or build output getting committed
- ⚠Force-pushing to a shared branch, overwriting others' work without warning
Frequently Asked Questions
What do I do if I already committed a secret?
Rotate/revoke the exposed credential immediately — treat it as compromised regardless of whether you remove it from history, since it may already be cached or scraped. Removing it from history (via tools like git filter-repo) is a separate, more involved step for a shared repository.
Should I squash commits before merging?
Depends on the team's convention — squashing produces a cleaner, single-commit history on main, at the cost of losing the granular in-progress commit history. Both are legitimate approaches; consistency across the team matters more than which one you pick.
Is rebasing dangerous?
It's safe on a personal branch that hasn't been shared with others. Rebasing a branch other people have already pulled and built on top of rewrites history they're relying on, which is the scenario that actually causes problems.