wt switch

Switch to a worktree. Creates one if needed.

Worktrees are addressed by branch name; paths are computed from a configurable template. Unlike git switch, this navigates between worktrees rather than changing branches in place.

wt switch feature-auth           # Switch to worktree
wt switch -                      # Previous worktree (like cd -)
wt switch --create new-feature   # Create new branch and worktree
wt switch --create hotfix --base production
wt switch pr:123                 # Switch to PR #123's branch

Creating a branch

The --create flag creates a new branch from the --base branch (defaults to default branch). Without --create, the branch must already exist.

Creating worktrees

If the branch already has a worktree, wt switch changes directories to it. Otherwise, it creates one, running hooks.

When creating a worktree, worktrunk:

1. Creates worktree at configured path
2. Switches to new directory
3. Runs post-create hooks (blocking)
4. Spawns post-start hooks (background)

wt switch feature                        # Existing branch → creates worktree
wt switch --create feature               # New branch and worktree
wt switch --create fix --base release    # New branch from release
wt switch --create temp --no-verify      # Skip hooks

Shortcuts

wt switch -                      # Back to previous
wt switch ^                      # Default branch worktree
wt switch --create fix --base=@  # Branch from current HEAD
wt switch pr:123                 # PR #123's branch

GitHub pull requests (experimental)

The pr:<number> syntax resolves the branch for a GitHub pull request. For same-repo PRs, it switches to the branch directly. For fork PRs, it fetches refs/pull/N/head and configures pushRemote to the fork URL.

wt switch pr:101                 # Checkout PR #101

Requires gh CLI to be installed and authenticated. The --create flag cannot be used with pr: syntax since the branch already exists.

Fork PRs: To push changes, use git push HEAD:<branch-name> where <branch-name> is the PR's head branch (e.g., feature-fix). The local branch is named <owner>/<branch> to avoid collisions, so plain git push won't work with default settings.

When wt switch fails

• Branch doesn't exist — Use --create, or check wt list --branches
• Path occupied — Another worktree is at the target path; switch to it or remove it
• Stale directory — Use --clobber to remove a non-worktree directory at the target path

To change which branch a worktree is on, use git switch inside that worktree.

See also

• wt select — Interactive worktree selection
• wt list — View all worktrees
• wt remove — Delete worktrees when done
• wt merge — Integrate changes back to the default branch

Command reference

wt switch - Switch to a worktree

Creates one if needed.

Usage: wt switch [OPTIONS] <BRANCH> [-- <EXECUTE_ARGS>...]

Arguments:
  <BRANCH>
          Branch name or shortcut

          Shortcuts: '^' (default branch), '-' (previous), '@' (current),
          'pr:{N}' (GitHub PR, experimental)

  [EXECUTE_ARGS]...
          Additional arguments for --execute command (after --)

          Arguments after -- are appended to the execute command. Each argument
          is expanded for templates, then POSIX shell-escaped.

Options:
  -c, --create
          Create a new branch

  -b, --base <BASE>
          Base branch

          Defaults to default branch.

  -x, --execute <EXECUTE>
          Command to run after switch

          Replaces the wt process with the command after switching, giving it
          full terminal control. Useful for launching editors, AI agents, or
          other interactive tools.

          Supports ]8;;@/hook.md#template-variables\hook template variables]8;;\ ({{ branch }}, {{ worktree_path }},
          etc.) and filters. {{ base }} and {{ base_worktree_path }} require
          --create.

          Especially useful with shell aliases:

            alias wsc='wt switch --create -x claude'
            wsc feature-branch -- 'Fix GH #322'

          Then wsc feature-branch creates the worktree and launches Claude Code.
          Arguments after -- are passed to the command, so wsc feature -- 'Fix
          GH #322' runs claude 'Fix GH #322', starting Claude with a prompt.

          Template example: -x 'code {{ worktree_path }}' opens VS Code at the
          worktree, -x 'tmux new -s {{ branch | sanitize }}' starts a tmux
          session named after the branch.

  -y, --yes
          Skip approval prompts

      --clobber
          Remove stale paths at target

      --no-verify
          Skip hooks

  -h, --help
          Print help (see a summary with '-h')

Global Options:
  -C <path>
          Working directory for this command

      --config <path>
          User config file path

  -v, --verbose...
          Show debug info (-v), or also write diagnostic report (-vv)