Skip to Content
WorkflowWorktrees

Worktrees

Work on multiple branches at the same time without stashing or switching.

Overview

Worktrees are a built-in Git feature (git worktree). They let you check out multiple branches simultaneously, each in its own directory, no stashing, no context-switching.

Blueberry enhances the experience by wrapping the underlying commands in a visual UI so you can create, switch, and remove worktrees without touching the terminal. Everything maps directly to standard Git operations, so your worktrees work the same way whether you manage them from Blueberry or the command line.

Each worktree appears as a numbered pill (1, 2, 3
) in the header bar. Click a pill to switch to that worktree instantly. Your editor, terminal, and preview all update to reflect the new branch. You can have up to 9 worktrees open at once.

Creating a Worktree

Press Ctrl+Shift+N or open the Command Bar (Cmd+P) and search for “New Worktree”.

In the dialog:

  1. Start point: choose which branch to base it on (defaults to your repository’s default branch).
  2. Branch name: enter a name for the new branch.
  3. Copy environment files: if .env files are found in your project root (.env, .env.local, .env.development, etc.), a checkbox lets you copy them to the new worktree automatically. This is checked by default.

Blueberry creates a sibling directory named <project>-<branch> and opens it as a new worktree. A new numbered pill appears in the header bar.

If your project has a .blueberry/startup.json, Blueberry offers to run the setup commands (like npm install) automatically after the worktree is created. This gets the new worktree ready to go without manual steps.

Switching Worktrees

You have several ways to switch between worktrees:

  • Header pills: click any numbered pill in the header bar. Hover over a pill to see its branch name.
  • Keyboard shortcuts: press Ctrl+Shift+1 through Ctrl+Shift+9 to jump directly to a worktree by number.
  • Command Bar: press Cmd+P, search for “Change Worktree”, then pick from the list.

Removing a Worktree

Hover over a worktree pill in the header bar and long-hover to reveal the X button, or use the Command Bar to search “Change Worktree” and select the remove action.

When removing a worktree, Blueberry walks you through a few checks:

  1. Uncommitted changes: if the worktree has uncommitted changes, you’ll be prompted to either commit them (with a customizable message) or discard them before proceeding.
  2. New environment variables: if the worktree’s .env files contain keys that don’t exist in the main project, Blueberry shows them and offers to copy them back. You can copy the new variables to the main project or skip this step.
  3. Confirm removal: choose between:
    • Remove: deletes the worktree directory but keeps the branch.
    • Remove & Delete Branch: deletes both the worktree directory and the branch.

Finishing Up with a Worktree

When you’re done with a worktree, you’ll want to get your changes back into the main branch:

  1. Commit your work: make sure all changes in the worktree branch are committed.
  2. Push the branch: push to remote so you can open a pull request, or merge locally.
  3. Merge into main: use your normal merge workflow (PR, git merge, or git rebase) from the main worktree.
  4. Remove the worktree: once merged, remove the worktree using the header pill (long-hover for the X) or the Command Bar. Choose Remove & Delete Branch if the branch is fully merged and no longer needed.

Since each worktree is just a branch checked out in its own directory, your standard Git workflow applies. There’s nothing special to do beyond treating it like any other branch.

Environment Files

Blueberry handles .env files specially in worktrees since they’re typically gitignored and wouldn’t transfer between branches:

  • On create: detected .env files (.env, .env.local, .env.development, etc.) are optionally copied from the main project to the new worktree.
  • On remove: Blueberry checks if the worktree added new environment variables that the main project doesn’t have. If found, it offers to copy them back before the worktree is deleted.

This prevents losing API keys or configuration that were added during development in a worktree.

Command Center Integration

The Command Bar (Cmd+P) has full worktree support. Search for “Change Worktree” to see a list of all your worktrees with options to switch to or remove each one.

Working with AI

Blueberry’s MCP context (blueberry_get_context) automatically exposes your worktree information to Claude. This means Claude knows which worktrees exist, which one is active, and can factor that into its suggestions.

Tips

  • Keep worktrees focused. Use one worktree per task: a feature branch, a bug fix, a review. This keeps your mental context clean.
  • Install dependencies in new worktrees. Each worktree is a separate directory, so dependencies aren’t shared. Run your project’s install command before starting work (e.g. npm install, pip install -r requirements.txt, bundle install, cargo build). If you switch to a worktree and things look broken, a missing install is usually the reason.
  • Use keyboard shortcuts. Ctrl+Shift+1 through Ctrl+Shift+9 make switching nearly instant once you build muscle memory.
  • External changes are detected. If you create or remove worktrees from the terminal with git worktree add or git worktree remove, Blueberry picks up the changes automatically.
  • Only the main project shows in the project picker. Worktree directories are hidden to keep your project list tidy.

Keyboard Shortcuts

ActionShortcut
Create new worktreeCtrl+Shift+N
Switch to worktree 1-9Ctrl+Shift+1 - Ctrl+Shift+9
Open Command BarCmd+P
Last updated on
Command BarSaved Setups