Skip to content

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.toml
index 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.md
index 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.md
index 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.rs
index 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.snap
index 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
  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
@@ -168,7 +169,7 @@ If the branch already has a worktree, wt switch changes directories to i
  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
@@ -204,12 +205,16 @@ Available on Unix only (macOS, Linux). On Windows, use wt list or wt
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.
-  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.