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.mdindex 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.mdindex 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. OthWhen 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)```bashwt 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 failsdiff --git a/docs/content/worktrunk.md b/docs/content/worktrunk.mdindex 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.mdindex 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. OthWhen 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)```bashwt 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 failsdiff --git a/skills/worktrunk/reference/worktrunk.md b/skills/worktrunk/reference/worktrunk.mdindex 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.rsindex 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. OthWhen 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)```consolewt 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 failsdiff --git a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap b/tests/snapshots/integration__integration_tests__help__help_switch_long.snapindex 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[1m[32mCreating a branch[0m-The [2m--create[0m flag creates a new branch from the [2m--base[0m branch (defaults to default branch). Without [2m--create[0m, the branch must already exist.--[1mUpstream tracking:[0m Branches created with [2m--create[0m have no upstream tracking configured. This prevents accidental pushes to the wrong branch — for example, [2m--base origin/main[0m would otherwise make [2mgit push[0m target [2mmain[0m. Use [2mgit push -u origin <branch>[0m to set up tracking as needed.--Without [2m--create[0m, switching to a remote branch (e.g., [2mwt switch feature[0m when only [2morigin/feature[0m exists) creates a local branch tracking the remote — this is the standard git behavior and is preserved.+The [2m--create[0m flag creates a new branch from the [2m--base[0m branch (defaults to default branch). Without [2m--create[0m, the branch must already exist. Switching to a remote branch (e.g., [2mwt switch feature[0m when only [2morigin/feature[0m exists) creates a local tracking branch.[1m[32mCreating worktrees[0m@@ -132,10 +128,12 @@ If the branch already has a worktree, [2mwt switch[0m changes directories to iWhen 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)[107m [0m [2m[0m[2m[34mwt[0m[2m switch feature # Existing branch → creates worktree[0m[2m[0m[107m [0m [2m[0m[2m[34mwt[0m[2m switch [0m[2m[36m--create[0m[2m feature # New branch and worktree[0m[2m[0m@@ -191,25 +189,16 @@ When called without arguments, [2mwt switch[0m opens an interactive picker toAvailable on Unix only (macOS, Linux). On Windows, use [2mwt list[0m or [2mwt switch <branch>[0m directly.-[1m[32mGitHub pull requests[0m--The [2mpr:<number>[0m syntax resolves the branch for a GitHub pull request. For same-repo PRs, it switches to the branch directly. For fork PRs, it fetches [2mrefs/pull/N/head[0m and configures [2mpushRemote[0m to the fork URL.--[107m [0m [2m[0m[2m[34mwt[0m[2m switch pr:101 # Checkout PR #101[0m[2m[0m--Requires [2mgh[0m CLI to be installed and authenticated. The [2m--create[0m flag cannot be used with [2mpr:[0m syntax since the branch already exists.--[1mFork PRs:[0m The local branch uses the PR's branch name directly (e.g., [2mfeature-fix[0m), so [2mgit push[0m works normally. If a local branch with that name already exists tracking something else, rename it first.--[1m[32mGitLab merge requests[0m+[1m[32mPull requests and merge requests[0m-The [2mmr:<number>[0m syntax resolves the branch for a GitLab merge request. For same-project MRs, it switches to the branch directly. For fork MRs, it fetches [2mrefs/merge-requests/N/head[0m and configures [2mpushRemote[0m to the fork URL.+The [2mpr:<number>[0m and [2mmr:<number>[0m 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 ([2mrefs/pull/N/head[0m or [2mrefs/merge-requests/N/head[0m) and configures [2mpushRemote[0m to the fork URL.-[107m [0m [2m[0m[2m[34mwt[0m[2m switch mr:101 # Checkout MR !101[0m[2m[0m+[107m [0m [2m[0m[2m[34mwt[0m[2m switch pr:101 # GitHub PR #101[0m[2m[0m+[107m [0m [2m[0m[2m[34mwt[0m[2m switch mr:101 # GitLab MR !101[0m[2m[0m-Requires [2mglab[0m CLI to be installed and authenticated. The [2m--create[0m flag cannot be used with [2mmr:[0m syntax since the branch already exists.+Requires [2mgh[0m (GitHub) or [2mglab[0m (GitLab) CLI to be installed and authenticated. The [2m--create[0m flag cannot be used with [2mpr:[0m/[2mmr:[0m syntax since the branch already exists.-[1mFork MRs:[0m The local branch uses the MR's branch name directly, so [2mgit push[0m works normally. If a local branch with that name already exists tracking something else, rename it first.+[1mForks:[0m The local branch uses the PR/MR's branch name directly (e.g., [2mfeature-fix[0m), so [2mgit push[0m works normally. If a local branch with that name already exists tracking something else, rename it first.[1m[32mWhen wt switch fails[0m