tbdflow

tbdflow, a Trunk-Based Development CLI

A simple yet powerful command-line tool to streamline Git workflows, especially for teams working with Trunk-Based Development (TBD).

This CLI supports both the default commit-to-main workflow and the structured handling of short-lived branches for features, releases, and hotfixes.

Status & history

This project is the result of an iterative development journey. It began as an F# application (tbdflow-fs) which served as a fantastic learning exercise in functional programming.

The current and actively developed version is the Rust implementation (tbdflow-rs). It was ported to Rust to create a leaner, faster, and more portable single-binary executable, making it easier for others to use and contribute to. The F# version is no longer maintained but remains in the repository as a functional prototype.

Philosophy

This tool is built around a specific philosophy of Trunk-Based Development:

• Main is the default. The commit command is your everyday go-to. It automates pulling the latest changes, committing, and pushing directly to main, promoting small, frequent integrations.
• Branches are the exception. While feature, release, and hotfix branches are supported, they’re treated as short-lived exceptions and not the norm.
• Cleanup is automatic. The complete command enforces branch short-livedness by merging and automatically tagging (release/hotfix) and deleting completed branches, helping keep your repo tidy.
• Conventional Commits encouraged. Commit messages follow Conventional Commits for clarity and consistency.

Why not just use Git?

This CLI isn’t a replacement for Git. You’ll still reach for raw git when doing advanced work like rebasing, cherry-picking, or running git bisect.

This tool is as a workflow assistant, tbdflow encapsulates a repeatable, opinionated process to support your day-to-day development.

It offers three main benefits:

1. Consistency across the team Everyone follows the same steps for common tasks. Commits, branches, and releases are handled the same way every time, keeping your Git history clean and predictable.

2. Less to remember No need to recall the exact flags or sequences (like pull --rebase, merge --no-ff, or commit message formats). The CLI handles that, so you can stay focused on writing code.

3. It supports "the TBD way" This tool makes the preferred approach easy by providing a smooth, safe, and efficient path for 80% of everyday tasks. For the other 20%, you can always use Git directly.

Commands

1. commit

This is the primary command for daily work.

Commits staged changes using a Conventional Commits message. This command is context-aware:

• On main: It runs the full TBD workflow: pulls the latest changes with rebase, commits, and pushes.
• On any other branch: It simply commits and pushes, allowing you to save work-in-progress.

Usage:

tbdflow commit [options]

Options:

Example:

# A new feature
tbdflow commit -t "feat" -s "auth" -m "Add password reset endpoint"

# A bug fix with a breaking change
tbdflow commit -t "fix" -m "Correct user permission logic" -b
tbdflow commit -t "refactor" -m "Rename internal API" --breaking --breaking-description "The `getUser` function has been renamed to `fetchUser`."

# A bug fix with a new tag
tbdflow commit -t "fix" -m "Correct user permission logic" --tag "v1.1.1"

2.feature / release / hotfix

Creates a new, short-lived branch from the latest version of `main.

Usage:

# For features or hotfixes
tbdflow <feature|hotfix> --name <branch-name>

# For releases
tbdflow release --version <version-number> [options]

Options (release):

Examples:

# Create a feature branch
tbdflow feature -n "user-profile-page"

# Create a release branch
tbdflow release -v "2.1.0"

# Create a release branch from a specific commit
tbdflow release -v "2.1.0" -f "39b68b5"

# Create a hotfix branch
tbdflow hotfix -n "critical-auth-bug"

3. complete

Merges a short-lived branch back into main, then deletes the local and remote copies of the branch.

Automatic Tagging:

• When completing a release branch, a tag (e.g., v1.2.0) is automatically created and pushed.
• When completing a hotfix branch, a tag (e.g., hotfix/name-of-fix) is automatically created and pushed.

Usage:

tbdflow complete --type <branch-type> --name <branch-name>

Options:

Examples:

# Complete a feature branch
tbdflow complete -t "feature" -n "user-profile-page"

# Complete a release branch (this will be tagged v2.1.0)
tbdflow complete -t "release" -n "2.1.0"

4. Misc commands

tbdflow has a couple of commands that can be beneficial to use but they are not part of the workflow, they are for inspecting the state of the repository.

Examples:

# Does a pull, shows latest changes to main branch, and warns about stale branches.
tbdflow sync

# Checks the status of the working dir
tbdflow status

# Shows the current branch name
tbdflow current-branch

# Explicitly checks for local branches older than one day.
tbdflow check-branches