Skip to content

Git Best Practices

Professional Git habits — commit hygiene, branch strategies, and workflows for clean history.

What you'll learn

  • How to write meaningful commits and keep history clean
  • Branch naming and feature branch workflows
  • Daily habits: pull, commit, push discipline
  • Team conventions for a maintainable repository

Concept

Why Best Practices Matter

Git is a tool, but how you use it determines whether your project's history is a useful record or an unreadable mess. Good Git habits make it easier to:

  • Understand what changed and why
  • Find and revert bugs
  • Onboard new team members
  • Generate changelogs and release notes
  • Collaborate without conflicts

Commit Best Practices

Make Atomic Commits

Each commit should represent one logical change. Do not mix a bug fix, a new feature, and a refactor in the same commit.

# Bad: three unrelated changes in one commit
git add -A
git commit -m "fix login, add search, refactor utils"

# Good: three separate commits
git add login.js
git commit -m "fix: handle null user in login redirect"
git add search.js
git commit -m "feat: add search with debouncing"
git add utils.js
git commit -m "refactor: extract validation into utils"

Write Meaningful Messages

A commit message should explain why the change was made, not just what changed (the diff shows what).

Good:

  • fix: handle empty cart in checkout total calculation
  • feat: add JWT refresh token rotation for security
  • refactor: extract payment validation into separate module

Bad:

  • fix
  • update
  • wip
  • stuff

Use Conventional Commits

Adopt the Conventional Commits format for consistency and automation:

<type>(<scope>): <description>

feat(auth): add OAuth2 login flow
fix(cart): resolve negative quantity bug
docs(api): update authentication examples
chore(deps): upgrade express to 4.18
refactor(payment): simplify refund logic
test(user): add integration tests for registration

Commit Early and Often

Make small commits as you work. You can always squash them before pushing (with interactive rebase). It is much harder to split a giant commit after the fact.

Branch Best Practices

Use Descriptive Branch Names

# Good
feature/user-authentication
bugfix/login-redirect-loop
hotfix/security-patch-cve-2024
chore/upgrade-dependencies
docs/api-reference

# Bad
my-changes
fix
branch1
test

Keep Branches Short-Lived

Feature branches should be merged within a few days, not weeks. Long-lived branches diverge from main and cause painful merges. If a feature is large, break it into smaller, mergeable pieces.

One Branch Per Feature

Do not pile multiple features onto one branch. Each feature gets its own branch, its own PR, and its own review.

Daily Workflow Habits

Pull Before You Push

git pull --rebase origin main
# resolve any conflicts
git push

Always pull before pushing to avoid rejection errors and surprise conflicts.

Commit Before You Pull

If you have local changes, commit or stash them before pulling. Uncommitted changes can conflict with the pull and leave you in a messy state.

Use .gitignore From the Start

Create your .gitignore before the first commit. It is much harder to remove tracked files from history than to never track them.

Never Commit Secrets

# .gitignore
.env
*.key
*.pem
secrets/

If you accidentally commit a secret:

  1. Rotate the credential immediately
  2. Remove it from history with git filter-repo or BFG
  3. Add it to .gitignore

History Hygiene

Rebase Before Merging

Keep your history linear by rebasing feature branches before merging:

git checkout feature-branch
git fetch origin
git rebase origin/main
git checkout main
git merge feature-branch  # fast-forward, no merge commit

Squash WIP Commits

Use interactive rebase to squash "WIP" commits before pushing:

git rebase -i origin/main
# squash your work-in-progress commits into clean, meaningful ones

Do Not Rewrite Shared History

Never rebase or amend commits that others have pulled. Use git revert instead of git reset on shared branches.

Team Conventions

  • Agree on a workflow: GitHub Flow, Git Flow, or Trunk-Based — pick one and document it
  • Require PR reviews: protect main with branch protection rules
  • Use PR templates: create .github/pull_request_template.md for consistent descriptions
  • Enforce commit conventions: use commit-msg hooks or tools like commitlint
  • Automate with CI: run tests and linting on every PR
  • Keep main always green: main should always be deployable

The Golden Habits

  1. Commit small, atomic changes with clear messages
  2. Pull before you push (git pull --rebase)
  3. Use feature branches with descriptive names
  4. Review every PR before merging
  5. Never commit secrets — use .gitignore
  6. Never rewrite shared history — use revert, not reset
  7. Test before you commit — or let hooks do it for you
  8. Keep main deployable — always green, always tested

Example

              # --- Atomic commits: one logical change per commit ---
git add src/auth/login.js
git commit -m "feat(auth): add JWT token generation on login"

git add src/auth/refresh.js
git commit -m "feat(auth): add refresh token rotation"

git add src/auth/middleware.js
git commit -m "refactor(auth): extract token validation into middleware"

# --- Daily workflow: pull, work, commit, push ---
git checkout main
git pull --rebase origin main

git checkout -b feature/user-settings
# ... make changes ...
git add .
git commit -m "feat(settings): add user preference management"

# Keep your branch updated with main
git fetch origin
git rebase origin/main

git push -u origin feature/user-settings
# Open a PR, get review, merge

# --- Clean up before a PR ---
git rebase -i origin/main
# squash WIP commits, reword messages, reorder

# --- Protect main: never commit directly ---
# On GitHub: Settings > Branches > Branch protection rules
# - Require pull request reviews before merging
# - Require status checks to pass before merging
# - Require branches to be up to date before merging

# --- Use a PR template ---
mkdir -p .github
cat > .github/pull_request_template.md << 'EOF'
## What
<!-- Describe what this PR does -->

## Why
<!-- Link to issue, explain the motivation -->

## Testing
- [ ] Unit tests pass
- [ ] Manual testing done

## Checklist
- [ ] No console.log left in code
- [ ] No secrets committed
EOF

# --- Never commit secrets ---
echo ".env" >> .gitignore
echo "*.key" >> .gitignore
echo "secrets/" >> .gitignore
git add .gitignore
git commit -m "chore: update gitignore for secrets"

# --- If you accidentally committed a secret ---
git rm --cached .env
git commit -m "fix: stop tracking .env file"
# Then rotate the leaked credential immediately!
# Use git filter-repo to purge from history if needed
            

Shows atomic commits with Conventional Commits messages, the daily pull-work-commit-push workflow, keeping branches updated with rebase, cleaning up history before a PR, setting up branch protection and PR templates, and handling secrets properly. These habits separate professional Git usage from amateur.

Try it

Common mistakes

The mistake

Committing large, unrelated changes in one giant commit

The fix

Make atomic commits — one logical change per commit. Use git add <specific-files> instead of git add . to stage only related changes. If you have already committed everything together, you can use interactive rebase (git rebase -i) to split the commit before pushing.

The mistake

Committing directly to main instead of using feature branches and PRs

The fix

Never commit directly to main on a shared project. Create a feature branch, make your changes, push, and open a pull request for review. Enable branch protection on GitHub to prevent direct pushes to main. This ensures every change is reviewed and tested before it lands.

Related Snippets

Related Cheatsheets

Practice Git Best Practices

6 exercises

Practice Git Best Practices

Look up unfamiliar terms

A beginner-friendly glossary explains jargon in plain English — variables, functions, DOM, Promise, and more.

View glossary

Build real projects

Apply what you learned by building guided projects with starter code and solutions.

View projects

Decode error messages

Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.

View errors