birch

A Git worktree manager CLI that simplifies creating, tracking, and managing git worktrees. Birch automates the lifecycle of worktrees with memorable auto-generated names, state tracking, and optional custom configuration.

Install

bun add -g @matthamlin/birch

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

Quick Start

# Initialize birch in your repo
birch init

# Create a new worktree (auto-generates a name like "swift-cedar")
birch new

# List all worktrees
birch list

# Navigate to a worktree
cd $(birch go swift-cedar)

# Remove a worktree when done
birch remove swift-cedar

Commands

birch init

Initialize birch in the current repository. Creates a .birch/ directory with state.json for tracking worktrees, and adds .birch/ to .gitignore.

birch init [options]

| Option | Description | | --------- | ------------------------------------------------------------------------------------ | | --local | Store worktrees in .birch/worktrees/ within the repo | | --root | Store worktrees in ~/.birch/worktrees/<repo-key>/ in your home directory (default) |

birch new

Create a new worktree. Automatically initializes birch if it hasn't been set up yet.

birch new [options]

| Option | Description | | ----------------- | --------------------------------------------------------------------------------- | | --name <name> | Use a custom worktree name instead of an auto-generated one | | --base <branch> | Base the new branch off a specific branch (defaults to the repo's default branch) |

When no --name is provided, birch generates a memorable compound name by combining an adjective with a tree name (e.g. funky-oak, swift-cedar, bright-maple). There are 2,500 unique combinations available.

birch list

List all tracked worktrees with their name, branch, and path.

birch list

birch go <name>

Print the absolute path to a worktree. Designed to compose with shell commands for navigation.

cd $(birch go swift-cedar)

Also updates the worktree's "last accessed" timestamp.

birch status [name]

Show git status for worktrees.

# Status for all worktrees
birch status

# Status for a specific worktree
birch status swift-cedar

birch remove <name>

Remove a worktree and clean up its state tracking entry.

birch remove <name> [options]

| Option | Description | | --------------- | ------------------------------------------------------------- | | --force, -F | Skip the confirmation prompt and force-remove dirty worktrees |

birch prune

Clean up stale worktree references and merged branches.

birch prune

Prune operates in two phases:

1. Stale cleanup — Runs git worktree prune and removes any state entries whose paths no longer exist on disk.
2. Merged branch cleanup — Detects branches that have been merged into the default branch (via regular merge or squash merge) and removes their worktrees and branches. Worktrees with uncommitted changes are skipped.

birch cleanup

Remove all birch-managed worktrees and the .birch/ directory. This is a destructive operation that defaults to declining if no confirmation is provided.

birch cleanup [options]

| Option | Description | | ----------- | ---------------------------------------------------- | | --confirm | Skip the confirmation prompt and proceed immediately |

birch help

Show usage information for all commands and options.

birch help
birch --help
birch -h

birch --version

Print the current version.

Configuration

Birch supports an optional configuration file at .birch/birch.config.mjs for customizing behavior.

// .birch/birch.config.mjs
export let config = {
  // Custom branch naming function
  branchName(context) {
    // context: { worktreeName, baseBranch, existingWorktrees, existingBranches }
    return `feature/${context.worktreeName}`;
  },

  // Worktree storage location: "root" (default) or "local"
  worktreeStorage: "root",
};

branchName(context)

A function that receives a context object and returns a custom branch name string. The context includes:

• worktreeName - the generated or user-provided worktree name
• baseBranch - the branch being branched from
• existingWorktrees - array of current worktree names
• existingBranches - array of all existing branch names

If the function returns an invalid branch name or throws, birch falls back to the default naming.

worktreeStorage

Controls where worktrees are stored on disk:

• "root" (default) - ~/.birch/worktrees/<repo-key>/ in your home directory, using a stable key derived from the repo name and path
• "local" - .birch/worktrees/ inside the repository

State Tracking

Birch maintains a state.json file in .birch/ that tracks metadata for each worktree:

• Name and branch
• Absolute path on disk
• Creation timestamp
• Last accessed timestamp (updated by birch go)

Contributing

Building

This library uses hohoro and TypeScript to build the source code and generate types.

To build the library, run bun run build from the root, or from this workspace.

Code Quality

Type Checking: Run bun run type-check from the root or from this workspace.

Linting: Uses oxlint. Run bun run lint from the root or from this workspace.

Tests: Uses Bun's built-in test runner. Run bun run test from the root or from this workspace.

Publishing

To publish the library, run bun run pub from the workspace root. This will prompt you to login to npm and publish the package.