Git Commit Best Practices

A good commit contains one complete change and a message that explains its purpose without requiring the reader to inspect the entire diff.

Rule 1: 1 Commit = 1 Change

# Bad: an entire week's work in one commit
git commit -m "week's work"

# Good: each change separately
git commit -m "feat: add user model"
git commit -m "feat: create login form"
git commit -m "fix: fix email validation"

Atomic commits simplify code review, let you revert a specific change, and make the history readable as documentation.

Rule 2: Write Meaningful Messages

Format: <type>: <what was done>

Commit types:
- feat — new feature
- fix — bug fix
- docs — documentation
- refactor — refactoring
- test — tests
- chore — dependencies, configs

# Good
feat: add two-factor authentication support
fix: fix 500 error on empty email
docs: update API endpoint documentation

# Bad
update
fix
done

Rule 3: Commit Working Code

Before committing:
1. Run the code — does it work?
2. Do tests pass?
3. Does the linter pass?

If you need to save unfinished work:

git stash      # temporarily hide changes
git stash pop  # bring them back

Rule 4: Review the Diff Before Committing

git diff --staged  # see what will go into the commit

Common mistakes: committing console.log(), .env with passwords, accidentally deleting important code.

Rule 5: Use .gitignore

# .gitignore
node_modules/
__pycache__/
.env
*.log
.DS_Store
dist/

Create .gitignore at the start of the project — before the first commit.

Conventional Commits

The industry standard:

<type>[optional scope]: <description>

[optional body]

feat(auth): add two-factor authentication
fix(api): handle null values in user endpoint
docs(readme): update installation instructions
refactor(payment): simplify checkout logic

Scope (optional) narrows the area of change: auth, api, ui, db.

Pre-Commit Checklist

• Code runs and works
• Tests pass
• Diff reviewed — everything looks right
• Commit message is meaningful
• No secrets (passwords, tokens)
• No debug print / console.log
• .gitignore is configured