Skip to main content
This guide describes Graphite’s multi-worktree behavior in gt version 1.8.4 and above.
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.
Exception for trunk branches: Both gt sync and gt get may update local trunk even if trunk is checked out in another worktree.

​
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 instead of changing that worktree behind your back.
  • 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; one agent working in one worktree can’t suddenly change file contents being used by another agent in another worktree.
  • 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.