Git Best Practices for Team Collaboration โ
Introduction โ
Beyond commands, effective collaboration depends on shared discipline. This guide enumerates pragmatic, enforceable practices that scale from small teams to large organizations.
Philosophy โ
Golden principles:
- Clarity beats cleverness (history tells a story)
- Smaller changes ship faster
- Automation over manual policing
- Reproducibility = reliability
Branch Strategy Patterns โ
| Strategy | Description | When to Use |
|---|---|---|
| Trunk-Based | Short-lived branches merged into main rapidly | Fast-moving teams, CI maturity |
| GitHub Flow | Feature branch โ PR โ merge โ deploy | SaaS, continuous delivery |
| Git Flow | develop, release, hotfix branches | Versioned products, slower cadence |
| Release Train | Time-boxed merges & releases | Coordinated multi-team releases |
Pick the simplest that meets governance needs. Avoid over-engineering.
Commit Message Convention (Example) โ
<type>(<scope>): <short summary>
<body>
<footer>Types: feat, fix, docs, refactor, test, chore, perf. Use conventional commits to enable automated changelogs.
Enforce via Hooks / CI โ
Examples:
bash
# .husky/commit-msg
#!/bin/sh
exec < /dev/tty
commitlint -E HUSKY_GIT_PARAMSPull Request Hygiene โ
| Practice | Target |
|---|---|
| Max lines changed | ~400 (soft) |
| Review turnaround | < 24h |
| All checks pass | Required before merge |
| Linked issue present | 100% |
Avoiding Long-Lived Branches โ
Mitigation tactics:
- Feature flags (merge incremental slices)
- API compatibility layers
- Dark launches / toggles
- Early upstream rebases
Handling Hotfixes โ
Workflow example:
bash
git checkout main
git pull
git checkout -b hotfix/critical-timezone
# fix, commit, test
git push origin hotfix/critical-timezone
# PR โ merge โ tag โ deployTagging Releases โ
bash
git tag -a v2.3.0 -m "Release v2.3.0"
git push origin v2.3.0Protecting Main Branch โ
Controls to enable (platform settings):
- Required status checks
- Required reviews (โฅ1 or โฅ2)
- Disallow force pushes
- Linear history (optional)
- Signed commits (if security sensitive)
Large File & Monorepo Guidance โ
- Use Git LFS for binaries
- Adopt sparse checkout for huge repos
- Define CODEOWNERS for critical paths
Standard .gitignore Baseline โ
Keep it minimal + project-specific. Avoid committing generated artifacts.
Pre-Merge Checklist (Automated Where Possible) โ
- [ ] Tests pass
- [ ] Linting/formatting clean
- [ ] Security scan passes
- [ ] No TODO left in changed code (or tracked issue)
- [ ] Docs updated if behavior changed
Rewriting History Policy โ
| Action | Allowed? | Notes |
|---|---|---|
| Rebase local feature | Yes | Before sharing |
| Force-push shared branch | Rare | Use --force-with-lease |
| Rebase protected branch | No | Breaks consumers |
| Squash on merge | Conditional | If preserving commit granularity not needed |
Collaboration Anti-Patterns โ
| Pattern | Problem | Remedy |
|---|---|---|
| Drive-by force pushes | Breaks teammates' clones | Restrict permissions |
| Mixed concerns PR | Hard to review | Split by concern |
| Silent merges | Low visibility | Require PR discussions |
| Working directly on main | Risk of broken production | Enforce branch protection |
Documentation Anchors โ
Maintain:
- CONTRIBUTING.md
- CODEOWNERS
- Architecture decision records (ADR)
- Onboarding cheat sheet
Metrics (Health Indicators) โ
- Mean time to merge (MTTM)
- % PRs > 1,000 LOC (reduce)
- Flaky test rate
- Revert frequency post-merge
Summary โ
Effective Git collaboration blends social agreements, automation, and disciplined workflows. Make the happy path the easy path.
Next Steps โ
- Hooks & automation (
git-hooks-and-automation.md) - Undo strategies (
git-reset-revert-and-checkout-explained.md)
Key Commands
bash
git tag -a <tag> -m "msg"
git push origin <tag>
git push origin --delete <branch>