Getting Started

Birch is a CLI for managing git worktrees. It handles the full lifecycle — creating worktrees with memorable names, tracking their state, navigating between them, and cleaning up when you're done.

Install

npm install -g @matthamlin/birch

Or with bun:

bun add -g @matthamlin/birch

Once installed, birch is available via two aliases: birch and br.

Quick Start

1. Initialize

birch init

This creates a .birch/ directory in your repo with a state.json file for tracking worktrees, and adds .birch/ to your .gitignore.

2. Create a worktree

birch new

Birch generates a memorable compound name (e.g. swift-cedar) and creates a new git worktree with a matching branch. You can also provide a custom name:

birch new --name my-feature

3. Navigate to it

cd $(birch go swift-cedar)

The go command prints the absolute path to a worktree, making it easy to compose with cd.

4. Work on your changes

Your worktree is a full working copy of the repo on its own branch. Make changes, commit, push — same as any git workflow.

5. Clean up

birch remove swift-cedar

When you're done, remove the worktree. Birch handles both the git worktree removal and its own state cleanup.

Auto-initialization

You don't need to run birch init separately. Running birch new in a repo that hasn't been initialized will automatically set up birch with default settings.

Next Steps

• Browse all Commands
• Learn about Configuration for custom branch naming and storage
• Understand the Concepts behind name generation, state tracking, and pruning