@avelor/bonsai

Git worktree manager. Branch-centric, zero configuration.

Install

npm install -g @avelor/bonsai
bonsai install

Why

Git worktrees let you work on multiple branches simultaneously in separate directories — no stashing, no context switching. They're one of git's most underused features because the syntax is too hard to remember:

# raw git — you have to know the target path, the branch name, and the right flags
git worktree add ../myrepo-feature-auth feature/auth

# bonsai
bonsai feature/auth

Bonsai fixes that with a branch-centric interface. Just name the branch — bonsai figures out whether to create it, track it from remote, or open an existing worktree. Worktrees always live in .bonsai/ inside your repo.

Setup

Run once after install:

bonsai install
source ~/.zshrc   # or: source ~/.bashrc

This installs a shell function that enables automatic cd when opening worktrees.

Usage

bonsai feature/auth      # open worktree — creates it if needed
bonsai                   # list all worktrees
bonsai rm feature/auth   # remove a worktree
bonsai prune             # remove merged worktrees
bonsai root              # go back to repo root

How worktrees are organized

myrepo/
  .bonsai/
    feature-auth/        ← bonsai feature/auth
    hotfix-login/        ← bonsai hotfix/login
  src/
  package.json

.bonsai/ is added to .gitignore on first use.

Running from inside a worktree

Bonsai detects when you're in a worktree and operates from the repo root automatically:

cd .bonsai/feature-auth
bonsai payments/checkout   # creates .bonsai/payments-checkout from repo root
bonsai rm feature/auth     # removes and cds back to repo root
bonsai root                # cd back to repo root

Requirements

• git ≥ 2.5
• Node.js ≥ 18
• zsh or bash

MIT © Avelor