Looking under the hood with a dry-run

One of the most valuable pieces of feedback I’ve had about tbdflow came as a simple question:

“What does this tool actually do if the user only knows tbdflow but not the workflow behind it?”

It’s a fair point. The aim of tbdflow has never been to act as a magic black box. It’s meant to be a friendly assistant with guardrails, helping developers adopt Trunk-Based Development while still showing them what’s going on under the hood.

That’s why I’ve added a new global flag: --dry-run.

Transparent and educational

When you add --dry-run to any tbdflow command, the tool won’t execute anything. Instead, it prints the Git commands it would have run, in the order they’d normally run.

• Transparency: No hidden steps, no magic. You see exactly what tbdflow is doing for a commit, complete, or sync command. That visibility hopefully builds trust and confidence.
• Learning: For anyone new to TBD, --dry-run doubles as a teaching tool. By exposing the Git workflow, it shows the “why” behind the automation and helps developers pick up best practices faster.

How to use it

For example, if you want to see what happens when creating a new feature branch, just add the --dry-run flag:

tbdflow --dry-run branch --type feat --name "new-thing"

This will show you every Git command tbdflow would run, step by step, without actually touching your repo.

The output looks like this:

[DRY RUN] Command would execute but no changes made
git rev-parse --is-inside-work-tree

--- Creating short-lived branch ---
[DRY RUN] Command would execute but no changes made
git status --porcelain

[DRY RUN] Command would execute but no changes made
git checkout main

[DRY RUN] Command would execute but no changes made
git pull --rebase --autostash

[DRY RUN] Command would execute but no changes made
git checkout -b feat/new-thing

[DRY RUN] Command would execute but no changes made
git push --set-upstream origin feat/new-thing

This way you get a safe, educational view of how the workflow plays out, without changing a thing.

Wrapping up

--dry-run is a small addition, but it captures the essence of what I want tbdflow to be: a helpful assistant that removes friction while staying transparent. It’s there to keep you in flow, but also to show you the ropes so you can deepen your understanding of Git and Trunk-Based Development.

Give it a try, and reveal the magic!