branchkit

Branchkit is a lightweight Bun-powered CLI that streamlines Git worktree collaboration. It provides a no-fuss workflow for spinning up feature worktrees and for wrapping up the work once it is ready to merge. The init command prints the newly created worktree path so you can wire it into your preferred editor or shell automation.

Prerequisites

• Git with worktree support (Git ≥ 2.37 recommended)
• Bun ≥ 1.2 (the CLI entry point uses a Bun shebang)

Installation

Install dependencies and link the CLI locally:

bun install
bun link

After linking you can invoke the CLI as branchkit or the shorter alias bk. If you prefer not to link, run the tool directly with bun run src/index.ts -- <command>.

Usage

branchkit <command> [flags]

Commands

• branchkit init <path> resolves the target relative to the current worktree, so the destination can live outside the primary repository tree as long as its parent directory exists and the folder is empty. Existing worktree paths are detected via git worktree list before creation.
• Branch names are derived from the requested path: navigation segments such as .. are stripped and remaining path pieces are normalized, producing clean branch identifiers for external directories.
• branchkit finish <path> now inspects git metadata from the selected worktree, so finishing and removing worktrees works even when the feature directory sits outside the main repository checkout.

Merge options

Create a brand-new Git worktree rooted at <path> (relative or absolute) and print the absolute path to the new worktree directory.

What happens under the hood:

• Validates that <path> resides inside your current Git repository.
• Ensures the parent directory exists and <path> is empty (or missing).
• Derives a new branch name from the relative path segments (e.g. features/new-api → features-new-api).
• Creates the worktree on that branch via git worktree add -b <branch> <path>.
• Outputs the worktree path so you can launch other tooling as desired.

finish <path> [target]

Prepare an existing worktree for merge into the target branch (defaults to the current branch of your terminal session when omitted).

Key steps performed:

• Resolves <path> to a registered worktree and ensures it belongs to your repo.
• Optionally auto-commits dirty changes (-c/--auto-commit-message).
• Verifies the worktree is clean before proceeding.
• Locates (or checks out) the target branch and merges in the feature branch, unless merging is skipped.
• Optionally removes the feature worktree and deletes the feature branch once the merge completes.

Flags for finish

Flag	Description
-s, --skip-merge	Switch to the target branch but print merge instructions instead of executing git merge.
-k, --keep-branch	Keep the feature branch after completing the merge (otherwise the branch is deleted).
-c <message>, --auto-commit-message <message>	Automatically stage and commit pending changes in the worktree before merging.

Example workflow

# Create a new worktree and capture its path
worktree_path=$(branchkit init worktrees/feature/login-form)

# ...do the work, commit as usual...

# Merge the worktree back into main once ready
branchkit finish worktrees/feature/login-form main --auto-commit-message "wip" --keep-branch

Development

• Show inline help:

  branchkit --help

• Run the CLI without linking:

  bun run src/index.ts -- init path/to/worktree

Feel free to adjust the workflow to match your team conventions; Branchkit is a thin helper around standard Git commands, so everything remains compatible with the usual tooling you already rely on.