> ## Documentation Index
> Fetch the complete documentation index at: https://graphite-58cc94ce.mintlify.site/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Work In Multiple Git Worktrees

> Learn how Graphite behaves across multiple Git worktrees and how to use the CLI across them.

<Note>
  This guide describes Graphite's multi-worktree behavior in `gt` version `1.8.4` and above.
</Note>

Graphite fully supports multiple Git worktrees.

Graphite normally does not modify branches checked out in another worktree. If a stack is split across worktrees, commands like `gt sync`, `gt get`, or `gt restack` need to be run separately from each relevant worktree. Use `gt create --onto <branch>` to create a new branch on top of a branch that is checked out elsewhere.

<Warning>
  **Exception for trunk branches:** Both `gt sync` and `gt get` may update local `trunk` even if `trunk` is checked out in another worktree.
</Warning>

## Understand the mental model

When you use Graphite across multiple Git worktrees, a few rules explain almost all of the behavior:

* A Git branch can only be checked out in one worktree at a time.

* Graphite respects that rule and avoids mutating branches that are checked out in another worktree.

* If a command would need to rewrite or check out a branch in another worktree, Graphite exits with an informative error and will not make changes in that worktree.

* `gt undo` history is per-worktree, so undo in one worktree targets commands that were run from that same worktree.

* `gt log` shows which worktree a branch is checked out in when multiple worktrees are present.

This model keeps Graphite predictable when you are working in multiple terminals, on multiple machines, or with multiple agents at the same time. For instance, an agent working in one worktree should not change file contents being used by another agent in another worktree.

## Recommended workflow

* Avoid simultaneously having more than one worktree on the same stack when possible.

* Use `gt log` to confirm where branches are checked out before syncing, restacking, or undoing.
  * When you have more than one worktree open for the same repository, `gt log` shows the worktree path next to branches that are checked out.
  * If you are not sure why a command will not touch a branch, run `gt log` first. It is the fastest way to confirm where that branch is currently checked out.

* Use `gt create --onto` when you want to start a new branch on top of a branch that is already checked out in another worktree.

* If one stack spans multiple worktrees, run `gt sync` or `gt restack` in each worktree as needed to sync or restack the entire stack.
  * For example, if one worktree has `feature-a` checked out and another has `feature-b` checked out on top of it, running `gt sync` from the `feature-a` worktree may still update local `trunk` and update `feature-a`, but it does not update `feature-b` in the other worktree.

* If Graphite tells you that a branch is checked out in another worktree, switch to that worktree or move that other worktree to a different branch before retrying.

## Know when Graphite stops instead of crossing worktrees

* `gt modify --into` stops if the target branch is checked out in another worktree.

* `gt undo` only undoes commands that were run from the current worktree, and it stops if the undo would need to modify or check out a branch that is checked out elsewhere.