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.

Practice

1. What is the main idea behind trunk-based development?

easy

A. Developing mostly on one main branch to avoid big merge conflicts

B. Creating many long-lived branches for each feature

C. Working only on local branches without pushing to remote

D. Merging branches only once a month

Solution

1. Step 1: Understand trunk-based development concept

   It focuses on working mainly on one main branch, often called trunk or main.

2. Step 2: Compare options with this concept

   Options A, C, and D describe practices that do not align with trunk-based development principles.

3. Final Answer:

   Developing mostly on one main branch to avoid big merge conflicts -> Option A

4. Quick Check:

   Trunk-based development = one main branch [OK]

Hint: Remember: trunk means main branch work mostly [OK]

Common Mistakes:

• Thinking trunk means many long-lived branches
• Believing merges happen rarely in trunk-based
• Confusing local-only work with trunk-based

2. Which of the following git commands is best to quickly merge a short-lived feature branch back to main in trunk-based development?

easy

A. git merge feature-branch

B. git rebase feature-branch

C. git checkout feature-branch

D. git branch -d feature-branch

Solution

1. Step 1: Identify the command to merge branches

   git merge feature-branch merges the feature branch into the current branch, usually main.

2. Step 2: Check other commands

   git rebase rewrites history, git checkout switches branches, and git branch -d deletes a branch but does not merge.

3. Final Answer:

   git merge feature-branch -> Option A

4. Quick Check:

   Merge short-lived branch = git merge [OK]

Hint: Merge feature branch with git merge [OK]

Common Mistakes:

• Using git checkout instead of merging
• Deleting branch before merging
• Confusing rebase with merge

3. Given this sequence of commands in trunk-based development:

git checkout main
git pull origin main
git checkout -b feature
# make changes
 git commit -am 'Add feature'
git checkout main
git merge feature

What is the state of the main branch after these commands?

medium

A. Main branch is unchanged and does not have feature changes

B. Main branch has the new feature changes merged in

C. Feature branch is deleted automatically

D. Main branch is behind origin/main

Solution

1. Step 1: Follow the commands step-by-step

   Start on main, update it from origin, create feature branch, commit changes, switch back to main, then merge feature into main.

2. Step 2: Understand merge effect

   After merge, main branch includes the feature changes locally.

3. Final Answer:

   Main branch has the new feature changes merged in -> Option B

4. Quick Check:

   Merge feature into main = main updated [OK]

Hint: Merge updates main branch with feature changes [OK]

Common Mistakes:

• Assuming merge deletes feature branch automatically
• Thinking main is unchanged after merge
• Forgetting to pull origin before branching

4. You tried to merge a short-lived branch into main but got a conflict error. What is the best way to fix this in trunk-based development?

medium

A. Force push main branch to overwrite remote

B. Delete the feature branch and start over

C. Resolve conflicts manually, then commit the merge

D. Ignore conflicts and continue

Solution

1. Step 1: Understand merge conflicts

   Conflicts happen when changes overlap. They must be fixed manually to keep code correct.

2. Step 2: Choose correct resolution

   Resolving conflicts manually and committing is the proper way. Deleting branch or ignoring conflicts causes problems.

3. Final Answer:

   Resolve conflicts manually, then commit the merge -> Option C

4. Quick Check:

   Fix conflicts manually = merge success [OK]

Hint: Fix conflicts manually before committing merge [OK]

Common Mistakes:

• Ignoring conflicts thinking git fixes automatically
• Deleting branch instead of resolving
• Force pushing without resolving conflicts

5. In trunk-based development, a team wants to avoid long-lived branches but still work on multiple features simultaneously. Which strategy fits best?

hard

A. Work only on main branch without any feature branches

B. Keep all features in one big branch for weeks before merging

C. Use separate repositories for each feature

D. Create short-lived feature branches, merge them quickly to main, and deploy often

Solution

1. Step 1: Understand trunk-based development goals

   It encourages short-lived branches merged quickly to main to reduce conflicts and speed releases.

2. Step 2: Evaluate options

   Create short-lived feature branches, merge them quickly to main, and deploy often matches this approach. Keep all features in one big branch for weeks before merging causes long-lived branches. Work only on main branch without any feature branches limits parallel work. Use separate repositories for each feature complicates repo management.

3. Final Answer:

   Create short-lived feature branches, merge them quickly to main, and deploy often -> Option D

4. Quick Check:

   Short-lived branches + quick merge = trunk-based best practice [OK]

Hint: Use short-lived branches merged fast to main [OK]

Common Mistakes:

• Thinking all work must be on main only
• Using long-lived branches defeats trunk-based purpose
• Splitting features into separate repos unnecessarily