Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

docs(switch): trim upstream tracking, add missing hooks, combine PR/MR sections (#1521)

worktrunk-botdf54d28c3aca
diff --git a/README.md b/README.md
index 23c7e626e..caa268f60 100644
--- a/README.md
+++ b/README.md
@@ -88,7 +88,7 @@ git branch -d feat</pre></td>
- **[Interactive picker](https://worktrunk.dev/switch/#interactive-picker)** — browse worktrees with live diff and log previews
- **[Copy build caches](https://worktrunk.dev/step/)** — skip cold starts by sharing `target/`, `node_modules/`, etc between worktrees
- **[`wt list --full`](https://worktrunk.dev/list/#full-mode)** — [CI status](https://worktrunk.dev/list/#ci-status) and [AI-generated summaries](https://worktrunk.dev/list/#llm-summaries) per branch
-- **[PR checkout](https://worktrunk.dev/switch/#github-pull-requests)** — `wt switch pr:123` to jump straight to a PR's branch
+- **[PR checkout](https://worktrunk.dev/switch/#pull-requests-and-merge-requests)** — `wt switch pr:123` to jump straight to a PR's branch
- **[Dev server per worktree](https://worktrunk.dev/hook/#dev-servers)** — `hash_port` template filter gives each worktree a unique port
- ...and **[lots more](#next-steps)**
diff --git a/docs/content/switch.md b/docs/content/switch.md
index 9778c5440..b290a2fd5 100644
--- a/docs/content/switch.md
+++ b/docs/content/switch.md
@@ -32,11 +32,7 @@ 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.
-
-**Upstream tracking:** Branches created with `--create` have no upstream tracking configured. This prevents accidental pushes to the wrong branch — for example, `--base origin/main` would otherwise make `git push` target `main`. Use `git push -u origin <branch>` to set up tracking as needed.
-
-Without `--create`, switching to a remote branch (e.g., `wt switch feature` when only `origin/feature` exists) creates a local branch tracking the remote — this is the standard git behavior and is preserved.
+The `--create` flag creates a new branch from the `--base` branch (defaults to default branch). Without `--create`, the branch must already exist. Switching to a remote branch (e.g., `wt switch feature` when only `origin/feature` exists) creates a local tracking branch.
## Creating worktrees
@@ -44,10 +40,12 @@ If the branch already has a worktree, `wt switch` changes directories to it. Oth
When creating a worktree, worktrunk:
-1. Creates worktree at configured path
-2. Switches to new directory
-3. Runs [post-create hooks](@/hook.md#post-create) (blocking)
-4. Spawns [post-start hooks](@/hook.md#post-start) (background)
+1. Runs [pre-switch hooks](@/hook.md#pre-switch) (blocking, fail-fast)
+2. Creates worktree at configured path
+3. Switches to new directory
+4. Runs [post-create hooks](@/hook.md#post-create) (blocking)
+5. Spawns [post-start hooks](@/hook.md#post-start) (background)
+6. Spawns [post-switch hooks](@/hook.md#post-switch) (background)
```bash
wt switch feature # Existing branch → creates worktree
@@ -116,29 +114,18 @@ pager = "delta --paging=never --width=$COLUMNS"
Available on Unix only (macOS, Linux). On Windows, use `wt list` or `wt switch <branch>` directly.
-## GitHub pull requests
-
-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.
-
-```bash
-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:** The local branch uses the PR's branch name directly (e.g., `feature-fix`), so `git push` works normally. If a local branch with that name already exists tracking something else, rename it first.
-
-## GitLab merge requests
+## Pull requests and merge requests
-The `mr:<number>` syntax resolves the branch for a GitLab merge request. For same-project MRs, it switches to the branch directly. For fork MRs, it fetches `refs/merge-requests/N/head` and configures `pushRemote` to the fork URL.
+The `pr:<number>` and `mr:<number>` shortcuts resolve a GitHub PR or GitLab MR to its branch. For same-repo PRs/MRs, worktrunk switches to the branch directly. For fork PRs/MRs, it fetches the ref (`refs/pull/N/head` or `refs/merge-requests/N/head`) and configures `pushRemote` to the fork URL.
```bash
-wt switch mr:101 # Checkout MR !101
+wt switch pr:101 # GitHub PR #101
+wt switch mr:101 # GitLab MR !101
```
-Requires `glab` CLI to be installed and authenticated. The `--create` flag cannot be used with `mr:` syntax since the branch already exists.
+Requires `gh` (GitHub) or `glab` (GitLab) CLI to be installed and authenticated. The `--create` flag cannot be used with `pr:`/`mr:` syntax since the branch already exists.
-**Fork MRs:** The local branch uses the MR's branch name directly, so `git push` works normally. If a local branch with that name already exists tracking something else, rename it first.
+**Forks:** The local branch uses the PR/MR's branch name directly (e.g., `feature-fix`), so `git push` works normally. If a local branch with that name already exists tracking something else, rename it first.
## When wt switch fails
diff --git a/docs/content/worktrunk.md b/docs/content/worktrunk.md
index 3a24d29f7..32fcf73ab 100644
--- a/docs/content/worktrunk.md
+++ b/docs/content/worktrunk.md
@@ -89,7 +89,7 @@ git branch -d feat{% end %}</td>
- **[Interactive picker](@/switch.md#interactive-picker)** — browse worktrees with live diff and log previews
- **[Copy build caches](@/step.md)** — skip cold starts by sharing `target/`, `node_modules/`, etc between worktrees
- **[`wt list --full`](@/list.md#full-mode)** — [CI status](@/list.md#ci-status) and [AI-generated summaries](@/list.md#llm-summaries) per branch
-- **[PR checkout](@/switch.md#github-pull-requests)** — `wt switch pr:123` to jump straight to a PR's branch
+- **[PR checkout](@/switch.md#pull-requests-and-merge-requests)** — `wt switch pr:123` to jump straight to a PR's branch
- **[Dev server per worktree](@/hook.md#dev-servers)** — `hash_port` template filter gives each worktree a unique port
- ...and **[lots more](#next-steps)**
diff --git a/skills/worktrunk/reference/switch.md b/skills/worktrunk/reference/switch.md
index da5b5d84a..27c2c98a5 100644
--- a/skills/worktrunk/reference/switch.md
+++ b/skills/worktrunk/reference/switch.md
@@ -16,11 +16,7 @@ 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.
-
-**Upstream tracking:** Branches created with `--create` have no upstream tracking configured. This prevents accidental pushes to the wrong branch — for example, `--base origin/main` would otherwise make `git push` target `main`. Use `git push -u origin <branch>` to set up tracking as needed.
-
-Without `--create`, switching to a remote branch (e.g., `wt switch feature` when only `origin/feature` exists) creates a local branch tracking the remote — this is the standard git behavior and is preserved.
+The `--create` flag creates a new branch from the `--base` branch (defaults to default branch). Without `--create`, the branch must already exist. Switching to a remote branch (e.g., `wt switch feature` when only `origin/feature` exists) creates a local tracking branch.
## Creating worktrees
@@ -28,10 +24,12 @@ If the branch already has a worktree, `wt switch` changes directories to it. Oth
When creating a worktree, worktrunk:
-1. Creates worktree at configured path
-2. Switches to new directory
-3. Runs [post-create hooks](https://worktrunk.dev/hook/#post-create) (blocking)
-4. Spawns [post-start hooks](https://worktrunk.dev/hook/#post-start) (background)
+1. Runs [pre-switch hooks](https://worktrunk.dev/hook/#pre-switch) (blocking, fail-fast)
+2. Creates worktree at configured path
+3. Switches to new directory
+4. Runs [post-create hooks](https://worktrunk.dev/hook/#post-create) (blocking)
+5. Spawns [post-start hooks](https://worktrunk.dev/hook/#post-start) (background)
+6. Spawns [post-switch hooks](https://worktrunk.dev/hook/#post-switch) (background)
```bash
wt switch feature # Existing branch → creates worktree
@@ -93,29 +91,18 @@ pager = "delta --paging=never --width=$COLUMNS"
Available on Unix only (macOS, Linux). On Windows, use `wt list` or `wt switch <branch>` directly.
-## GitHub pull requests
-
-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.
-
-```bash
-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:** The local branch uses the PR's branch name directly (e.g., `feature-fix`), so `git push` works normally. If a local branch with that name already exists tracking something else, rename it first.
-
-## GitLab merge requests
+## Pull requests and merge requests
-The `mr:<number>` syntax resolves the branch for a GitLab merge request. For same-project MRs, it switches to the branch directly. For fork MRs, it fetches `refs/merge-requests/N/head` and configures `pushRemote` to the fork URL.
+The `pr:<number>` and `mr:<number>` shortcuts resolve a GitHub PR or GitLab MR to its branch. For same-repo PRs/MRs, worktrunk switches to the branch directly. For fork PRs/MRs, it fetches the ref (`refs/pull/N/head` or `refs/merge-requests/N/head`) and configures `pushRemote` to the fork URL.
```bash
-wt switch mr:101 # Checkout MR !101
+wt switch pr:101 # GitHub PR #101
+wt switch mr:101 # GitLab MR !101
```
-Requires `glab` CLI to be installed and authenticated. The `--create` flag cannot be used with `mr:` syntax since the branch already exists.
+Requires `gh` (GitHub) or `glab` (GitLab) CLI to be installed and authenticated. The `--create` flag cannot be used with `pr:`/`mr:` syntax since the branch already exists.
-**Fork MRs:** The local branch uses the MR's branch name directly, so `git push` works normally. If a local branch with that name already exists tracking something else, rename it first.
+**Forks:** The local branch uses the PR/MR's branch name directly (e.g., `feature-fix`), so `git push` works normally. If a local branch with that name already exists tracking something else, rename it first.
## When wt switch fails
diff --git a/skills/worktrunk/reference/worktrunk.md b/skills/worktrunk/reference/worktrunk.md
index cfbf34ddb..e1e9de944 100644
--- a/skills/worktrunk/reference/worktrunk.md
+++ b/skills/worktrunk/reference/worktrunk.md
@@ -74,7 +74,7 @@ git branch -d feat{% end %}</td>
- **[Interactive picker](https://worktrunk.dev/switch/#interactive-picker)** — browse worktrees with live diff and log previews
- **[Copy build caches](https://worktrunk.dev/step/)** — skip cold starts by sharing `target/`, `node_modules/`, etc between worktrees
- **[`wt list --full`](https://worktrunk.dev/list/#full-mode)** — [CI status](https://worktrunk.dev/list/#ci-status) and [AI-generated summaries](https://worktrunk.dev/list/#llm-summaries) per branch
-- **[PR checkout](https://worktrunk.dev/switch/#github-pull-requests)** — `wt switch pr:123` to jump straight to a PR's branch
+- **[PR checkout](https://worktrunk.dev/switch/#pull-requests-and-merge-requests)** — `wt switch pr:123` to jump straight to a PR's branch
- **[Dev server per worktree](https://worktrunk.dev/hook/#dev-servers)** — `hash_port` template filter gives each worktree a unique port
- ...and **[lots more](#next-steps)**
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index 90142d810..a2be64dc4 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -264,11 +264,7 @@ 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.
-
-**Upstream tracking:** Branches created with `--create` have no upstream tracking configured. This prevents accidental pushes to the wrong branch — for example, `--base origin/main` would otherwise make `git push` target `main`. Use `git push -u origin <branch>` to set up tracking as needed.
-
-Without `--create`, switching to a remote branch (e.g., `wt switch feature` when only `origin/feature` exists) creates a local branch tracking the remote — this is the standard git behavior and is preserved.
+The `--create` flag creates a new branch from the `--base` branch (defaults to default branch). Without `--create`, the branch must already exist. Switching to a remote branch (e.g., `wt switch feature` when only `origin/feature` exists) creates a local tracking branch.
## Creating worktrees
@@ -276,10 +272,12 @@ If the branch already has a worktree, `wt switch` changes directories to it. Oth
When creating a worktree, worktrunk:
-1. Creates worktree at configured path
-2. Switches to new directory
-3. Runs [post-create hooks](@/hook.md#post-create) (blocking)
-4. Spawns [post-start hooks](@/hook.md#post-start) (background)
+1. Runs [pre-switch hooks](@/hook.md#pre-switch) (blocking, fail-fast)
+2. Creates worktree at configured path
+3. Switches to new directory
+4. Runs [post-create hooks](@/hook.md#post-create) (blocking)
+5. Spawns [post-start hooks](@/hook.md#post-start) (background)
+6. Spawns [post-switch hooks](@/hook.md#post-switch) (background)
```console
wt switch feature # Existing branch → creates worktree
@@ -342,29 +340,18 @@ pager = "delta --paging=never --width=$COLUMNS"
Available on Unix only (macOS, Linux). On Windows, use `wt list` or `wt switch <branch>` directly.
-## GitHub pull requests
-
-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.
-
-```console
-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:** The local branch uses the PR's branch name directly (e.g., `feature-fix`), so `git push` works normally. If a local branch with that name already exists tracking something else, rename it first.
-
-## GitLab merge requests
+## Pull requests and merge requests
-The `mr:<number>` syntax resolves the branch for a GitLab merge request. For same-project MRs, it switches to the branch directly. For fork MRs, it fetches `refs/merge-requests/N/head` and configures `pushRemote` to the fork URL.
+The `pr:<number>` and `mr:<number>` shortcuts resolve a GitHub PR or GitLab MR to its branch. For same-repo PRs/MRs, worktrunk switches to the branch directly. For fork PRs/MRs, it fetches the ref (`refs/pull/N/head` or `refs/merge-requests/N/head`) and configures `pushRemote` to the fork URL.
```console
-wt switch mr:101 # Checkout MR !101
+wt switch pr:101 # GitHub PR #101
+wt switch mr:101 # GitLab MR !101
```
-Requires `glab` CLI to be installed and authenticated. The `--create` flag cannot be used with `mr:` syntax since the branch already exists.
+Requires `gh` (GitHub) or `glab` (GitLab) CLI to be installed and authenticated. The `--create` flag cannot be used with `pr:`/`mr:` syntax since the branch already exists.
-**Fork MRs:** The local branch uses the MR's branch name directly, so `git push` works normally. If a local branch with that name already exists tracking something else, rename it first.
+**Forks:** The local branch uses the PR/MR's branch name directly (e.g., `feature-fix`), so `git push` works normally. If a local branch with that name already exists tracking something else, rename it first.
## When wt switch fails
diff --git a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap b/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
index 570aa1ff6..7a89850b0 100644
--- a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
@@ -120,11 +120,7 @@ Worktrees are addressed by branch name; paths are computed from a configurable t
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.
-
-Upstream tracking: Branches created with --create have no upstream tracking configured. This prevents accidental pushes to the wrong branch — for example, --base origin/main would otherwise make git push target main. Use git push -u origin <branch> to set up tracking as needed.
-
-Without --create, switching to a remote branch (e.g., wt switch feature when only origin/feature exists) creates a local branch tracking the remote — this is the standard git behavior and is preserved.
+The --create flag creates a new branch from the --base branch (defaults to default branch). Without --create, the branch must already exist. Switching to a remote branch (e.g., wt switch feature when only origin/feature exists) creates a local tracking branch.
Creating worktrees
@@ -132,10 +128,12 @@ If the branch already has a worktree, wt switch changes directories to i
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)
+1. Runs pre-switch hooks (blocking, fail-fast)
+2. Creates worktree at configured path
+3. Switches to new directory
+4. Runs post-create hooks (blocking)
+5. Spawns post-start hooks (background)
+6. Spawns post-switch hooks (background)
  wt switch feature # Existing branch → creates worktree
  wt switch --create feature # New branch and worktree
@@ -191,25 +189,16 @@ When called without arguments, wt switch opens an interactive picker to
Available on Unix only (macOS, Linux). On Windows, use wt list or wt switch <branch> directly.
-GitHub pull requests
-
-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: The local branch uses the PR's branch name directly (e.g., feature-fix), so git push works normally. If a local branch with that name already exists tracking something else, rename it first.
-
-GitLab merge requests
+Pull requests and merge requests
-The mr:<number> syntax resolves the branch for a GitLab merge request. For same-project MRs, it switches to the branch directly. For fork MRs, it fetches refs/merge-requests/N/head and configures pushRemote to the fork URL.
+The pr:<number> and mr:<number> shortcuts resolve a GitHub PR or GitLab MR to its branch. For same-repo PRs/MRs, worktrunk switches to the branch directly. For fork PRs/MRs, it fetches the ref (refs/pull/N/head or refs/merge-requests/N/head) and configures pushRemote to the fork URL.
-  wt switch mr:101 # Checkout MR !101
+  wt switch pr:101 # GitHub PR #101
+  wt switch mr:101 # GitLab MR !101
-Requires glab CLI to be installed and authenticated. The --create flag cannot be used with mr: syntax since the branch already exists.
+Requires gh (GitHub) or glab (GitLab) CLI to be installed and authenticated. The --create flag cannot be used with pr:/mr: syntax since the branch already exists.
-Fork MRs: The local branch uses the MR's branch name directly, so git push works normally. If a local branch with that name already exists tracking something else, rename it first.
+Forks: The local branch uses the PR/MR's branch name directly (e.g., feature-fix), so git push works normally. If a local branch with that name already exists tracking something else, rename it first.
When wt switch fails