Worktrees — Multiple Workspaces

How to have several branches open at the same time in separate folders, so you can switch between tasks instantly.

What is a worktree?

A worktree is like having multiple desks in your office, each with a different document open. Normally with Git, you have one desk (one folder). If you want to look at a different branch, you have to close your current work, switch branches, and reopen everything. With worktrees, you just walk over to another desk where that branch is already open and ready.

A git worktree is a separate folder on your computer that is linked to the same repository but has a different branch checked out. You can have as many worktrees as you want, each showing a different branch simultaneously.

Why use worktrees?

No context switching

You are working on a feature but need to check something on the main branch. Instead of saving, switching, checking, switching back, and reopening — you just open the other folder.

Parallel development

Two AI agents (or two developers) can work on different features at the same time, each in their own worktree, without interfering with each other.

Quick comparisons

Want to compare how the app looks on the current branch versus the develop branch? Both are available simultaneously in separate folders.

Safe experiments

Spin up a worktree to try a wild experiment. If it fails, delete the folder. Your main workspace is untouched.

How worktrees relate to branches

Key rule: Each worktree must have a different branch checked out. You cannot have two worktrees both on develop. Think of it this way: each desk has a different document, never the same one twice.
flowchart TB subgraph repo["Git Repository (single history)"] direction TB H["Shared commit history"] end subgraph wt1["Main Workspace"] direction TB F1["Folder: /projects/mesh-hub/"] B1["Branch: develop"] end subgraph wt2["Worktree 1"] direction TB F2["Folder: .worktrees/feature-v0.2/"] B2["Branch: feature/mesh-hub-v0.2"] end subgraph wt3["Worktree 2"] direction TB F3["Folder: .worktrees/physics/"] B3["Branch: feature/physics-controls"] end repo --> wt1 repo --> wt2 repo --> wt3 style repo fill:#0f1425,stroke:#00e5ff,color:#e0e6f0 style wt1 fill:#1e2a4a,stroke:#00e676,color:#e0e6f0 style wt2 fill:#1e2a4a,stroke:#ffab40,color:#e0e6f0 style wt3 fill:#1e2a4a,stroke:#448aff,color:#e0e6f0 style H fill:#141a2e,stroke:#00e5ff,color:#e0e6f0 style F1 fill:#141a2e,stroke:#00e676,color:#e0e6f0 style B1 fill:#141a2e,stroke:#00e676,color:#e0e6f0 style F2 fill:#141a2e,stroke:#ffab40,color:#e0e6f0 style B2 fill:#141a2e,stroke:#ffab40,color:#e0e6f0 style F3 fill:#141a2e,stroke:#448aff,color:#e0e6f0 style B3 fill:#141a2e,stroke:#448aff,color:#e0e6f0

One repository, three workspaces. All share the same history but each has a different branch checked out in its own folder.

The folder structure

At BACON-AI, worktrees live inside a .worktrees/ folder within the project. Here is what the Mesh Hub project looks like on disk: 

bacon-ai-local-ai-file-chat/          ← Main workspace (develop branch)
  ├── client/
  ├── server/
  ├── package.json
  ├── .worktrees/                       ← Worktrees folder
  │   ├── feature-mesh-hub-v0.2/        ← Worktree 1 (feature/mesh-hub-v0.2)
  │   │   ├── client/
  │   │   ├── server/
  │   │   └── package.json
  │   └── feature-physics-controls/     ← Worktree 2 (feature/physics-controls)
  │       ├── client/
  │       ├── server/
  │       └── package.json
  └── .git/                             ← Shared repository data
The .worktrees/ folder is listed in .gitignore, meaning it is not tracked by Git itself. Worktrees are a local convenience — they exist on your machine but are not uploaded to GitHub.

The lifecycle of a worktree

flowchart LR A["Need to work\non a feature"] --> B["Create worktree\n+ branch"] B --> C["Work in the\nworktree folder"] C --> D["Commit and\npush changes"] D --> E["Open a PR\nfor review"] E --> F["Merge the\nbranch"] F --> G["Delete the\nworktree"] style A fill:#1e2a4a,stroke:#00e5ff,color:#e0e6f0 style B fill:#1e2a4a,stroke:#00e5ff,color:#e0e6f0 style C fill:#1e2a4a,stroke:#00e5ff,color:#e0e6f0 style D fill:#1e2a4a,stroke:#00e5ff,color:#e0e6f0 style E fill:#1e2a4a,stroke:#00e5ff,color:#e0e6f0 style F fill:#1e2a4a,stroke:#00e676,color:#e0e6f0 style G fill:#1e2a4a,stroke:#8892a8,color:#e0e6f0

Worktrees are temporary workspaces. Once the feature is merged, the worktree folder is removed to keep things tidy.

Worktrees vs. branches — what is the difference?

Concept What it is Analogy
Branch A line of development in the project history A chapter you are rewriting
Worktree A folder on your computer where a branch is checked out A desk where that chapter is open

You can have a branch without a worktree (it exists in history but is not currently open anywhere). But you cannot have a worktree without a branch — every desk must have a document on it.

When BACON-AI uses worktrees

BACON-AI runs multiple AI agents simultaneously. Imagine three writers working on the same book at the same time. Each writer sits at their own desk with their own chapter open. They all share the same bookshelf (repository) but nobody is fighting over the same piece of paper. That is worktrees in action.

Common scenarios:

  • The orchestrator agent works on develop in the main workspace
  • A feature agent works on feature/mesh-hub-v0.2 in a worktree
  • A third agent tests feature/physics-controls in another worktree

Key takeaways

Remember:
  • A worktree is a separate folder with a different branch open.
  • Worktrees let you work on multiple things at once without switching back and forth.
  • Each worktree has its own branch — no duplicates allowed.
  • Worktrees are temporary. Delete them when the feature is done.