wt switch

Change directory to a worktree, creating one if needed. Creating a worktree runs hooks.

Worktrees are addressed by branch name — each worktree has exactly one branch, and the path is derived automatically.

Examples

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

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.

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

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

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

Arguments:
  <BRANCH>
          Branch name

          Shortcuts: '^' (default branch), '-' (previous), '@' (current)

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

          Arguments after -- are appended to the execute command. Each argument
          is POSIX shell-escaped before appending.

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.

          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.

  -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 commands and debug info