Trunk-based development in Git - Deep Dive

Overview - Trunk-based development

What is it?

Trunk-based development is a way of working with code where all developers share one main branch called the trunk. Instead of creating long-lived separate branches, developers make small, frequent changes directly or through very short-lived branches merged quickly. This helps keep the codebase simple and up to date for everyone.

Why it matters

Without trunk-based development, teams often face big problems merging code after long delays, causing conflicts and bugs. This slows down delivery and makes teamwork harder. Trunk-based development solves this by encouraging constant integration, reducing surprises, and enabling faster, safer releases.

Where it fits

Before learning trunk-based development, you should understand basic git concepts like branches, commits, and merges. After mastering it, you can explore continuous integration, feature flags, and advanced release strategies like canary deployments.

Mental Model

Core Idea

Trunk-based development means everyone works together on one main code line, making small changes often to avoid conflicts and keep progress smooth.

Think of it like...

It's like a group of friends writing a story together on one notebook page, each adding a sentence quickly and passing it on, instead of writing separate pages and trying to combine them later.

┌───────────────┐
│   Trunk/Main  │
│───────────────│
│  • Commit 1  │
│  • Commit 2  │
│  • Commit 3  │
└─────┬─────────┘
      │
  ┌───┴───┐
  │Short  │
  │Branch │
  └───┬───┘
      │ Merge quickly
      ▼
  Back to Trunk

Build-Up - 7 Steps

1

Foundation

Understanding the Trunk Concept

Concept: Learn what the trunk (main branch) is and why it is central in trunk-based development.

In git, the trunk is usually the 'main' or 'master' branch. It holds the latest stable code. Instead of working on many long branches, trunk-based development focuses on this single branch where everyone integrates their work frequently.

Result

You know the trunk is the main shared place for code changes.

Understanding the trunk as the single source of truth helps prevent confusion about where to put code changes.

2

Foundation

Basics of Branching and Merging

Concept: Review how branches and merges work in git to prepare for short-lived branches.

Branches let you work on code separately. Merging brings changes back together. In trunk-based development, branches are very short-lived, often just a few hours or a day, to keep merges simple and fast.

Result

You can create, use, and merge branches quickly without long delays.

Knowing how to merge frequently reduces the risk of big conflicts later.

3

Intermediate

Small, Frequent Commits Practice

🤔Before reading on: do you think making many small commits or fewer big commits is better for trunk-based development? Commit to your answer.

Concept: Trunk-based development encourages small, frequent commits to keep the codebase stable and integration smooth.

Instead of saving many changes for later, developers commit small pieces of work often. This makes it easier to find and fix problems and keeps the trunk healthy.

Result

Code changes are easier to review and integrate without breaking the trunk.

Understanding that small commits reduce complexity helps maintain a stable main branch.

4

Intermediate

Using Feature Flags for Incomplete Work

🤔Before reading on: do you think incomplete features should be merged to trunk or kept separate until done? Commit to your answer.

Concept: Feature flags let developers merge unfinished features safely by turning them off in production.

When a feature is not ready, developers wrap it in a feature flag. This way, the code is in trunk but inactive, allowing continuous integration without affecting users.

Result

Incomplete features do not break the main code or user experience.

Knowing how feature flags enable safe integration changes the way teams handle work-in-progress.

5

Intermediate

Continuous Integration with Trunk

Concept: Trunk-based development works best with automated testing and integration tools that check every change.

Every commit to trunk triggers automated builds and tests. This ensures new changes do not break existing code and keeps the trunk always ready to release.

Result

The team quickly knows if a change causes problems.

Understanding that automation supports trunk-based development helps maintain high code quality.

6

Advanced

Handling Conflicts in High-Activity Trunks

🤔Before reading on: do you think conflicts increase or decrease with trunk-based development? Commit to your answer.

Concept: Frequent integration reduces big conflicts but requires quick conflict resolution skills.

Because everyone merges often, conflicts are smaller and easier to fix. Developers must resolve conflicts quickly to keep the trunk clean and moving.

Result

Conflicts are less painful and less frequent than in long-lived branches.

Knowing that quick conflict resolution is a skill needed prevents delays in integration.

7

Expert

Scaling Trunk-Based Development in Large Teams

🤔Before reading on: do you think trunk-based development works only for small teams or also for large teams? Commit to your answer.

Concept: Large teams use trunk-based development with additional practices like code ownership and modular design to scale effectively.

In big teams, the trunk is still central, but teams organize code ownership and use tools to manage changes. Modular code helps reduce conflicts and allows parallel work.

Result

Even large teams can benefit from trunk-based development without chaos.

Understanding how to adapt trunk-based development for scale unlocks its power in real-world projects.

Under the Hood

Trunk-based development relies on git's fast branching and merging capabilities. Developers create short-lived branches or commit directly to trunk. Automated systems run tests on every commit to ensure stability. Feature flags allow incomplete code to coexist safely. The process minimizes merge conflicts by integrating changes continuously.

Why designed this way?

It was designed to solve the problem of long-lived branches causing complex merges and integration hell. Early software teams faced delays and bugs from infrequent merges. Trunk-based development emerged to keep code integration continuous, reducing risk and speeding delivery. Alternatives like long feature branches were rejected because they delayed feedback and increased conflicts.

┌───────────────┐
│ Developer 1   │
│  ┌─────────┐  │
│  │ Short   │  │
│  │ Branch  │  │
│  └────┬────┘  │
└───────│───────┘
        │ Merge quickly
        ▼
┌───────────────┐
│    Trunk      │
│  (Main Line)  │
└───────┬───────┘
        │ CI runs tests
        ▼
┌───────────────┐
│ Automated     │
│ Testing &     │
│ Deployment    │
└───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does trunk-based development mean never using branches? Commit yes or no.

Common Belief: Trunk-based development means no branches at all.

Reality: It allows short-lived branches but discourages long-lived ones. Branches exist but are merged quickly.

Why it matters: Thinking no branches are allowed can confuse developers and prevent using helpful short branches for safe work.

Quick: Does frequent merging increase conflicts? Commit yes or no.

Common Belief: Merging often causes more conflicts and slows development.

Reality: Frequent merges keep conflicts small and easier to resolve, reducing overall conflict pain.

Why it matters: Believing frequent merges cause problems may lead teams to avoid them, causing bigger conflicts later.

Quick: Is trunk-based development only for small teams? Commit yes or no.

Common Belief: Trunk-based development only works for small teams.

Reality: It scales to large teams with proper practices like modular code and code ownership.

Why it matters: Assuming it doesn't scale limits adoption in big projects that could benefit greatly.

Quick: Can incomplete features be merged safely without breaking the product? Commit yes or no.

Common Belief: Incomplete features must stay out of trunk until fully done.

Reality: Feature flags allow incomplete features to be merged safely and turned off in production.

Why it matters: Not using feature flags can delay integration and increase risk of big merges.

Expert Zone

1

Trunk-based development requires cultural discipline; without team commitment, it can lead to unstable trunk.

2

Automated testing speed and reliability are critical; slow tests can block frequent merges and reduce benefits.

3

Feature flags add complexity and require cleanup; managing them poorly can cause technical debt.

When NOT to use

Trunk-based development may not fit projects with strict regulatory requirements needing isolated audits or very large legacy codebases where modularization is impossible. Alternatives include Gitflow or release branching strategies.

Production Patterns

In production, teams use trunk-based development combined with continuous integration pipelines, feature toggles, and canary releases. They enforce code reviews and automated quality gates to keep trunk stable while enabling rapid delivery.

Connections

Continuous Integration

Builds-on

Trunk-based development depends on continuous integration to verify every change quickly, ensuring the main code line stays healthy.

Feature Flags

Complementary practice

Feature flags allow teams to merge incomplete work safely, enabling trunk-based development without blocking unfinished features.

Lean Manufacturing

Similar pattern

Both focus on small, frequent deliveries to reduce waste and catch problems early, showing how software development borrows from manufacturing efficiency principles.

Common Pitfalls

#1 Waiting too long to merge changes causes big conflicts.

Wrong approach:

git checkout feature-branch
# work for weeks without merging
# finally merge to trunk causing conflicts

Correct approach:

git checkout feature-branch
# commit small changes daily
# merge to trunk multiple times a day

Root cause:

Misunderstanding that frequent merges reduce conflicts leads to delayed integration and painful merges.

#2 Merging incomplete features without feature flags breaks production.

Wrong approach:

git merge incomplete-feature-branch
# deploy to production
# users see broken features

Correct approach:

Wrap incomplete features in feature flags
# merge to trunk
# deploy safely with features off

Root cause:

Not using feature flags causes unstable trunk and user-facing bugs.

#3 Ignoring automated tests causes broken trunk after merges.

Wrong approach:

Merge changes without running tests
# broken build
# delays fixing issues

Correct approach:

Set up CI to run tests on every commit
# fix failures immediately

Root cause:

Skipping automation removes safety net, making frequent merges risky.

Key Takeaways

Trunk-based development keeps all work integrated on one main branch to avoid complex merges.

Small, frequent commits and merges reduce conflicts and keep the codebase stable.

Feature flags enable merging incomplete work safely without affecting users.

Automated testing and continuous integration are essential to maintain trunk health.

This approach scales to large teams with proper practices like modular code and code ownership.