ev worktree

Usage

ev worktree add <name> [branch] [--env <env>]
ev worktree remove <name>
ev worktree list

Description

ev worktree wraps git worktree with automatic secret sync. When you create a worktree, ev pull runs inside it automatically so secrets are ready without any extra steps.

Worktrees are stored under .worktrees/ by default (configurable in ev.yaml). This keeps them co-located with the repo and out of your main working tree.

Subcommands

add

ev worktree add <name> [branch] [--env <env>]

Creates a git worktree at .worktrees/<name>, then pulls secrets into it.

Examples:

# New branch + pull dev secrets (default_env)
ev worktree add my-feature
 
# Check out an existing branch
ev worktree add auth-rewrite origin/auth-rewrite
 
# Pull staging secrets instead of dev
ev worktree add my-feature --env staging

After creation, your shell automatically cds into the new worktree (requires shell setup).

remove

ev worktree remove <name>

Removes the worktree at .worktrees/<name>. Delegates to git worktree remove — no extra cleanup needed since .env files are gitignored.

ev worktree remove my-feature

list

ev worktree list

Lists all worktrees. Pass-through to git worktree list.

Shell Setup

To get automatic cd into the new worktree after ev worktree add, run once:

ev completions install

This writes a shell function to your ~/.zshrc or ~/.bashrc (auto-detected from $SHELL). The function intercepts ev worktree add, runs it normally, then cds into the result. It's idempotent — safe to re-run after updates.

To specify shell or file explicitly:

ev completions install --shell zsh
ev completions install --shell bash
ev completions install --file ~/.config/zsh/.zshrc

After installing, reload your shell:

source ~/.zshrc   # or ~/.bashrc

Configuration

Control where worktrees are created via ev.yaml:

worktrees:
  dir: .worktrees   # default — omit this entire block to use the default

The directory is relative to the repo root (where ev.yaml lives). On first ev worktree add, the directory is added to .gitignore automatically.

Monorepo Behavior

In a monorepo with apps: configured, ev worktree add pulls secrets for all apps into the new worktree:

.worktrees/my-feature/
├── packages/
│   ├── api/          ← .env written here
│   ├── web/          ← .env written here
│   └── worker/       ← .env written here
└── ev.yaml

This mirrors what ev pull does when run from the repo root.

AI Agents & Worktrees

AI coding tools — Claude, Cursor, GitHub Copilot Workspace — increasingly use git worktrees to work on multiple branches in parallel without losing context. ev worktree add makes this seamless: the agent gets a fully-configured environment with secrets in one command, no manual secret setup required.

# Spin up an isolated environment for an AI agent in one step
ev worktree add agent-task-123
# → worktree created, secrets pulled, ready to go

Each worktree is completely isolated — changes to .env in one worktree don't affect any other.

If Pull Fails

If the secret pull fails (network issue, not logged in), the worktree is left in place and a retry command is printed:

⚠ Pull failed: unauthorized
  Retry with: cd .worktrees/my-feature && ev pull

The worktree itself is still usable — secrets just need to be pulled manually.