> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wit.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Worktrees

> Work on multiple branches simultaneously

Worktrees let you have multiple working directories for the same repository, each on a different branch.

## Overview

Instead of:

* Stashing changes
* Switching branches
* Switching back
* Restoring stash

You can:

* Create a worktree on another branch
* Work on both simultaneously
* No context switching overhead

## Commands

### Add Worktree

```bash theme={null}
wit worktree add <path> <branch>
```

**Examples:**

```bash theme={null}
# Create worktree for existing branch
wit worktree add ../feature-worktree feature-branch

# Create worktree with new branch
wit worktree add ../hotfix-worktree -b hotfix-123
```

### List Worktrees

```bash theme={null}
wit worktree list
```

Output:

```
/home/user/project         a1b2c3d [main]
/home/user/feature-wt      e5f6g7h [feature-branch]
/home/user/hotfix-wt       i9j0k1l [hotfix-123]
```

### Remove Worktree

```bash theme={null}
wit worktree remove <path>
```

**Example:**

```bash theme={null}
wit worktree remove ../feature-worktree
```

### Prune Stale Entries

```bash theme={null}
wit worktree prune
```

Removes worktree entries where the directory no longer exists.

## Workflow Example

### Scenario: Working on Feature, Need to Hotfix

You're deep in feature development when a critical bug is reported.

**Without worktrees:**

```bash theme={null}
wit stash
wit switch main
# fix bug...
wit commit -m "Hotfix"
wit switch feature
wit stash pop
```

**With worktrees:**

```bash theme={null}
# Create a worktree for the hotfix
wit worktree add ../hotfix main

# Work on hotfix in separate directory
cd ../hotfix
# fix bug...
wit commit -m "Hotfix"
wit push

# Back to feature (no context switch!)
cd ../project
# Continue exactly where you left off

# Clean up
wit worktree remove ../hotfix
```

## Directory Structure

```
~/code/
├── my-project/              # Main worktree (main branch)
│   ├── .wit/              # The actual repository
│   ├── src/
│   └── package.json
├── my-project-feature/      # Linked worktree (feature branch)
│   ├── .wit -> link       # Links to main .wit
│   ├── src/
│   └── package.json
└── my-project-hotfix/       # Linked worktree (hotfix branch)
    ├── .wit -> link
    ├── src/
    └── package.json
```

## Use Cases

### Parallel Development

```bash theme={null}
# Work on two features simultaneously
wit worktree add ../feature-a feature-a
wit worktree add ../feature-b feature-b

# Now you have three directories:
# - Main repo (can stay on main)
# - feature-a worktree
# - feature-b worktree
```

### Testing Branches

```bash theme={null}
# Create worktree to test a PR
wit worktree add ../pr-123 origin/pr-123

# Test in that directory
cd ../pr-123
npm install
npm test

# Clean up
cd ../project
wit worktree remove ../pr-123
```

### Long-running Operations

```bash theme={null}
# Run a long build in a worktree
wit worktree add ../build-wt main
cd ../build-wt
npm run build:production &

# Continue working in main worktree
cd ../project
# Edit files, make commits, etc.
```

### Code Review

```bash theme={null}
# Review someone's branch
wit worktree add ../review origin/teammate-feature

# Open in IDE, review, then clean up
wit worktree remove ../review
```

## Best Practices

<Tip>
  **Use consistent naming**

  Name worktrees clearly:

  ```bash theme={null}
  wit worktree add ../project-feature feature-x
  wit worktree add ../project-hotfix hotfix-123
  ```
</Tip>

<Tip>
  **Clean up when done**

  Don't leave worktrees lying around:

  ```bash theme={null}
  wit worktree list
  wit worktree remove ../old-worktree
  ```
</Tip>

<Tip>
  **Share node\_modules (optional)**

  For JavaScript projects, symlink node\_modules:

  ```bash theme={null}
  cd ../new-worktree
  ln -s ../main-project/node_modules node_modules
  ```
</Tip>

## Limitations

* Each branch can only be checked out in one worktree
* The main worktree cannot be removed
* All worktrees share the same `.wit` directory

## Worktrees vs Other Approaches

| Approach       | Pros                             | Cons                       |
| -------------- | -------------------------------- | -------------------------- |
| **Worktrees**  | No context switch, parallel work | Disk space                 |
| **Stashing**   | No extra directories             | Manual, error-prone        |
| **Clone**      | Complete isolation               | Separate repo, sync issues |
| **Auto-stash** | Automatic                        | Still switches context     |

## Troubleshooting

<AccordionGroup>
  <Accordion title="Branch already checked out">
    A branch can only be in one worktree:

    ```
    fatal: 'feature' is already checked out at '/path/to/worktree'
    ```

    Remove the existing worktree or use a different branch.
  </Accordion>

  <Accordion title="Worktree directory exists">
    Remove or choose a different path:

    ```bash theme={null}
    rm -rf ../old-worktree
    wit worktree add ../old-worktree branch
    ```
  </Accordion>

  <Accordion title="Stale worktree entries">
    If you deleted a worktree directory manually:

    ```bash theme={null}
    wit worktree prune
    ```
  </Accordion>
</AccordionGroup>