Navigate Branches and Worktrees

Switch between branches and navigate stacks seamlessly.

Overview

Navigation commands let you move between branches and worktrees without manually cd-ing to directories. They automatically allocate worktrees when needed—either creating a new one or using an available slot—so you can focus on the code rather than filesystem management.

Navigate by Branch Name

erk br co (alias for erk branch checkout) is the most common navigation command. Give it a branch name and it switches you to that branch's worktree:

erk br co P1234-some-feature

This command handles several scenarios automatically:

Branch is checked out in a worktree: Switches to it
Branch exists but is not checked out in a worktree: Allocates one, then switches
Branch only exists on remote: Creates a tracking branch and allocates a worktree

Use this when you know the branch name and want to work on it.

Navigate by Worktree Name

erk wt co (alias for erk wt checkout) navigates by worktree name rather than branch name:

erk wt co some-worktree

The special keyword root always takes you to the original clone location.

Checkout a PR

erk pr co checks out a pull request by number or URL:

erk pr co 123
erk pr co https://github.com/owner/repo/pull/123

This fetches the PR's branch, allocates a worktree if needed, and switches to it. Use this when reviewing or iterating on someone else's PR.

Navigate Stacks

When using Graphite for stacked PRs, erk up and erk down move through the stack:

erk up      # Move toward leaves (away from trunk)
erk down    # Move toward trunk (toward parent)

Stack terminology:

Up = toward children/leaves (away from main)
Down = toward parent (toward main)

main
 └── feature-base (erk down from here)
      └── feature-part-1 (current)
           └── feature-part-2 (erk up goes here)

After landing a PR, use --delete-current to clean up:

erk down --delete-current    # Land, then move down and delete current worktree

Both commands automatically allocate worktrees for stack branches that don't have them yet.

Move Current Branch to Another Worktree

Sometimes you create a branch in the root worktree (or any worktree you want to keep on a different branch) and decide you'd rather work on it in a dedicated worktree:

erk wt create --from-current-branch

This allocates a new worktree for your current branch and switches to it. The original worktree returns to whatever branch it had before (typically master or main).

Choosing the Right Command

Scenario	Command
Know the branch name	`erk br co <branch>`
Know the worktree name	`erk wt co <worktree>`
Return to root repository	`erk wt co root`
Review a PR	`erk pr co <number>`
Move up the stack	`erk up`
Move down the stack	`erk down`
Land PR and navigate up	`erk pr land --up`
Move current branch to new worktree	`erk wt create --from-current-branch`