npm package: @matthamlin/birch
Description: Git Worktree Manager CLI
Author: Matt Hamlin
Latest version: 0.0.1

# `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

```bash
bun add -g @matthamlin/birch
```

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

## Quick Start

```bash
# 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`.

```bash
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.

```bash
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.

```bash
birch list
```

### `birch go <name>`

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

```bash
cd $(birch go swift-cedar)
```

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

### `birch status [name]`

Show git status for worktrees.

```bash
# 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.

```bash
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.

```bash
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.

```bash
birch cleanup [options]
```

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

### `birch help`

Show usage information for all commands and options.

```bash
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.

```javascript
// .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`](https://github.com/matthamlin/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](https://oxc.rs/docs/guide/usage/linter.html). 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.