Use Cases

  • Large teams with high throughput requirements and mature CI/CD infrastructure
  • Projects with comprehensive automated testing (unit, integration, contract)
  • Organizations practicing continuous delivery or continuous deployment
  • When feature flag infrastructure is available (or you are willing to adopt it)

Components

  • trunk (main) (main-branch): The single authoritative branch. Always in a releasable state. Every engineer integrates here at least daily.
  • feature flags (strategy): Runtime toggles (e.g., LaunchDarkly, Unleash, Flagsmith) that hide incomplete features from users while code ships to production
  • short-lived branches (supporting-branch): Optional branches for code review workflows. Must integrate back to trunk within 1-2 days maximum. Paul Hamant's trunkbaseddevelopment.com recommends less than 2 days.

Steps

  1. Step 1: Create feature flag: Before writing new functionality, create a feature flag in your flag management system so incomplete work can be deployed safely
  2. Step 2: Commit small increments to trunk: Make incremental commits directly to trunk (or via short-lived branch) with the feature flag off. Each commit must leave trunk in a passing state.
  3. Step 3: Automated testing on every commit: Each commit triggers the full CI pipeline. A broken build is a team emergency — fix it within minutes, not hours, or revert.
  4. Step 4: Deploy to production continuously: Trunk deploys to production automatically (or on-demand). Incomplete features are invisible to users because the flag is off.
  5. Step 5: Enable feature flag: When the feature is complete and tested, enable the flag — first for internal users or a percentage of traffic, then fully
  6. Step 6: Remove feature flag: Once the feature is stable and permanent, delete the flag from code. Stale flags are a form of technical debt.

Workflow Diagram

gitGraph commit id: "flag off: start login" commit id: "flag off: add form" branch review/login checkout review/login commit id: "address review" checkout main merge review/login id: "merge (flag off)" commit id: "flag on: login live" commit id: "remove flag"
Step 1 of —

Common Gotchas

  • Requires feature flag infrastructure: Without a proper feature flag service, TBD forces you to ship only complete features, which defeats the model. Retrofitting flags into an existing codebase takes significant effort. critical
  • Broken trunk blocks the entire team: A failing commit on trunk breaks CI for every engineer. The cultural rule is "never leave a broken build" — fix forward or revert within minutes, not hours. critical
  • High CI/CD requirements: TBD requires a fast, reliable automated test suite. If tests take 45+ minutes, developers won't integrate frequently enough and trunk becomes a merge battlefield. critical
  • Not suitable for all features: Some large refactors or data migrations are hard to break into flag-gated increments. These require extra patterns (branch-by-abstraction, expand-contract). important
  • Junior developer risk: Committing directly to trunk is high-stakes. Great for experienced engineers with strong testing discipline; risky for teams without a strong test-first culture. important

Best Practices

  • Keep commits small and focused — if a commit takes more than a day to write, break it down
  • Adopt branch-by-abstraction for large refactors instead of long-lived feature branches
  • Write tests first (or alongside) — never commit untested code to trunk
  • Enforce a sub-10-minute CI pipeline; anything longer discourages frequent integration
  • Use canary releases or percentage rollouts when enabling flags in production
  • Treat stale feature flags as bugs — clean them up within days of full rollout

Pros and Cons

Pros

  • Minimizes merge conflicts by keeping branches short-lived
  • Enables continuous delivery
  • Fastest development cycle for teams with mature CI/CD
  • Simplified branching mental model (one authoritative branch)
  • Scales to very large teams (used by Google and Meta at thousands of engineers)

Cons

  • Requires sophisticated infrastructure (flags, fast CI, observability tooling)
  • High risk if test coverage is inadequate — bugs ship silently to production
  • Feature flag management adds operational complexity and flag debt
  • Significant cultural shift — many developers are uncomfortable committing to a shared trunk
  • Not suitable for firmware, hardware drivers, or libraries with explicit versioned release contracts

Real-World Examples

  • Google: Google runs a single monorepo ("google3") with over one billion files and hundreds of thousands of engineers all committing to trunk. They rely on hermetic builds, pre-submit testing, and Critique (code review) to keep trunk green at scale.
  • Meta (Facebook): Meta's main PHP/Hack monorepo receives thousands of commits per day. Engineers use Sapling (their VCS) and Gatekeeper (feature flags) to roll out changes to a fraction of users before full release.
  • Microsoft (Windows): Since ~2017, the Windows team migrated from a complex per-feature branch model to trunk-based development using VFSForGit (now ProjFS). They reported dramatic reduction in merge conflicts and integration testing time.