birch

Concepts

Name Generation

Birch generates memorable compound names by combining an adjective with a tree name. There are 50 adjectives and 50 tree names, giving 2,500 unique combinations.

Examples: swift-cedar, bold-maple, bright-pine, calm-birch, ancient-oak.

Names are generated using a Fisher-Yates shuffle for randomization, ensuring an even distribution. If all 2,500 combinations are exhausted (unlikely in practice), birch appends a numeric suffix.

You can always override the generated name with --name:

birch new --name my-feature

State Tracking

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

{
  "version": 1,
  "worktrees": {
    "swift-cedar": {
      "name": "swift-cedar",
      "branch": "swift-cedar",
      "path": "/Users/you/.birch/worktrees/my-project/swift-cedar",
      "createdAt": "2026-03-01T12:00:00.000Z",
      "lastAccessed": "2026-03-09T15:30:00.000Z"
    }
  }
}

The lastAccessed timestamp is updated whenever you use birch go to navigate to a worktree.

Pruning

birch prune runs two cleanup phases:

Phase 1: Stale References

Removes state entries whose worktree directories no longer exist on disk, and runs git worktree prune to clean up git's internal references.

Phase 2: Merged Branch Detection

Checks each worktree's branch to see if it has been merged into the default branch. Birch detects two merge strategies:

  • Regular merges — The branch's commits are reachable from the default branch.
  • Squash merges — The branch was squash-merged (using the Teddy Katz algorithm). This is common in GitHub PR workflows where "Squash and merge" is the default.

Worktrees with uncommitted changes are never pruned, even if their branch has been merged.

Git Integration

Birch wraps git operations using execFileSync with explicit argument arrays (no shell execution), which prevents command injection. The key git operations are:

  • git worktree add — Create new worktrees
  • git worktree remove — Remove worktrees
  • git worktree list --porcelain — List worktrees in machine-readable format
  • git worktree prune — Clean up stale references
  • git merge-base / git cherry-pick — Detect squash merges
  • git branch -d / git branch -D — Clean up branches

Branch Name Validation

Birch validates branch names according to git-check-ref-format rules:

  • No double dots (..)
  • No ASCII control characters or spaces
  • No colons, question marks, asterisks, or open brackets
  • Cannot begin or end with a dot, or end with .lock
  • Cannot contain consecutive slashes or end with a slash

Invalid names from custom branchName functions are caught and birch falls back to the default naming.

Filesystem Safety

Worktree names are sanitized for filesystem use:

  • Slashes are converted to dashes
  • Special characters are removed
  • Path traversal attempts (../) are blocked
  • Names are kept short and readable