tbdflow ❤️ monorepo

Monorepos are a powerful strategy for managing code. By keeping all your projects in a single repository, you get a single source of truth, simplified dependency management, and easier cross-team collaboration. As influencial thought-leaders and others in the DevOps space have pointed out, monorepos are a natural fit for Trunk-Based Development (TBD) because they both revolve around a single, shared mainline of code.

But with great power comes great responsibility. The biggest challenge of a monorepo is the risk of accidental cross-project changes. How do you commit a change to a root-level README.md without accidentally staging unrelated work from the frontend and backend projects?

This is exactly the kind of workflow problem that a good tool should solve. That’s why tbdflow is now “monorepo-aware.”

The Goal: Safe Commits from Anywhere

The ideal monorepo workflow should be intuitive and safe. A developer should be able to:

1. Make a change within a specific project (e.g. frontend/) and have their commit be automatically scoped to just that project.
2. Make a change to a shared, root-level file (like CHANGELOG.md) and commit it without fear of including unrelated work from other projects.

tbdflow now supports this out of the box with a simple configuration.

How It Works: The monorepo Config

To enable monorepo mode, you first run tbdflow init at the root of your repository. This creates a .tbdflow.yml file where you can define your project directories.

# in .tbdflow.yml
monorepo:
  enabled: true
  # A list of all directories that are self-contained projects.
  # These will be excluded from root-level commits and status checks.
  project_dirs:
    - "frontend"
    - "backend-api"
    - "infra"

Escape hatch

For “vertical slice” changes there is an escape hatch you can use: --include-projects. This overrides the default safety mechanism and stages all changes from all directories, readers beware…

With this in place, tbdflow’s behavior becomes context-aware:

Committing from the Root

When you run tbdflow commit from the root of the repository, the tool is now smart enough to know it should only stage changes to root-level files. It automatically constructs a git add command that excludes all the project directories you’ve defined.

This gives you a safe, reliable way to manage your shared, repository-level files.

Committing from a Project Directory

To work within a specific project, you first cd into that directory and run tbdflow init again. This creates a new, project-specific .tbdflow.yml file that tells tbdflow to scope its commands.

Now, when you run tbdflow commit from within frontend/, the tool behaves as you’d expect. It scopes its git add . command to only the frontend/ directory, ensuring your commit is focused and self-contained.

The status and sync commands are also monorepo-aware, giving you a clean, relevant view of your working directory by ignoring other projects when you’re at the root.

Conclusion

Trunk-Based Development and monorepos are a powerful combination for high-performing teams. By adding these new monorepo-aware features, tbdflow acts as an intelligent guardrail, helping you and your team get all the benefits of this workflow while avoiding its most common pitfalls.