Configuration

Birch supports an optional configuration file at .birch/birch.config.mjs for customizing behavior. This file is generated automatically during birch init.

Example Config

// .birch/birch.config.mjs
export let config = {
  branchName(context) {
    return `feature/${context.worktreeName}`;
  },

  worktreeStorage: "root",
};

`branchName(context)`

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

Context Object

Property	Type	Description
`worktreeName`	`string`	The generated or user-provided worktree name
`baseBranch`	`string`	The branch being branched from
`existingWorktrees`	`string[]`	Array of current worktree names
`existingBranches`	`string[]`	Array of all existing branch names

Examples

Prefix with a convention:

branchName(context) {
  return `feature/${context.worktreeName}`;
}

Include the base branch:

branchName(context) {
  return `${context.baseBranch}/${context.worktreeName}`;
}

If the function returns an invalid git branch name or throws an error, birch falls back to the default naming (using the worktree name directly as the branch name).

`worktreeStorage`

Controls where worktrees are stored on disk.

Value	Description
`"root"`	`~/.birch/worktrees/<repo-key>/` in your home directory (default)
`"local"`	`.birch/worktrees/` inside the repository

Root Storage (default)

Worktrees are stored in a centralized location under your home directory. The repo key is a stable hash derived from the repository name and path, so different repos don't collide.

~/.birch/worktrees/
  my-project-a1b2c3d4/
    swift-cedar/
    bold-maple/

This keeps your repo directory clean and avoids accidentally committing worktree files.

Local Storage

Worktrees are stored inside the repo's .birch/worktrees/ directory. This is useful if you want worktrees co-located with the project, but the directory is already in .gitignore.

.birch/
  state.json
  birch.config.mjs
  worktrees/
    swift-cedar/
    bold-maple/

Init Options

You can also set the storage mode during initialization:

birch init --root   # Use root storage (default)
birch init --local  # Use local storage

The setting is persisted in your birch.config.mjs.