Skip to content

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

docs(switch): refine wt switch --help text (#3096)

Worktrunk Bot6f63a5bc54cb
diff --git a/docs/content/switch.md b/docs/content/switch.md
index 7f80faa4a..d48920f7a 100644
--- a/docs/content/switch.md
+++ b/docs/content/switch.md
@@ -105,15 +105,11 @@ The `pr:<number>` / `mr:<number>` shortcut and the PR/MR's web URL both resolve
{{ 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") }}
-Both work anywhere a branch is accepted, including `--base`.
+Both work anywhere a branch is accepted, including `--base`. The `--create` flag cannot be used with a PR/MR reference since the branch already exists.
-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.
+If the PR or MR is on a fork, the local branch uses its branch name directly, so `git push` works normally. A pre-existing local branch with that name tracking something else requires renaming 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.
-
-**Gitea (experimental):** `pr:` is also compatible with Gitea via the `tea` CLI. Set `[forge] platform = "gitea"` in `.config/wt.toml` to opt in; worktrunk also auto-detects Gitea when the remote host contains `gitea` or when `tea login add` has been run for the host.
-
-**Azure DevOps (experimental):** `pr:` is also compatible with Azure DevOps via the `az` CLI (with the `azure-devops` extension). Set `[forge] platform = "azure-devops"` in `.config/wt.toml` to opt in; worktrunk also auto-detects Azure DevOps from `dev.azure.com` and `*.visualstudio.com` remotes.
+Requires `gh` (GitHub), `glab` (GitLab), or an equivalent CLI installed and authenticated; see [forge platform](@/config.md#forge-platform) for Gitea, Azure DevOps, and other supported platforms.
## When wt switch fails
@@ -138,10 +134,10 @@ Usage: <b><span class=c>wt switch</span></b> <span class=c>[OPTIONS]</span> <spa
<b><span class=g>Arguments:</span></b>
<span class=c>[BRANCH]</span>
- Branch name or shortcut
+ Branch name, shortcut, or PR/MR URL
- Opens interactive picker if omitted. Shortcuts: &#39;^&#39; (default branch), &#39;-&#39; (previous), &#39;@&#39;
- (current), &#39;pr:{N}&#39; (GitHub PR), &#39;mr:{N}&#39; (GitLab MR)
+ Opens interactive picker if omitted. Shortcuts: <b>^</b> (default branch), <b>-</b> (previous), <b>@</b>
+ (current), <b>pr:{N}</b> (GitHub PR), <b>mr:{N}</b> (GitLab MR)
<span class=c>[EXECUTE_ARGS]...</span>
Additional arguments for --execute command (after --)
diff --git a/skills/worktrunk/reference/switch.md b/skills/worktrunk/reference/switch.md
index a9c89a6fd..ac9529813 100644
--- a/skills/worktrunk/reference/switch.md
+++ b/skills/worktrunk/reference/switch.md
@@ -106,15 +106,11 @@ $ wt switch mr:101 # GitLab MR !101
$ wt switch https://gitlab.com/owner/repo/-/merge_requests/101 # ...the same MR, by URL
```
-Both work anywhere a branch is accepted, including `--base`.
+Both work anywhere a branch is accepted, including `--base`. The `--create` flag cannot be used with a PR/MR reference since the branch already exists.
-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.
+If the PR or MR is on a fork, the local branch uses its branch name directly, so `git push` works normally. A pre-existing local branch with that name tracking something else requires renaming 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.
-
-**Gitea (experimental):** `pr:` is also compatible with Gitea via the `tea` CLI. Set `[forge] platform = "gitea"` in `.config/wt.toml` to opt in; worktrunk also auto-detects Gitea when the remote host contains `gitea` or when `tea login add` has been run for the host.
-
-**Azure DevOps (experimental):** `pr:` is also compatible with Azure DevOps via the `az` CLI (with the `azure-devops` extension). Set `[forge] platform = "azure-devops"` in `.config/wt.toml` to opt in; worktrunk also auto-detects Azure DevOps from `dev.azure.com` and `*.visualstudio.com` remotes.
+Requires `gh` (GitHub), `glab` (GitLab), or an equivalent CLI installed and authenticated; see [forge platform](https://worktrunk.dev/config/#forge-platform) for Gitea, Azure DevOps, and other supported platforms.
## When wt switch fails
@@ -133,10 +129,10 @@ Usage: wt switch [OPTIONS] [BRANCH] [-- <EXECUTE_ARGS>...]
Arguments:
[BRANCH]
- Branch name or shortcut
+ Branch name, shortcut, or PR/MR URL
- Opens interactive picker if omitted. Shortcuts: '^' (default branch), '-' (previous), '@'
- (current), 'pr:{N}' (GitHub PR), 'mr:{N}' (GitLab MR)
+ Opens interactive picker if omitted. Shortcuts: ^ (default branch), - (previous), @
+ (current), pr:{N} (GitHub PR), mr:{N} (GitLab MR)
[EXECUTE_ARGS]...
Additional arguments for --execute command (after --)
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index d306ea8e1..c7253bb95 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -302,10 +302,10 @@ impl HookFlags {
#[derive(Args)]
pub(crate) struct SwitchArgs {
- /// Branch name or shortcut
+ /// Branch name, shortcut, or PR/MR URL
///
/// Opens interactive picker if omitted.
- /// Shortcuts: '^' (default branch), '-' (previous), '@' (current), 'pr:{N}' (GitHub PR), 'mr:{N}' (GitLab MR)
+ /// Shortcuts: `^` (default branch), `-` (previous), `@` (current), `pr:{N}` (GitHub PR), `mr:{N}` (GitLab MR)
#[arg(add = crate::completion::worktree_branch_completer())]
pub(crate) branch: Option<String>,
@@ -656,15 +656,11 @@ $ wt switch mr:101 # GitLab MR !101
$ wt switch https://gitlab.com/owner/repo/-/merge_requests/101 # ...the same MR, by URL
```
-Both work anywhere a branch is accepted, including `--base`.
+Both work anywhere a branch is accepted, including `--base`. The `--create` flag cannot be used with a PR/MR reference since the branch already exists.
-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.
+If the PR or MR is on a fork, the local branch uses its branch name directly, so `git push` works normally. A pre-existing local branch with that name tracking something else requires renaming 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.
-
-**Gitea (experimental):** `pr:` is also compatible with Gitea via the `tea` CLI. Set `[forge] platform = "gitea"` in `.config/wt.toml` to opt in; worktrunk also auto-detects Gitea when the remote host contains `gitea` or when `tea login add` has been run for the host.
-
-**Azure DevOps (experimental):** `pr:` is also compatible with Azure DevOps via the `az` CLI (with the `azure-devops` extension). Set `[forge] platform = "azure-devops"` in `.config/wt.toml` to opt in; worktrunk also auto-detects Azure DevOps from `dev.azure.com` and `*.visualstudio.com` remotes.
+Requires `gh` (GitHub), `glab` (GitLab), or an equivalent CLI installed and authenticated; see [forge platform](@/config.md#forge-platform) for Gitea, Azure DevOps, and other supported platforms.
## 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 10ffef2ea..1304723b7 100644
--- a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
@@ -38,9 +38,9 @@ Usage: wt switch [OPTIONS] [BRANCH] [--
Arguments:
[BRANCH]
- Branch name or shortcut
+ Branch name, shortcut, or PR/MR URL
- Opens interactive picker if omitted. Shortcuts: '^' (default branch), '-' (previous), '@' (current), 'pr:{N}' (GitHub PR), 'mr:{N}' (GitLab MR)
+ Opens interactive picker if omitted. Shortcuts: ^ (default branch), - (previous), @ (current), pr:{N} (GitHub PR), mr:{N} (GitLab MR)
[EXECUTE_ARGS]...
Additional arguments for --execute command (after --)
@@ -211,15 +211,11 @@ The pr:<number> / mr:<number> shortcut and the PR/MR's web URL b
  wt switch mr:101 # GitLab MR !101
  wt switch https://gitlab.com/owner/repo/-/merge_requests/101 # ...the same MR, by URL
-Both work anywhere a branch is accepted, including --base.
+Both work anywhere a branch is accepted, including --base. The --create flag cannot be used with a PR/MR reference since the branch already exists.
-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.
+If the PR or MR is on a fork, the local branch uses its branch name directly, so git push works normally. A pre-existing local branch with that name tracking something else requires renaming 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.
-
-Gitea (experimental): pr: is also compatible with Gitea via the tea CLI. Set [forge] platform = "gitea" in .config/wt.toml to opt in; worktrunk also auto-detects Gitea when the remote host contains gitea or when tea login add has been run for the host.
-
-Azure DevOps (experimental): pr: is also compatible with Azure DevOps via the az CLI (with the azure-devops extension). Set [forge] platform = "azure-devops" in .config/wt.toml to opt in; worktrunk also auto-detects Azure DevOps from dev.azure.com and *.visualstudio.com remotes.
+Requires gh (GitHub), glab (GitLab), or an equivalent CLI installed and authenticated; see forge platform for Gitea, Azure DevOps, and other supported platforms.
When wt switch fails
diff --git a/tests/snapshots/integration__integration_tests__help__help_switch_short.snap b/tests/snapshots/integration__integration_tests__help__help_switch_short.snap
index 3e6c0687d..2f7912aec 100644
--- a/tests/snapshots/integration__integration_tests__help__help_switch_short.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_switch_short.snap
@@ -37,7 +37,7 @@ wt switch - Switch to a worktree; create if needed
Usage: wt switch [OPTIONS] [BRANCH] [-- <EXECUTE_ARGS>...]
Arguments:
- [BRANCH] Branch name or shortcut
+ [BRANCH] Branch name, shortcut, or PR/MR URL
[EXECUTE_ARGS]... Additional arguments for --execute command (after --)
Options: