Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
docs(switch): give PR links equal billing with pr:N (#2970)
Maximilian Roos2dd5d60902e1
diff --git a/.config/lychee.toml b/.config/lychee.tomlindex 614009a03..46bf12490 100644--- a/.config/lychee.toml+++ b/.config/lychee.toml@@ -35,6 +35,7 @@ exclude = ["github\\.com/[^/]+/[^/]+/actions","github\\.com/[^/]+/[^/]+/stargazers","github\\.com/[^/]+/[^/]+/releases/tag",+ "gitlab\\.com/.+/-/merge_requests",# GitHub user/org profiles (no content we control, frequently 429/502)"github\\.com/[a-zA-Z0-9_-]+$",diff --git a/docs/content/switch.md b/docs/content/switch.mdindex b7e73c053..8c0a85cf2 100644--- a/docs/content/switch.md+++ b/docs/content/switch.md@@ -22,7 +22,7 @@ Worktrees are addressed by branch name; paths are computed from a configurable t## Examples-{{ terminal(cmd="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") }}+{{ terminal(cmd="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|||wt switch https://github.com/owner/repo/pull/123 # ...or paste the PR's URL") }}## Creating a branch@@ -52,7 +52,7 @@ If the branch already has a worktree, `wt switch` changes directories to it. Oth{{ terminal(cmd="wt switch - # Back to previous|||wt switch ^ # Default branch worktree|||wt switch --create fix --base=@ # Branch from current HEAD|||wt switch --create fix --base=pr:123 # Branch from PR #123's head|||wt switch pr:123 # PR #123's branch|||wt switch mr:101 # MR !101's branch") }}-Shortcuts also apply to `--base`. For a fork PR/MR, the head commit is fetched and used as the base SHA without creating a tracking branch. (Web URLs like `https://github.com/owner/repo/pull/N` or `https://gitlab.com/owner/repo/-/merge_requests/N` work in place of `pr:N` / `mr:N` anywhere a shortcut does.)+Shortcuts also apply to `--base`. For a fork PR/MR, the head commit is fetched and used as the base SHA without creating a tracking branch.## Interactive picker@@ -98,11 +98,13 @@ Available on Unix only (macOS, Linux). On Windows, use `wt list` or `wt switch <## Pull requests and merge requests-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.+The `pr:<number>` / `mr:<number>` shortcut and the PR/MR's web URL both resolve 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.-{{ terminal(cmd="wt switch pr:101 # GitHub PR #101|||wt switch mr:101 # GitLab MR !101") }}+{{ terminal(cmd="wt switch pr:101 # GitHub PR #101|||wt switch https://github.com/owner/repo/pull/101 # ...the same PR, by URL|||wt switch mr:101 # GitLab MR !101|||wt switch https://gitlab.com/owner/repo/-/merge_requests/101 # ...the same MR, by URL") }}-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.+Both work anywhere a branch is accepted, including `--base`.++Requires `gh` (GitHub) or `glab` (GitLab) CLI to be installed and authenticated. The `--create` flag cannot be used with a PR/MR reference since the branch already exists.**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.diff --git a/skills/worktrunk/reference/switch.md b/skills/worktrunk/reference/switch.mdindex 190c70337..e8c7bb977 100644--- a/skills/worktrunk/reference/switch.md+++ b/skills/worktrunk/reference/switch.md@@ -12,6 +12,7 @@ $ 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+$ wt switch https://github.com/owner/repo/pull/123 # ...or paste the PR's URL```## Creating a branch@@ -54,7 +55,7 @@ $ wt switch pr:123 # PR #123's branch$ wt switch mr:101 # MR !101's branch```-Shortcuts also apply to `--base`. For a fork PR/MR, the head commit is fetched and used as the base SHA without creating a tracking branch. (Web URLs like `https://github.com/owner/repo/pull/N` or `https://gitlab.com/owner/repo/-/merge_requests/N` work in place of `pr:N` / `mr:N` anywhere a shortcut does.)+Shortcuts also apply to `--base`. For a fork PR/MR, the head commit is fetched and used as the base SHA without creating a tracking branch.## Interactive picker@@ -93,14 +94,18 @@ Available on Unix only (macOS, Linux). On Windows, use `wt list` or `wt switch <## Pull requests and merge requests-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.+The `pr:<number>` / `mr:<number>` shortcut and the PR/MR's web URL both resolve 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 pr:101 # GitHub PR #101-$ wt switch mr:101 # GitLab MR !101+$ wt switch pr:101 # GitHub PR #101+$ wt switch https://github.com/owner/repo/pull/101 # ...the same PR, by URL+$ wt switch mr:101 # GitLab MR !101+$ wt switch https://gitlab.com/owner/repo/-/merge_requests/101 # ...the same MR, by URL```-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.+Both work anywhere a branch is accepted, including `--base`.++Requires `gh` (GitHub) or `glab` (GitLab) CLI to be installed and authenticated. The `--create` flag cannot be used with a PR/MR reference since the branch already exists.**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.diff --git a/src/cli/mod.rs b/src/cli/mod.rsindex 468fab9fa..6ca07408d 100644--- a/src/cli/mod.rs+++ b/src/cli/mod.rs@@ -560,6 +560,7 @@ $ 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+$ wt switch https://github.com/owner/repo/pull/123 # ...or paste the PR's URL```## Creating a branch@@ -602,7 +603,7 @@ $ wt switch pr:123 # PR #123's branch$ wt switch mr:101 # MR !101's branch```-Shortcuts also apply to `--base`. For a fork PR/MR, the head commit is fetched and used as the base SHA without creating a tracking branch. (Web URLs like `https://github.com/owner/repo/pull/N` or `https://gitlab.com/owner/repo/-/merge_requests/N` work in place of `pr:N` / `mr:N` anywhere a shortcut does.)+Shortcuts also apply to `--base`. For a fork PR/MR, the head commit is fetched and used as the base SHA without creating a tracking branch.## Interactive picker@@ -642,14 +643,18 @@ Available on Unix only (macOS, Linux). On Windows, use `wt list` or `wt switch <## Pull requests and merge requests-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.+The `pr:<number>` / `mr:<number>` shortcut and the PR/MR's web URL both resolve 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 pr:101 # GitHub PR #101-$ wt switch mr:101 # GitLab MR !101+$ wt switch pr:101 # GitHub PR #101+$ wt switch https://github.com/owner/repo/pull/101 # ...the same PR, by URL+$ wt switch mr:101 # GitLab MR !101+$ wt switch https://gitlab.com/owner/repo/-/merge_requests/101 # ...the same MR, by URL```-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.+Both work anywhere a branch is accepted, including `--base`.++Requires `gh` (GitHub) or `glab` (GitLab) CLI to be installed and authenticated. The `--create` flag cannot be used with a PR/MR reference since the branch already exists.**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.diff --git a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap b/tests/snapshots/integration__integration_tests__help__help_switch_long.snapindex cc884f5c7..4b3856571 100644--- a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap+++ b/tests/snapshots/integration__integration_tests__help__help_switch_long.snap@@ -131,6 +131,7 @@ Worktrees are addressed by branch name; paths are computed from a configurable t[107m [0m [2m[0m[2m[34mwt[0m[2m switch [0m[2m[36m--create[0m[2m new-feature # Create new branch and worktree[0m[2m[0m[107m [0m [2m[0m[2m[34mwt[0m[2m switch [0m[2m[36m--create[0m[2m hotfix [0m[2m[36m--base[0m[2m production[0m[107m [0m [2m[0m[2m[34mwt[0m[2m switch pr:123 # Switch to PR #123's branch[0m[2m[0m+[107m [0m [2m[0m[2m[34mwt[0m[2m switch https://github.com/owner/repo/pull/123 # ...or paste the PR's URL[0m[2m[0m[1m[32mCreating a branch[0m@@ -168,7 +169,7 @@ If the branch already has a worktree, [2mwt switch[0m changes directories to i[107m [0m [2m[0m[2m[34mwt[0m[2m switch pr:123 # PR #123's branch[0m[2m[0m[107m [0m [2m[0m[2m[34mwt[0m[2m switch mr:101 # MR !101's branch[0m[2m[0m-Shortcuts also apply to [2m--base[0m. For a fork PR/MR, the head commit is fetched and used as the base SHA without creating a tracking branch. (Web URLs like [2mhttps://github.com/owner/repo/pull/N[0m or [2mhttps://gitlab.com/owner/repo/-/merge_requests/N[0m work in place of [2mpr:N[0m / [2mmr:N[0m anywhere a shortcut does.)+Shortcuts also apply to [2m--base[0m. For a fork PR/MR, the head commit is fetched and used as the base SHA without creating a tracking branch.[1m[32mInteractive picker[0m@@ -204,12 +205,16 @@ Available on Unix only (macOS, Linux). On Windows, use [2mwt list[0m or [2mwt[1m[32mPull requests and merge requests[0m-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.+The [2mpr:<number>[0m / [2mmr:<number>[0m shortcut and the PR/MR's web URL both resolve 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 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+[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 https://github.com/owner/repo/pull/101 # ...the same PR, by URL[0m[2m[0m+[107m [0m [2m[0m[2m[34mwt[0m[2m switch mr:101 # GitLab MR !101[0m[2m[0m+[107m [0m [2m[0m[2m[34mwt[0m[2m switch https://gitlab.com/owner/repo/-/merge_requests/101 # ...the same MR, by URL[0m[2m[0m-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.+Both work anywhere a branch is accepted, including [2m--base[0m.++Requires [2mgh[0m (GitHub) or [2mglab[0m (GitLab) CLI to be installed and authenticated. The [2m--create[0m flag cannot be used with a PR/MR reference since the branch already exists.[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.