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.mdindex 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: '^' (default branch), '-' (previous), '@'- (current), 'pr:{N}' (GitHub PR), 'mr:{N}' (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.mdindex 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.rsindex 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 failsdiff --git a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap b/tests/snapshots/integration__integration_tests__help__help_switch_long.snapindex 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: [1m[36mwt switch[0m [36m[OPTIONS][0m [36m[BRANCH][0m [1m[36m[--[1m[32mArguments:[0m[36m[BRANCH][0m- Branch name or shortcut[0m+ Branch name, shortcut, or PR/MR URL[0m- Opens interactive picker if omitted. Shortcuts: '^' (default branch), '-' (previous), '@' (current), 'pr:{N}' (GitHub PR), 'mr:{N}' (GitLab MR)[0m+ Opens interactive picker if omitted. Shortcuts: [1m^[0m (default branch), [1m-[0m (previous), [1m@[0m (current), [1mpr:{N}[0m (GitHub PR), [1mmr:{N}[0m (GitLab MR)[0m[36m[EXECUTE_ARGS]...[0mAdditional arguments for --execute command (after --)[0m@@ -211,15 +211,11 @@ The [2mpr:<number>[0m / [2mmr:<number>[0m shortcut and the PR/MR's web URL b[107m [0m [2m[0m[2m[34mwt[0m[2m switch mr:101 # GitLab MR !101[0m[107m [0m [2m[0m[2m[34mwt[0m[2m switch https://gitlab.com/owner/repo/-/merge_requests/101 # ...the same MR, by URL[0m-Both work anywhere a branch is accepted, including [2m--base[0m.+Both work anywhere a branch is accepted, including [2m--base[0m. The [2m--create[0m flag cannot be used with a PR/MR reference 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 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 [2mgit push[0m works normally. A pre-existing local branch with that name tracking something else requires renaming 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.--[1mGitea (experimental):[0m [2mpr:[0m is also compatible with Gitea via the [2mtea[0m CLI. Set [2m[forge] platform = "gitea"[0m in [2m.config/wt.toml[0m to opt in; worktrunk also auto-detects Gitea when the remote host contains [2mgitea[0m or when [2mtea login add[0m has been run for the host.--[1mAzure DevOps (experimental):[0m [2mpr:[0m is also compatible with Azure DevOps via the [2maz[0m CLI (with the [2mazure-devops[0m extension). Set [2m[forge] platform = "azure-devops"[0m in [2m.config/wt.toml[0m to opt in; worktrunk also auto-detects Azure DevOps from [2mdev.azure.com[0m and [2m*.visualstudio.com[0m remotes.+Requires [2mgh[0m (GitHub), [2mglab[0m (GitLab), or an equivalent CLI installed and authenticated; see forge platform for Gitea, Azure DevOps, and other supported platforms.[1m[32mWhen wt switch fails[0mdiff --git a/tests/snapshots/integration__integration_tests__help__help_switch_short.snap b/tests/snapshots/integration__integration_tests__help__help_switch_short.snapindex 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 neededUsage: [1m[36mwt switch[0m [36m[OPTIONS][0m [36m[BRANCH][0m [1m[36m[--[0m [36m<EXECUTE_ARGS>...[0m[1m[36m][0m[1m[32mArguments:[0m- [36m[BRANCH][0m Branch name or shortcut+ [36m[BRANCH][0m Branch name, shortcut, or PR/MR URL[36m[EXECUTE_ARGS]...[0m Additional arguments for --execute command (after --)[1m[32mOptions:[0m