Worktrees

Worktrees

Trellis treats each git worktree as a first-class development environment with isolated services, logs, and terminal sessions.

What are Worktrees?

Git worktrees allow you to have multiple working directories from a single repository. Each worktree can have a different branch checked out:

~/src/myapp/          # main branch
~/src/myapp-feature/  # feature branch (worktree)
~/src/myapp-hotfix/   # hotfix branch (worktree)

Trellis extends this by giving each worktree its own:

• Service instances (binaries from that worktree’s build)
• Terminal sessions
• Log buffers
• Workflow execution context

Worktree Discovery

Trellis automatically discovers worktrees:

{
  worktree: {
    discovery: {
      mode: "git"  // Use git worktree list
    }
  }
}

Discovery runs at startup.

Active Worktree

One worktree is “active” at a time. The active worktree:

• Has its services running
• Is shown by default in the UI

Workflows run in the context of the currently viewed worktree, not necessarily the active one.

Switch worktrees with:

trellis-ctl worktree activate feature-branch

This:

1. Stops services in the current worktree
2. Switches to the new worktree
3. Starts services with binaries from the new worktree

Worktree-Aware Configuration

Use template variables to make your config worktree-aware:

{
  services: [
    {
      name: "api"
      command: "{{.Worktree.Root}}/bin/api"
      watch_binary: "{{.Worktree.Binaries}}/api"
      env: {
        CONFIG_PATH: "{{.Worktree.Root}}/config"
      }
    }
  ]
}

Available Variables

Binary Path Configuration

Configure where binaries are located:

{
  worktree: {
    binaries: {
      path: "{{.Worktree.Root}}/bin"
    }
  }
}

Terminal Sessions

Each worktree gets its own tmux session. Terminal windows are created on demand from the worktree home page rather than being pre-configured. Windows and Claude sessions can be renamed from the worktree home page using the pencil icon next to each item.

Parallel Development

With worktrees, you can:

1. Work on multiple features simultaneously - Each worktree has its own services running its own binaries

2. Quick bug fixes - Create a worktree from main, fix the bug, deploy, delete the worktree

3. Code review - Check out a PR in a worktree, run the services, test it

4. AI-assisted development - Have Claude working in one worktree while you work in another

Worktree Events

Creating Worktrees

From the Web UI

The home page has a Create New Worktree form. Enter a branch name and Trellis will create both the git branch and worktree directory. Optionally check Switch to new worktree to activate it immediately.

New worktrees also get the agent skill file installed at .claude/skills/trellis/SKILL.md automatically (unless disabled via agent.install_skill), so Claude Code sessions in the worktree can drive trellis-ctl right away.

From the Command Line

# Create worktree with new branch
git worktree add ../myapp-feature -b feature-branch

# Create worktree from existing branch
git worktree add ../myapp-hotfix hotfix-branch

Trellis will discover the new worktree automatically.

Removing Worktrees

From the Web UI

Click the Remove button on the home page to delete a worktree. You’ll be asked whether to also delete the associated git branch. Trellis will remove the worktree directory, its binaries directory, and kill the tmux session.

You cannot remove the currently active worktree or the main project worktree.

From the Command Line

# Remove the worktree directory
git worktree remove ../myapp-feature

# Or delete and prune
rm -rf ../myapp-feature
git worktree prune