Git Workflow Best Practices for Teams (Checklist and Anti-Patterns)

This lesson brings Modules 2 to 6 together into a practical set of team best practices for Git and GitHub: daily habits, branch and pull request rules, security, history hygiene, what belongs in a repository, automation, common anti-patterns and a checklist.

---

✅ Why Best Practices?

Git gives teams enormous flexibility, which also means many ways to create a mess: giant commits, broken main, lost work, leaked secrets and endless conflicts. These best practices, collected from the earlier lessons, keep a team’s repository clean, safe and fast to work with.

---

🔁 Daily Habits

Practice	Why	Lesson
Pull (or fetch) before you start and before you push	Fewer and smaller conflicts	fetch vs pull
Commit small, focused changes often	Easy to review, revert and bisect	first repository
Check git diff --staged before committing	Catch debug code and secrets	staging area
Write meaningful commit messages	History becomes documentation	commit messages
Push at least daily	Backup, visibility and early CI feedback	push and pull

---

🌿 Branches and Pull Requests

• One branch per task, named consistently (feature/QA-123-login-tests) (branches).
• Keep branches short-lived: merge within days, not weeks.
• Never commit directly to main on a team project; use pull requests.
• Small pull requests with a clear description and testing notes.
• Update your branch with the latest main before merging (rebase your own branch, or merge).
• Delete branches after merging, locally and on GitHub.

---

🛡️ Protect the Main Branch

Configure on GitHub (branch protection):

• Require pull requests and at least one approval.
• Require status checks (tests, lint) to pass.
• Block force pushes and deletions.
• Use CODEOWNERS to request the right reviewers automatically.

---

🔐 Security Practices

• Never commit secrets: use .env files listed in .gitignore and CI secrets.
• If a secret leaks, revoke and rotate it first, then clean history.
• Use SSH keys or tokens with minimal scopes and expiry dates (SSH, tokens).
• Enable 2FA, Dependabot and secret scanning (security).

---

🧬 History Hygiene

Do	Do not
Rewrite your own local commits (amend, interactive rebase) before sharing	Rewrite commits on shared branches
Use git revert to undo pushed commits	Use git reset + force push on main
Use --force-with-lease on your own branches	Use plain --force
Squash “WIP” and “fix typo” commits before merging	Merge noisy history into main
Tag releases with semantic versions	Move or reuse release tags

See undo changes, interactive rebase and tags.

---

📦 What Belongs in the Repository

✅ Commit	❌ Do not commit
Source code and tests	Dependencies (node_modules/, venv/)
Configuration templates (.env.example)	Real secrets (.env, keys, tokens)
Lock files (package-lock.json)	Build output and test reports
Documentation (README, CONTRIBUTING)	Personal editor settings (unless shared on purpose)
CI workflows (.github/workflows/)	Large binaries (use Git LFS or artifact storage)

---

🤖 Automate Quality

• Run tests and linting on every PR with GitHub Actions.
• Use pre-commit hooks for formatting, linting and commit message checks (hooks and Husky).
• Keep dependencies updated with Dependabot.

---

🚫 Common Anti-Patterns

Anti-pattern	Better approach
“Mega commits” with 50 files and the message “updates”	Small, focused commits with clear messages
Long-lived feature branches (weeks)	Short branches, feature flags, frequent integration
Working directly on main	Branch + pull request
Ignoring failing CI	Fix or revert immediately; red builds block everyone
Committing generated reports or node_modules	A proper .gitignore
Force-pushing shared branches	Revert, or coordinate with the team

---

📋 Team Checklist

• [ ] Branching strategy chosen and documented (strategies)
• [ ] Branch naming and commit message conventions agreed
• [ ] main protected; reviews and CI required
• [ ] PR template and CODEOWNERS in place
• [ ] .gitignore covers dependencies, reports and secrets
• [ ] CI runs tests on every pull request
• [ ] Releases tagged with semantic versions

---

📝 Assignment

1. Audit one of your repositories against the “What belongs in the repository” table and fix what you find.
2. Write a CONTRIBUTING.md for git-practice covering branch names, commit messages and the PR process.
3. Review your last 20 commits with git log --oneline and rewrite three messages (on a local branch) using interactive rebase later in Module 7.
4. Complete the team checklist for a real or imaginary team of five.

---

❓ FAQ

🤔 What are Git best practices for teams?

Commit small and often with clear messages, use short-lived branches and pull requests, protect main with reviews and CI, never commit secrets, and avoid rewriting shared history.

🤔 How often should I commit?

Whenever you complete a small, logical step that leaves the code working, often several times a day.

🤔 Should I commit directly to main?

Not in a team. Use a branch and a pull request so changes are reviewed and tested before reaching main.

🤔 What files should not be committed to Git?

Secrets, dependencies, build output, test reports, logs and large binaries. List them in .gitignore.

🤔 How do I keep a clean Git history?

Write focused commits, squash fixup commits before merging, use squash or rebase merges for PRs, and revert instead of rewriting shared branches.

---

🎯 Next Steps

• 🧬 Interactive Rebase: Squash, Reword and Reorder Commits
• 🔐 Branch Protection Rules and Rulesets
• 📘 Git and GitHub Tutorial: full course