Trunk-Based Development

Quick Summary

Trunk-based development (TBD) is a branching strategy where all developers integrate their changes into a single shared branch (main / trunk) at least once a day. Feature branches exist but live for hours — not weeks. This approach is the foundation of modern CI/CD and is used by Google, Facebook, and Netflix.

---

Core Principle

gitGraph
    commit id: "C1"
    commit id: "C2"
    branch feature/quick-fix
    commit id: "Fix"
    checkout main
    merge feature/quick-fix id: "Merge (same day)"
    commit id: "C3"
    branch feature/api
    commit id: "API"
    checkout main
    merge feature/api id: "Merge (hours later)"
    commit id: "C4"
    commit id: "C5"

Key rule: Branches are short-lived (hours, not days). Main branch is always deployable.

---

TBD vs Gitflow Comparison

Aspect	Trunk-Based	Gitflow
Long-lived branches	Only main	main + develop
Feature branch lifetime	Hours to 1-2 days	Days to weeks
Integration frequency	Multiple times daily	At release time
Release process	Deploy from main anytime	Dedicated release branches
Merge conflicts	Rare (small changes)	Common (large branches)
CI/CD compatibility	Excellent	Moderate
Team size	Any (Google uses it with 30K+ engineers)	Medium teams
Risk of breakage	Low (small increments)	Higher (big merges)

---

The Workflow

Daily Flow

# 1. Start from latest main
git checkout main
git pull --rebase

# 2. Create a short-lived branch
git checkout -b feature/add-search-bar

# 3. Make focused changes (small scope)
git add .
git commit -m "feat: add search bar component"

# 4. Rebase onto latest main (stay current)
git fetch origin
git rebase origin/main

# 5. Push and create PR (or merge directly)
git push -u origin feature/add-search-bar

# 6. After merge — delete branch immediately
git checkout main
git pull
git branch -d feature/add-search-bar

Feature Flags

For larger features that take days, use feature flags instead of long-lived branches:

// Code merged to main immediately, but hidden behind a flag
if (featureFlags.isEnabled('new-dashboard')) {
    renderNewDashboard();
} else {
    renderOldDashboard();
}

Without Feature Flags	With Feature Flags
Long branch → big merge → risk	Small merges → always deployable
Feature hidden in a branch	Feature hidden behind a flag
Testing only on branch	Testing in production (gradually)
All-or-nothing release	Gradual rollout (1% → 10% → 100%)

---

Rules for Success

1. Merge to main at least once per day — no exceptions
2. Keep branches under 200 lines changed — if larger, split it
3. Run CI on every commit — automated tests catch breakage immediately
4. Use feature flags for WIP — merge incomplete features safely
5. Fix broken builds immediately — main must always be green

---

When to Use Trunk-Based Development

Scenario	TBD Suitable?
Continuous deployment environment	✅ Perfect fit
Web applications / SaaS	✅ Yes
Solo developer	✅ Simple and effective
Team with strong CI/CD pipeline	✅ Yes
Mobile apps with store review cycles	⚠️ Pair with release branches
Regulated environments (compliance reviews)	⚠️ May need adaptations

---

Best Practices

• Invest in CI/CD — automated tests are mandatory for TBD
• Use feature flags over long branches for gradual rollouts
• Pair programming / code review — small PRs are quick to review
• Keep main deployable — every commit should be production-ready
• Branch lifetime < 24 hours — if it's taking longer, scope is too big

What's Next

1. Monorepo Patterns — Managing multiple projects in a single repo
2. GitHub Actions & CI/CD — Automate your pipeline