The Merge Conflict That Started a War
Sarah pushed code. Tom pushed code. Both changed same file.
Merge conflict overwrote Sarah’s staging URL with Tom’s production URL. App deployed. Production broke.
The real problem? No git workflow. Everyone just pushed to main.
The Git Workflows
Level 1: Trunk-Based Development
Philosophy: Everyone commits to main. Deploy often. Fix fast.
When to use: Small teams (2-5), experienced developers, good test coverage.
Pros: Simple, fast, no long-lived branch conflicts. Cons: Requires discipline, one bad commit breaks everything.
Level 2: Feature Branch Workflow (My Recommendation)
Philosophy: Create a branch for each feature. Merge when done.
main (protected)
├── feature/user-auth
├── feature/dark-mode
└── bugfix/login-error
Rules:
- Create branch for each feature
- Name descriptively
- Pull request before merging
- Keep branches short-lived (< 2 days)
Example:
# Create feature branch
git checkout -b feature/add-search
# Make changes, commit often
git commit -m "Add search bar component"
# Push and create PR
git push -u origin feature/add-search
# Get review, merge, delete branch
git branch -d feature/add-search
Branch naming:
feature/user-authentication
bugfix/navbar-overflow
hotfix/payment-api-timeout
docs/api-documentation
Pros: Isolates work, easy review, safe experimentation. Cons: Merge conflicts if branches live too long.
Level 3: GitHub Flow
Philosophy: main is always deployable. Deploy from pull requests immediately after merge.
Perfect for continuous deployment. Requires good CI/CD and tests.
My Workflow for Teams
For small teams (2-5):
- Branch from main for each task
- Name branches clearly
- Push early, open PR when ready
- At least one approval required
- Tests must pass
- Squash merge to keep history clean
- Delete branch after merge
Pull Request Best Practices
1. Descriptive Titles
❌ "Fix bug"
✅ "Fix: User profile page crashes on missing avatar"
2. Add Context
## What
Adds user authentication with email/password.
## Why
Users need to log in to access profile.
## How
- Added login form component
- Integrated with auth API
- Added session management
## Testing
- [ ] Login with valid credentials
- [ ] Invalid credentials show error
- [ ] Logout clears session
3. Keep PRs Small
Aim for < 400 lines changed. Easier to review, fewer bugs.
4. Request the Right Reviewers
Request people whose expertise matches changes.
Handling Merge Conflicts
Prevention is better:
# Keep your branch updated
git checkout main
git pull
git checkout feature/your-branch
git rebase main
When conflicts happen:
# Pull latest
git checkout main && git pull
git checkout feature/your-branch && git merge main
# Resolve conflicts in editor (look for <<<<<<< HEAD markers)
# Stage resolved files
git add src/api.ts
# Complete merge
git commit -m "Merge main, resolve conflicts"
Commit Message Best Practices
<type>: <description>
[Optional longer description]
Types: feat, fix, docs, refactor, test
Examples:
✅ "feat: Add user authentication with JWT"
✅ "fix: Prevent form submission with empty fields"
✅ "refactor: Extract validation logic to utils"
❌ "Update stuff"
Protecting Main Branch
GitHub Branch Protection Rules:
✅ Require pull request before merging
✅ Require approvals: 1
✅ Require status checks to pass
✅ Require branches up to date
❌ Allow force pushes (NEVER)
Common Scenarios
I Committed to Main by Accident
# Undo the commit but keep changes
git reset --soft HEAD~1
# Create feature branch
git checkout -b feature/my-feature
git commit -m "Add feature"
My Branch is Behind Main
git checkout main && git pull
git checkout feature/my-branch
git rebase main
Git workflows prevent conflicts, smooth collaboration, avoid 2 AM production emergencies.
Pick a workflow that fits your team. Enforce consistently. Adjust when needed.
Protect your main branch. Deploy with confidence.
Happy collaborating!