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

# Git Worktrees

> Manage git worktrees for isolated work on parallel branches without switching directories

ChatCLI's `/worktree` command integrates with the **git worktrees** system to allow isolated work on multiple branches simultaneously. Instead of `git stash` and `git checkout`, you create separate worktrees and switch between them with a single command.

<Info>
  Git worktrees allow you to have multiple working copies of the same repository, each on a different branch, sharing the same `.git`. ChatCLI automates the creation, listing, and removal of these worktrees.
</Info>

***

## Concept

A **worktree** is a separate directory linked to the same Git repository but on a different branch. This allows:

```text theme={"system"}
my-project/                 (main)
my-project-feature-auth/    (feature/auth)  <- worktree
my-project-fix-bug-123/     (fix/bug-123)   <- worktree
```

They all share the same `.git`, commits, and history. You can work on each branch without interfering with the others.

***

## Commands

| Command                     | Description                                                |
| :-------------------------- | :--------------------------------------------------------- |
| `/worktree create <branch>` | Creates a new worktree for the specified branch            |
| `/worktree list`            | Lists all active worktrees for the repository              |
| `/worktree remove <branch>` | Removes an existing worktree                               |
| `/worktree status`          | Shows the current worktree status (branch, modified files) |

***

## Creating a Worktree

```bash theme={"system"}
/worktree create feature/auth
```

```text theme={"system"}
Worktree created:
  Branch: feature/auth
  Path:   /Users/dev/my-project-feature-auth/
  CWD changed to: /Users/dev/my-project-feature-auth/

Tip: Use /worktree list to see all active worktrees.
```

<Steps>
  <Step title="Automatic branch detection">
    If the branch already exists in the repository (local or remote), ChatCLI uses it directly. If it doesn't exist, it creates a new branch from the current HEAD.
  </Step>

  <Step title="Directory creation">
    The worktree directory is created alongside the repository root, with a name based on the branch (slashes replaced with hyphens).
  </Step>

  <Step title="CWD change">
    ChatCLI automatically changes the working directory to the new worktree, allowing subsequent commands to operate in the correct context.
  </Step>
</Steps>

<Tip>
  The branch can be an existing branch (local or remote) or a new branch. ChatCLI automatically detects which and acts accordingly.
</Tip>

***

## Listing Worktrees

```bash theme={"system"}
/worktree list
```

```text theme={"system"}
Active worktrees:
  * /Users/dev/my-project/                  main          (current)
    /Users/dev/my-project-feature-auth/     feature/auth  3 modified files
    /Users/dev/my-project-fix-bug-123/      fix/bug-123   clean
```

***

## Removing a Worktree

```bash theme={"system"}
/worktree remove feature/auth
```

```text theme={"system"}
Worktree removed:
  Branch: feature/auth
  Path:   /Users/dev/my-project-feature-auth/ (deleted)

Note: The branch 'feature/auth' was NOT deleted. Use git branch -d to remove it.
```

<Warning>
  Removing a worktree **deletes the directory** but **does not delete the branch**. Uncommitted changes will be lost. Always commit or stash before removing.
</Warning>

***

## Worktree Status

```bash theme={"system"}
/worktree status
```

```text theme={"system"}
Current worktree:
  Path:   /Users/dev/my-project-feature-auth/
  Branch: feature/auth
  Ahead:  2 commits (vs origin/feature/auth)
  Files:  3 modified, 1 untracked

  Modified:
    M  auth/handler.go
    M  auth/middleware.go
    M  auth/jwt.go
    ?  auth/refresh_token.go
```

***

## Typical Workflows

<Tabs>
  <Tab title="Parallel feature">
    Work on a feature without affecting the main branch:

    ```bash theme={"system"}
    # Create worktree for the feature
    /worktree create feature/auth

    # Work normally (CWD already changed)
    /coder Implement the JWT authentication module

    # Go back to the main worktree
    /worktree create main
    # (detects that main already exists and just changes CWD)
    ```
  </Tab>

  <Tab title="Urgent hotfix">
    Fix a bug without losing work in progress:

    ```bash theme={"system"}
    # You're working on feature/auth...
    # Urgent bug in production!

    /worktree create hotfix/fix-login

    # Fix the bug
    /coder Fix the login bug causing infinite redirect

    # Go back to the feature
    /worktree create feature/auth
    ```
  </Tab>

  <Tab title="PR review">
    Review a PR without leaving your branch:

    ```bash theme={"system"}
    # Create worktree for the PR branch
    /worktree create feature/new-api

    # Analyze the code
    /plan
    /agent Analyze the changes in this branch and identify potential issues
    # or, on a single line:
    # /plan Analyze the changes in this branch and identify potential issues

    # Remove when done
    /worktree remove feature/new-api
    ```
  </Tab>
</Tabs>

***

## Technical Details

### Directory Location

Worktrees are created **alongside** the repository root:

```text theme={"system"}
/Users/dev/
  my-project/                     <- original repository
  my-project-feature-auth/        <- worktree (branch: feature/auth)
  my-project-fix-bug-123/         <- worktree (branch: fix/bug-123)
```

The directory name is composed as `<repo-name>-<branch>`, where slashes (`/`) in the branch are replaced with hyphens (`-`).

### Automatic CWD Change

When creating or selecting a worktree, ChatCLI automatically changes the CWD. This ensures that:

* Agent/coder commands operate on the correct files
* File search (`search`, `tree`) reflects the correct branch
* Bootstrap files (SOUL.md, RULES.md) are detected correctly

### Compatibility

| Requirement | Details                                                |
| :---------- | :----------------------------------------------------- |
| Git         | >= 2.15.0 (worktree support)                           |
| Repository  | Must be a Git repository (non-bare)                    |
| Permissions | Write access to the parent directory of the repository |

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Sessions" icon="clock-rotate-left" href="/features/session-management">
    Combine worktrees with sessions for persistent context per branch.
  </Card>

  <Card title="Coder Mode" icon="code" href="/core-concepts/coder-mode">
    Use coder mode with worktrees for isolated engineering per branch.
  </Card>
</CardGroup>