Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
docs(extending): rename "external subcommand" to "custom subcommand" (#2270)
Maximilian Roos016eb030e760
diff --git a/docs/content/extending.md b/docs/content/extending.mdindex 0eb1de8e5..8c2589b21 100644--- a/docs/content/extending.md+++ b/docs/content/extending.md@@ -1,6 +1,6 @@+++title = "Extending Worktrunk"-description = "Three ways to add custom behavior: hooks for lifecycle automation, aliases for reusable commands, and external subcommands for standalone tools."+description = "Three ways to add custom behavior: hooks for lifecycle automation, aliases for reusable commands, and custom subcommands for standalone tools."weight = 21[extra]@@ -13,9 +13,9 @@ Worktrunk has three extension mechanisms.**[Aliases](#aliases)** define reusable commands invoked as `wt <name>`. Same template variables as hooks, but triggered manually.-**[External subcommands](#external-subcommands)** are standalone executables. Drop `wt-foo` on `PATH` and it becomes `wt foo`. No configuration needed.+**[Custom subcommands](#custom-subcommands)** are standalone executables. Drop `wt-foo` on `PATH` and it becomes `wt foo`. No configuration needed.-| | Hooks | Aliases | External subcommands |+| | Hooks | Aliases | Custom subcommands ||---|---|---|---|| **Trigger** | Automatic (lifecycle events) | Manual (`wt <name>`) | Manual (`wt <name>`) || **Defined in** | TOML config | TOML config | Any executable on `PATH` |@@ -201,7 +201,7 @@ tail -f "$(wt config state logs --format=json | jq -r --arg name "{{ name | saniRun with `wt hook-log --name=<hook-name>` (e.g., `wt hook-log --name=server`) to tail the current worktree's `post-start` hook of that name. The `sanitize_hash` filter produces a filesystem-safe name with a hash suffix that keeps distinct originals unique — the same transformation Worktrunk applies on disk — so the alias resolves the right log even for branch and hook names containing characters like `/`.-## External subcommands+## Custom subcommands<span class="badge-experimental"></span>@@ -209,7 +209,7 @@ Any executable named `wt-<name>` on `PATH` becomes available as `wt <name>` —{{ terminal(cmd="wt sync origin # runs: wt-sync origin|||wt -C /tmp/repo sync # -C is forwarded as the child's working directory") }}-Arguments pass through verbatim, stdio is inherited, and the child's exit code propagates unchanged. External subcommands don't have access to template variables.+Arguments pass through verbatim, stdio is inherited, and the child's exit code propagates unchanged. Custom subcommands don't have access to template variables.If nothing matches — no built-in, no alias, no `wt-<name>` on `PATH` — wt prints a "not a wt command" error with a typo suggestion.diff --git a/docs/content/faq.md b/docs/content/faq.mdindex bdf7334b0..f593e391f 100644--- a/docs/content/faq.md+++ b/docs/content/faq.md@@ -60,7 +60,7 @@ Git TUIs operate on a single repository. Worktrunk manages multiple worktrees, r## Does Worktrunk support stacked branches?-Not natively — stacked-branch workflows are a large design space, so Worktrunk treats them as an extension rather than a built-in. [`worktrunk-sync`](https://github.com/pablospe/worktrunk-sync) is a community tool that auto-detects the branch dependency tree from git history and rebases each branch onto its parent in topological order. Install with `cargo install worktrunk-sync` and run as `wt sync` (via [external subcommands](@/extending.md#external-subcommands)).+Not natively — stacked-branch workflows are a large design space, so Worktrunk treats them as an extension rather than a built-in. [`worktrunk-sync`](https://github.com/pablospe/worktrunk-sync) is a community tool that auto-detects the branch dependency tree from git history and rebases each branch onto its parent in topological order. Install with `cargo install worktrunk-sync` and run as `wt sync` (via [custom subcommands](@/extending.md#custom-subcommands)).## There's an issue with my shell setupdiff --git a/skills/worktrunk/reference/extending.md b/skills/worktrunk/reference/extending.mdindex ea75db29e..bd0378777 100644--- a/skills/worktrunk/reference/extending.md+++ b/skills/worktrunk/reference/extending.md@@ -6,9 +6,9 @@ Worktrunk has three extension mechanisms.**[Aliases](#aliases)** define reusable commands invoked as `wt <name>`. Same template variables as hooks, but triggered manually.-**[External subcommands](#external-subcommands)** are standalone executables. Drop `wt-foo` on `PATH` and it becomes `wt foo`. No configuration needed.+**[Custom subcommands](#custom-subcommands)** are standalone executables. Drop `wt-foo` on `PATH` and it becomes `wt foo`. No configuration needed.-| | Hooks | Aliases | External subcommands |+| | Hooks | Aliases | Custom subcommands ||---|---|---|---|| **Trigger** | Automatic (lifecycle events) | Manual (`wt <name>`) | Manual (`wt <name>`) || **Defined in** | TOML config | TOML config | Any executable on `PATH` |@@ -198,7 +198,7 @@ tail -f "$(wt config state logs --format=json | jq -r --arg name "{{ name | saniRun with `wt hook-log --name=<hook-name>` (e.g., `wt hook-log --name=server`) to tail the current worktree's `post-start` hook of that name. The `sanitize_hash` filter produces a filesystem-safe name with a hash suffix that keeps distinct originals unique — the same transformation Worktrunk applies on disk — so the alias resolves the right log even for branch and hook names containing characters like `/`.-## External subcommands+## Custom subcommands[experimental]@@ -209,7 +209,7 @@ wt sync origin # runs: wt-sync originwt -C /tmp/repo sync # -C is forwarded as the child's working directory```-Arguments pass through verbatim, stdio is inherited, and the child's exit code propagates unchanged. External subcommands don't have access to template variables.+Arguments pass through verbatim, stdio is inherited, and the child's exit code propagates unchanged. Custom subcommands don't have access to template variables.If nothing matches — no built-in, no alias, no `wt-<name>` on `PATH` — wt prints a "not a wt command" error with a typo suggestion.diff --git a/skills/worktrunk/reference/faq.md b/skills/worktrunk/reference/faq.mdindex 279733c81..382188363 100644--- a/skills/worktrunk/reference/faq.md+++ b/skills/worktrunk/reference/faq.md@@ -53,7 +53,7 @@ Git TUIs operate on a single repository. Worktrunk manages multiple worktrees, r## Does Worktrunk support stacked branches?-Not natively — stacked-branch workflows are a large design space, so Worktrunk treats them as an extension rather than a built-in. [`worktrunk-sync`](https://github.com/pablospe/worktrunk-sync) is a community tool that auto-detects the branch dependency tree from git history and rebases each branch onto its parent in topological order. Install with `cargo install worktrunk-sync` and run as `wt sync` (via [external subcommands](https://worktrunk.dev/extending/#external-subcommands)).+Not natively — stacked-branch workflows are a large design space, so Worktrunk treats them as an extension rather than a built-in. [`worktrunk-sync`](https://github.com/pablospe/worktrunk-sync) is a community tool that auto-detects the branch dependency tree from git history and rebases each branch onto its parent in topological order. Install with `cargo install worktrunk-sync` and run as `wt sync` (via [custom subcommands](https://worktrunk.dev/extending/#custom-subcommands)).## There's an issue with my shell setupdiff --git a/src/cli/mod.rs b/src/cli/mod.rsindex d770354a3..b30e17d65 100644--- a/src/cli/mod.rs+++ b/src/cli/mod.rs@@ -2094,11 +2094,11 @@ $ WORKTRUNK_COMMIT__GENERATION__COMMAND="echo 'test: automated commit'" wt mergeaction: ConfigCommand,},- /// Run an external `wt-<name>` command found on PATH.+ /// Run a custom `wt-<name>` command found on PATH.////// Captured by clap when the first positional argument doesn't match any/// built-in subcommand. The first element of the vec is the subcommand name;- /// the rest are the arguments to pass through. See `commands::external`.+ /// the rest are the arguments to pass through. See `commands::custom`.#[command(external_subcommand)]- External(Vec<OsString>),+ Custom(Vec<OsString>),}diff --git a/src/commands/alias.rs b/src/commands/alias.rsindex 25ee70dc5..514b1dee0 100644--- a/src/commands/alias.rs+++ b/src/commands/alias.rs@@ -76,7 +76,7 @@ const TOP_LEVEL_BUILTINS: &[&str] = &["config", "hook", "list", "merge", "remove", "select", "step", "switch",];-/// Options parsed from the external subcommand args.+/// Options parsed from alias-dispatch args (`wt step <alias>` or `wt <alias>`).#[derive(Debug)]pub struct AliasOptions {pub name: String,@@ -86,7 +86,7 @@ pub struct AliasOptions {}impl AliasOptions {- /// Parse alias options from the external subcommand args.+ /// Parse alias options from `wt step <alias>` args.////// First element is the alias name, remaining are flags:/// `--dry-run`, `--yes`/`-y`, `--var KEY=VALUE`, or `--KEY=VALUE`.@@ -260,8 +260,8 @@ fn load_merged_aliases(/// when no alias by that name is configured — the caller can fall through to/// other dispatch (e.g. `wt-<name>` PATH binary at the top level). Argument/// parsing only runs after we've confirmed the alias is configured, so-/// non-alias `rest` (positional args meant for an external binary) doesn't-/// surface as a parse error.+/// non-alias `rest` (positional args meant for a `wt-<name>` PATH binary)+/// doesn't surface as a parse error.////// Alias execution needs a git repository; without one this returns `Ok(None)`/// so the caller falls through to PATH lookup. Config load errors propagate —@@ -1082,7 +1082,7 @@ cmd = [////// Hidden subcommands like `select` count — clap still matches them/// before falling through to alias dispatch, so they shadow aliases of- /// the same name. Only `help` (clap-internal) and external subcommands+ /// the same name. Only `help` (clap-internal) and custom subcommands/// are excluded.#[test]fn test_top_level_builtins_match_clap() {diff --git a/src/commands/external.rs b/src/commands/custom.rssimilarity index 89%rename from src/commands/external.rsrename to src/commands/custom.rsindex 0b70555a7..1a9f30035 100644--- a/src/commands/external.rs+++ b/src/commands/custom.rs@@ -1,7 +1,7 @@-//! Git-style external subcommand dispatch.+//! Git-style custom subcommand dispatch.//!//! When the user runs `wt foo` and `foo` is not a built-in subcommand, clap-//! captures the invocation via the `Commands::External` variant. This module+//! captures the invocation via the `Commands::Custom` variant. This module//! resolves it in this order://!//! 1. **Alias**: if `foo` is configured as an alias in user/project config,@@ -19,8 +19,8 @@//! `perhaps wt step squash?`).//!//! Built-in subcommands always take precedence — clap only dispatches-//! `Commands::External` when no built-in matched, so there is no way for an-//! alias or external `wt-switch` to shadow `wt switch`.+//! `Commands::Custom` when no built-in matched, so there is no way for an+//! alias or `wt-switch` on PATH to shadow `wt switch`.use std::ffi::OsString;use std::path::{Path, PathBuf};@@ -34,26 +34,26 @@ use crate::cli::build_command;use crate::commands::{alias_names_for_suggestions, did_you_mean, try_alias};use crate::enhance_and_exit_error;-/// Handle a `Commands::External` invocation.+/// Handle a `Commands::Custom` invocation.////// `args[0]` is the subcommand name; `args[1..]` are the arguments to pass/// through. `working_dir`, if set, is the value of the top-level `-C <path>`/// flag — applied as the child's current directory so global `-C` works the-/// same for external subcommands as it does for built-ins.+/// same for custom subcommands as it does for built-ins.////// On success (child exit code 0), returns `Ok(())`. On non-zero exit, returns/// `WorktrunkError::AlreadyDisplayed` with the child's exit code so `main`/// can propagate it without printing an extra error line. When the command/// isn't found on PATH, diverges via `enhance_and_exit_error` with clap's/// standard exit code 2.-pub(crate) fn handle_external_command(+pub(crate) fn handle_custom_command(args: Vec<OsString>,working_dir: Option<PathBuf>,) -> Result<()> {let mut iter = args.into_iter();let name_os = iter.next()- .expect("clap guarantees at least one arg for external subcommands");+ .expect("clap guarantees at least one arg for external_subcommand variants");let rest: Vec<OsString> = iter.collect();let name = name_os@@ -68,10 +68,10 @@ pub(crate) fn handle_external_command(// Try alias dispatch first so user/project config wins over PATH binaries// of the same name. Built-ins still take precedence — clap only routes- // to `Commands::External` when no built-in matched. The alias arg parser+ // to `Commands::Custom` when no built-in matched. The alias arg parser// requires UTF-8, but we only run it after confirming the name is a- // configured alias, so non-UTF-8 args meant for an external binary don't- // surface as alias parse errors.+ // configured alias, so non-UTF-8 args meant for a custom subcommand binary+ // don't surface as alias parse errors.let alias_args: Option<Vec<String>> = rest.iter().map(|a| a.to_str().map(|s| s.to_owned()))@@ -90,7 +90,7 @@ pub(crate) fn handle_external_command(// do the on-PATH binary wins — same as git's behaviour).let binary = format!("wt-{name}");if let Ok(path) = which::which(&binary) {- return run_external(&path, &rest, working_dir.as_deref());+ return run_custom(&path, &rest, working_dir.as_deref());}// Not an alias and not on PATH — emit clap's native `InvalidSubcommand`@@ -132,8 +132,8 @@ fn unrecognized_subcommand_error(name: &str) -> clap::Error {err}-/// Spawn the external binary, inheriting stdio, and propagate its exit code.-fn run_external(path: &Path, args: &[OsString], working_dir: Option<&Path>) -> Result<()> {+/// Spawn the custom binary, inheriting stdio, and propagate its exit code.+fn run_custom(path: &Path, args: &[OsString], working_dir: Option<&Path>) -> Result<()> {let mut cmd = Command::new(path);cmd.args(args);if let Some(dir) = working_dir {@@ -150,7 +150,7 @@ fn run_external(path: &Path, args: &[OsString], working_dir: Option<&Path>) -> R// Propagate the exact exit code — including signal codes on Unix — so// `wt foo` behaves like running `wt-foo` directly. We use- // `AlreadyDisplayed` (not `ChildProcessExited`) because the external+ // `AlreadyDisplayed` (not `ChildProcessExited`) because the custom// command has already reported its own failure to the user; `wt` should// just forward the exit code without adding a second error line.#[cfg(unix)]@@ -234,14 +234,14 @@ mod tests {#[cfg(unix)]#[test]- fn handle_external_command_rejects_non_utf8_name() {+ fn handle_custom_command_rejects_non_utf8_name() {use std::os::unix::ffi::OsStringExt;// clap routes the subcommand name through `OsString`, so a caller// with a non-UTF-8 argv could in principle reach this path. We// construct the same `Vec<OsString>` shape directly.let bad_name = OsString::from_vec(vec![0xFF, 0xFE]);- let err = handle_external_command(vec![bad_name], None).unwrap_err();+ let err = handle_custom_command(vec![bad_name], None).unwrap_err();let msg = err.to_string();assert!(msg.contains("not valid UTF-8"),@@ -251,7 +251,7 @@ mod tests {#[cfg(unix)]#[test]- fn run_external_propagates_signal_exit_code() {+ fn run_custom_propagates_signal_exit_code() {use std::os::unix::fs::PermissionsExt;let dir = tempfile::tempdir().expect("create tempdir");@@ -263,7 +263,7 @@ mod tests {perms.set_mode(0o755);std::fs::set_permissions(&script, perms).expect("chmod script");- let err = run_external(&script, &[], None).expect_err("child killed by SIGTERM");+ let err = run_custom(&script, &[], None).expect_err("child killed by SIGTERM");let wt_err = err.downcast_ref::<WorktrunkError>().expect("signal should surface as WorktrunkError::AlreadyDisplayed");diff --git a/src/commands/mod.rs b/src/commands/mod.rsindex 1ec122ace..1364aec60 100644--- a/src/commands/mod.rs+++ b/src/commands/mod.rs@@ -5,8 +5,8 @@ pub(crate) mod commit;pub(crate) mod config;pub(crate) mod configure_shell;pub(crate) mod context;+pub(crate) mod custom;mod eval;-pub(crate) mod external;mod for_each;mod handle_switch;mod hook_commands;@@ -40,8 +40,8 @@ pub(crate) use config::{pub(crate) use configure_shell::{handle_configure_shell, handle_show_theme, handle_unconfigure_shell,};+pub(crate) use custom::handle_custom_command;pub(crate) use eval::step_eval;-pub(crate) use external::handle_external_command;pub(crate) use for_each::step_for_each;pub(crate) use handle_switch::{SwitchOptions, handle_switch};pub(crate) use hook_commands::{add_approvals, clear_approvals, handle_hook_show, run_hook};diff --git a/src/completion.rs b/src/completion.rsindex 33fbf84b6..aa5b1b3dc 100644--- a/src/completion.rs+++ b/src/completion.rs@@ -51,20 +51,20 @@ pub(crate) fn maybe_handle_env_completion() -> bool {return true;}- // If the subcommand word matches an external binary, forward the completion- // request to it (e.g., `wt sync --<tab>` → `wt-sync --<tab>`).+ // If the subcommand word matches a custom-subcommand binary, forward the+ // completion request to it (e.g., `wt sync --<tab>` → `wt-sync --<tab>`).// args[0] is the binary name ("wt"), args[1] is the subcommand ("sync").if args.len() >= 3 {let subcommand = args[1].to_string_lossy();- // Only forward to external binary if no built-in subcommand has this name.- // Built-ins always take precedence at runtime, so completions must agree.+ // Only forward to the custom binary if no built-in subcommand has this+ // name. Built-ins always take precedence at runtime, so completions+ // must agree.let binary = format!("wt-{subcommand}");if cli::build_command().find_subcommand(&*subcommand).is_none()&& which::which(&binary).is_ok(){- // Forward args[1..] to the external binary- if let Some(forwarded) =- forward_completion_to_external(&binary, &args[1..], &shell_name)+ // Forward args[1..] to the custom binary+ if let Some(forwarded) = forward_completion_to_custom(&binary, &args[1..], &shell_name){let _ = std::io::stdout().write_all(forwarded.as_bytes());CONTEXT.with(|ctx| ctx.borrow_mut().take());@@ -401,7 +401,7 @@ thread_local! {fn completion_command() -> Command {let cmd = cli::build_command();let cmd = inject_alias_subcommands(cmd);- let cmd = inject_external_subcommands(cmd);+ let cmd = inject_custom_subcommands(cmd);hide_non_positional_options_for_completion(cmd)}@@ -504,18 +504,14 @@ fn truncate_template(template: &str) -> &str {}}-/// Forward a completion request to an external `wt-*` binary.+/// Forward a completion request to a custom `wt-*` binary.////// Rebuilds the args as if the user invoked `wt-sync <rest>` directly, passing-/// the `COMPLETE` env var so the external binary generates completions.-fn forward_completion_to_external(- binary: &str,- args: &[OsString],- shell: &OsStr,-) -> Option<String> {- // Build args for the external binary: [binary_name, rest_args...]- let mut ext_args: Vec<OsString> = vec![OsString::from(binary)];- ext_args.extend_from_slice(&args[1..]);+/// the `COMPLETE` env var so the custom binary generates completions.+fn forward_completion_to_custom(binary: &str, args: &[OsString], shell: &OsStr) -> Option<String> {+ // Build args for the custom binary: [binary_name, rest_args...]+ let mut child_args: Vec<OsString> = vec![OsString::from(binary)];+ child_args.extend_from_slice(&args[1..]);// Adjust the completion index: subtract 1 since we removed the subcommand namelet index = std::env::var("_CLAP_COMPLETE_INDEX")@@ -525,7 +521,7 @@ fn forward_completion_to_external(let mut cmd = std::process::Command::new(binary);cmd.arg("--");- cmd.args(&ext_args);+ cmd.args(&child_args);cmd.env("COMPLETE", shell);cmd.env("_CLAP_IFS",@@ -535,7 +531,7 @@ fn forward_completion_to_external(cmd.env("_CLAP_COMPLETE_INDEX", idx.to_string());}- // Capture stdout from the external binary. Using std::process::Command+ // Capture stdout from the custom binary. Using std::process::Command// directly (not shell_exec::Cmd) because this runs during completion —// a short-lived subprocess where logging/tracing is unwanted.let result = cmd@@ -555,25 +551,25 @@ fn forward_completion_to_external(/// Discover `wt-*` executables on PATH and inject them as subcommands for completion.////// This mirrors git's approach: `wt sync` dispatches to `wt-sync`, and completions-/// should show `sync` as a subcommand. External subcommands that shadow built-in+/// should show `sync` as a subcommand. Custom subcommands that shadow built-in/// commands are skipped (built-ins always take precedence at runtime).-fn inject_external_subcommands(cmd: Command) -> Command {- inject_external_subcommand_list(cmd, discover_external_subcommands())+fn inject_custom_subcommands(cmd: Command) -> Command {+ inject_custom_subcommand_list(cmd, discover_custom_subcommands())}-/// Add discovered external subcommands to the completion command tree.+/// Add discovered custom subcommands to the completion command tree.///-/// Each external gets a stub `Command` with `allow_external_subcommands(true)` so+/// Each one gets a stub `Command` with `allow_external_subcommands(true)` so/// any trailing args are accepted without error. Built-in subcommands are never shadowed.-fn inject_external_subcommand_list(mut cmd: Command, externals: Vec<String>) -> Command {- for name in externals {+fn inject_custom_subcommand_list(mut cmd: Command, customs: Vec<String>) -> Command {+ for name in customs {if cmd.find_subcommand(&name).is_some() {continue;}// Leak is fine: completion is a short-lived subprocess that exits after// printing candidates (same pattern as inject_alias_subcommands).let name: &'static str = Box::leak(name.into_boxed_str());- let about: &'static str = Box::leak(format!("external: wt-{name}").into_boxed_str());+ let about: &'static str = Box::leak(format!("custom: wt-{name}").into_boxed_str());let sub = Command::new(name).about(about).allow_external_subcommands(true);@@ -583,17 +579,17 @@ fn inject_external_subcommand_list(mut cmd: Command, externals: Vec<String>) ->}/// Find `wt-*` executables on PATH, returning their subcommand names (without the `wt-` prefix).-fn discover_external_subcommands() -> Vec<String> {+fn discover_custom_subcommands() -> Vec<String> {let Some(path_var) = std::env::var_os("PATH") else {return Vec::new();};- discover_external_subcommands_in(&path_var)+ discover_custom_subcommands_in(&path_var)}/// Find `wt-*` executables in the given PATH value, returning subcommand names/// (without the `wt-` prefix). On Windows, executable extensions (.exe, .cmd, etc.)/// are stripped so that `wt-sync.exe` produces the subcommand name `sync`.-fn discover_external_subcommands_in(path_var: &OsStr) -> Vec<String> {+fn discover_custom_subcommands_in(path_var: &OsStr) -> Vec<String> {let mut seen = std::collections::HashSet::new();let mut result = Vec::new();@@ -718,14 +714,14 @@ mod tests {#[test]fn test_discover_empty_path() {- let result = discover_external_subcommands_in(OsStr::new(""));+ let result = discover_custom_subcommands_in(OsStr::new(""));assert!(result.is_empty());}#[test]fn test_discover_nonexistent_dir() {let result =- discover_external_subcommands_in(OsStr::new("/nonexistent/path/xxxxxxxx_wt_test"));+ discover_custom_subcommands_in(OsStr::new("/nonexistent/path/xxxxxxxx_wt_test"));assert!(result.is_empty());}@@ -741,7 +737,7 @@ mod tests {std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o755)).unwrap();}- let result = discover_external_subcommands_in(dir.path().as_os_str());+ let result = discover_custom_subcommands_in(dir.path().as_os_str());assert_eq!(result, vec!["alpha", "beta"]);}@@ -759,7 +755,7 @@ mod tests {std::fs::write(&noexec, "data").unwrap();std::fs::set_permissions(&noexec, std::fs::Permissions::from_mode(0o644)).unwrap();- let result = discover_external_subcommands_in(dir.path().as_os_str());+ let result = discover_custom_subcommands_in(dir.path().as_os_str());assert_eq!(result, vec!["exec"]);}@@ -777,7 +773,7 @@ mod tests {}let path = std::env::join_paths([dir1.path(), dir2.path()]).unwrap();- let result = discover_external_subcommands_in(&path);+ let result = discover_custom_subcommands_in(&path);assert_eq!(result, vec!["dup"]);}@@ -797,7 +793,7 @@ mod tests {std::fs::write(&other, "#!/bin/sh\n").unwrap();std::fs::set_permissions(&other, std::fs::Permissions::from_mode(0o755)).unwrap();- let result = discover_external_subcommands_in(dir.path().as_os_str());+ let result = discover_custom_subcommands_in(dir.path().as_os_str());assert!(result.is_empty());}@@ -814,17 +810,17 @@ mod tests {std::fs::set_permissions(&path, std::fs::Permissions::from_mode(0o755)).unwrap();}- let result = discover_external_subcommands_in(dir.path().as_os_str());+ let result = discover_custom_subcommands_in(dir.path().as_os_str());assert_eq!(result, vec!["apple", "mango", "zebra"]);}#[test]- fn test_inject_external_adds_subcommands() {+ fn test_inject_custom_adds_subcommands() {let cmd = Command::new("wt").subcommand(Command::new("switch")).subcommand(Command::new("list"));- let cmd = inject_external_subcommand_list(cmd, vec!["sync".into(), "deploy".into()]);+ let cmd = inject_custom_subcommand_list(cmd, vec!["sync".into(), "deploy".into()]);assert!(cmd.find_subcommand("sync").is_some());assert!(cmd.find_subcommand("deploy").is_some());@@ -833,30 +829,30 @@ mod tests {}#[test]- fn test_inject_external_skips_builtins() {+ fn test_inject_custom_skips_builtins() {let cmd = Command::new("wt").subcommand(Command::new("switch").about("built-in switch"));- let cmd = inject_external_subcommand_list(cmd, vec!["switch".into(), "sync".into()]);+ let cmd = inject_custom_subcommand_list(cmd, vec!["switch".into(), "sync".into()]);- // "switch" should still be the built-in, not the external+ // "switch" should still be the built-in, not the custom subcommandlet switch = cmd.find_subcommand("switch").unwrap();assert_eq!(switch.get_about().unwrap().to_string(), "built-in switch");- // "sync" should be added as external+ // "sync" should be added as a custom subcommandlet sync = cmd.find_subcommand("sync").unwrap();- assert!(sync.get_about().unwrap().to_string().contains("external"));+ assert!(sync.get_about().unwrap().to_string().contains("custom"));}#[test]- fn test_inject_external_empty_list() {+ fn test_inject_custom_empty_list() {let cmd = Command::new("wt").subcommand(Command::new("switch"));- let cmd = inject_external_subcommand_list(cmd, vec![]);+ let cmd = inject_custom_subcommand_list(cmd, vec![]);assert_eq!(cmd.get_subcommands().count(), 1);}#[test]- fn test_inject_external_allows_trailing_args() {+ fn test_inject_custom_allows_trailing_args() {let cmd = Command::new("wt");- let cmd = inject_external_subcommand_list(cmd, vec!["sync".into()]);+ let cmd = inject_custom_subcommand_list(cmd, vec!["sync".into()]);let sync = cmd.find_subcommand("sync").unwrap();assert!(sync.is_allow_external_subcommands_set());@@ -864,7 +860,7 @@ mod tests {#[test]fn test_forward_to_nonexistent_binary() {- let result = forward_completion_to_external(+ let result = forward_completion_to_custom("/nonexistent/binary/xxxxxxxx_wt_test",&[OsString::from("test")],OsStr::new("bash"),@@ -874,14 +870,14 @@ mod tests {#[cfg(unix)]#[test]- fn test_forward_to_external_binary() {+ fn test_forward_to_custom_binary() {use std::os::unix::fs::PermissionsExt;let dir = tempfile::tempdir().unwrap();let script = dir.path().join("wt-fake");std::fs::write(&script, "#!/bin/sh\nprintf '%s\\n%s' '--all' '--verbose'\n").unwrap();std::fs::set_permissions(&script, std::fs::Permissions::from_mode(0o755)).unwrap();- let result = forward_completion_to_external(+ let result = forward_completion_to_custom(script.to_str().unwrap(),&[OsString::from("fake"), OsString::from("--")],OsStr::new("bash"),@@ -901,7 +897,7 @@ mod tests {std::fs::write(&script, "#!/bin/sh\nexit 1\n").unwrap();std::fs::set_permissions(&script, std::fs::Permissions::from_mode(0o755)).unwrap();- let result = forward_completion_to_external(+ let result = forward_completion_to_custom(script.to_str().unwrap(),&[OsString::from("fail")],OsStr::new("bash"),diff --git a/src/main.rs b/src/main.rsindex aac373782..7c904c085 100644--- a/src/main.rs+++ b/src/main.rs@@ -49,7 +49,7 @@ use commands::{MergeOptions, OperationMode, RebaseResult, RemoveTarget, SquashResult, SwitchOptions,add_approvals, clear_approvals, handle_claude_install, handle_claude_install_statusline,handle_claude_uninstall, handle_completions, handle_config_create, handle_config_show,- handle_config_update, handle_configure_shell, handle_external_command, handle_hints_clear,+ handle_config_update, handle_configure_shell, handle_custom_command, handle_hints_clear,handle_hints_get, handle_hook_show, handle_init, handle_list, handle_logs_list, handle_merge,handle_opencode_install, handle_opencode_uninstall, handle_promote, handle_rebase,handle_show_theme, handle_squash, handle_state_clear, handle_state_clear_all, handle_state_get,@@ -1157,9 +1157,9 @@ fn dispatch_command(Commands::Remove(args) => handle_remove_command(args),Commands::Merge(args) => handle_merge_command(args),// `working_dir` is the top-level `-C <path>` flag, applied as the- // child's current directory so global `-C` works for external+ // child's current directory so global `-C` works for custom// subcommands the same way it does for built-ins.- Commands::External(args) => handle_external_command(args, working_dir),+ Commands::Custom(args) => handle_custom_command(args, working_dir),}}diff --git a/tests/integration_tests/completion.rs b/tests/integration_tests/completion.rsindex 4c57d25cf..8f835e193 100644--- a/tests/integration_tests/completion.rs+++ b/tests/integration_tests/completion.rs@@ -1710,7 +1710,7 @@ fn prepend_path(cmd: &mut std::process::Command, dir: &std::path::Path) {/// External `wt-*` binaries on PATH appear as subcommand completion candidates.#[rstest]-fn test_complete_external_subcommand_listed(repo: TestRepo) {+fn test_complete_custom_subcommand_listed(repo: TestRepo) {repo.commit("initial");// Create a mock wt-testext binary on PATH@@ -1719,7 +1719,7 @@ fn test_complete_external_subcommand_listed(repo: TestRepo) {.command("_default", MockResponse::output("external ran\n")).write(ext_dir.path());- // Complete "wt " — should include "testext" from the external binary+ // Complete "wt " — should include "testext" from the `wt-testext` binarylet mut cmd = repo.completion_cmd(&["wt", ""]);prepend_path(&mut cmd, ext_dir.path());cmd.env("MOCK_CONFIG_DIR", ext_dir.path());@@ -1729,7 +1729,7 @@ fn test_complete_external_subcommand_listed(repo: TestRepo) {assert!(stdout.contains("testext"),- "External subcommand 'testext' missing from completion output: {stdout}"+ "Custom subcommand 'testext' missing from completion output: {stdout}");// Built-in subcommands should still be presentassert!(@@ -1738,10 +1738,10 @@ fn test_complete_external_subcommand_listed(repo: TestRepo) {);}-/// Completion for an external subcommand's flags forwards to the external binary.+/// Completion for a custom subcommand's flags forwards to the `wt-*` binary.#[cfg(unix)]#[rstest]-fn test_complete_external_subcommand_forwards(repo: TestRepo) {+fn test_complete_custom_subcommand_forwards(repo: TestRepo) {use std::os::unix::fs::PermissionsExt;repo.commit("initial");diff --git a/tests/integration_tests/external.rs b/tests/integration_tests/custom.rssimilarity index 90%rename from tests/integration_tests/external.rsrename to tests/integration_tests/custom.rsindex 64269de0c..75b4a8d1c 100644--- a/tests/integration_tests/external.rs+++ b/tests/integration_tests/custom.rs@@ -1,4 +1,4 @@-//! Tests for git-style external subcommand dispatch (`wt-<name>`).+//! Tests for git-style custom subcommand dispatch (`wt-<name>`).use crate::common::{mock_commands::{MockConfig, MockResponse},@@ -34,13 +34,10 @@ fn mock_bin_dir(name: &str, response: MockResponse) -> TempDir {}#[test]-fn external_subcommand_runs_wt_prefixed_binary_on_path() {+fn custom_subcommand_runs_wt_prefixed_binary_on_path() {// `wt wt-test-extcmd-ok` should find `wt-wt-test-extcmd-ok` on PATH.// We use a deliberately unique name so host PATH pollution doesn't match.- let dir = mock_bin_dir(- "wt-wt-test-extcmd-ok",- MockResponse::output("external ran\n"),- );+ let dir = mock_bin_dir("wt-wt-test-extcmd-ok", MockResponse::output("custom ran\n"));let mut cmd = wt_command();prepend_path(&mut cmd, dir.path());@@ -53,14 +50,11 @@ fn external_subcommand_runs_wt_prefixed_binary_on_path() {"expected success, stderr: {}",String::from_utf8_lossy(&output.stderr));- assert_eq!(- String::from_utf8_lossy(&output.stdout).trim(),- "external ran"- );+ assert_eq!(String::from_utf8_lossy(&output.stdout).trim(), "custom ran");}#[test]-fn external_subcommand_not_found_prints_clap_error() {+fn custom_subcommand_not_found_prints_clap_error() {let mut cmd = wt_command();// Clear PATH so no `wt-*` binaries can be discovered, then add a single// empty dir so `which` has somewhere to look.@@ -84,7 +78,7 @@ fn external_subcommand_not_found_prints_clap_error() {}#[test]-fn external_subcommand_typo_suggests_closest_builtin() {+fn custom_subcommand_typo_suggests_closest_builtin() {let mut cmd = wt_command();let empty = TempDir::new().unwrap();cmd.env("PATH", empty.path());@@ -104,7 +98,7 @@ fn external_subcommand_typo_suggests_closest_builtin() {}#[test]-fn external_subcommand_nested_suggestion_wins_over_path_lookup() {+fn custom_subcommand_nested_suggestion_wins_over_path_lookup() {// `wt squash` should suggest `wt step squash` even though `wt-squash` is// not on PATH. The nested tip is layered on top of clap's standard// unrecognized-subcommand error.@@ -145,7 +139,7 @@ fn strip_ansi(s: &str) -> String {}#[test]-fn external_subcommand_propagates_exit_code() {+fn custom_subcommand_propagates_exit_code() {let dir = mock_bin_dir("wt-wt-test-extcmd-fail",MockResponse::exit(0).with_exit_code(42),@@ -163,7 +157,7 @@ fn external_subcommand_propagates_exit_code() {"expected exit code 42, stderr: {}",String::from_utf8_lossy(&output.stderr));- // When the external command fails, wt should NOT add its own error line —+ // When the custom command fails, wt should NOT add its own error line —// the child already reported whatever it needed to.let stderr = String::from_utf8_lossy(&output.stderr);assert!(@@ -173,7 +167,7 @@ fn external_subcommand_propagates_exit_code() {}#[test]-fn external_subcommand_respects_global_dash_c_flag() {+fn custom_subcommand_respects_global_dash_c_flag() {// `wt -C <dir> foo` should run `wt-foo` with `<dir>` as its cwd. We verify// by reading argv, not cwd, because MockResponse doesn't reflect cwd —// instead we run `pwd` via a shell wrapper using the `file` response. Too@@ -207,7 +201,7 @@ fn external_subcommand_respects_global_dash_c_flag() {}#[test]-fn external_subcommand_passes_help_flag_through() {+fn custom_subcommand_passes_help_flag_through() {// `wt foo --help` should hand `--help` to `wt-foo`, not to wt itself.// The mock-stub has no built-in `--help` handler, so if `--help` reaches// it the mock falls through to `_default` (which we set to exit 0).diff --git a/tests/integration_tests/mod.rs b/tests/integration_tests/mod.rsindex 933fbaf94..679815aa1 100644--- a/tests/integration_tests/mod.rs+++ b/tests/integration_tests/mod.rs@@ -23,6 +23,7 @@ pub mod config_show_theme;pub mod config_state;pub mod config_update_pty;pub mod configure_shell;+pub mod custom;pub mod default_branch;pub mod diagnostic;pub mod directives;@@ -30,7 +31,6 @@ pub mod doc_templates;pub mod e2e_shell;pub mod e2e_shell_post_start;pub mod eval;-pub mod external;pub mod for_each;pub mod git_error_display;pub mod help;diff --git a/tests/integration_tests/shell_wrapper.rs b/tests/integration_tests/shell_wrapper.rsindex c6b23b263..14fd651e3 100644--- a/tests/integration_tests/shell_wrapper.rs+++ b/tests/integration_tests/shell_wrapper.rs@@ -2971,7 +2971,7 @@ fi/// Creates a temp dir with a symlink to the `wt` binary, then builds PATH/// from that dir + system dirs (excluding cargo target directories). This/// prevents co-built binaries like `wt-perf` from leaking into completion- /// output as external subcommands.+ /// output as custom subcommands.////// NOTE: passing this via `.env("PATH", ...)` is not enough when spawning/// a shell whose startup files mutate PATH: a typical `~/.zshenv` sources@@ -3029,7 +3029,7 @@ _wt_lazy_complete);// Filter PATH to exclude cargo target directories so `wt-perf` (test- // helper) doesn't leak into completion output as an external subcommand.+ // helper) doesn't leak into completion output as a custom subcommand.let (_dir, clean_path) = completion_test_path(&wt_bin);// `-f` skips ~/.zshenv (which typically sources ~/.cargo/env and@@ -3129,15 +3129,15 @@ for c in "${{COMPREPLY[@]}}"; do echo "${{c%% *}}"; doneassert_snapshot!(completions);}- /// Shell integration test: completing an external subcommand's flags+ /// Shell integration test: completing a custom subcommand's flags/// forwards the request to the `wt-*` binary on PATH.////// Places a `wt-fake` script in the hermetic PATH, then triggers/// `wt fake --<tab>` via the fish completion protocol. Verifies that:- /// 1. The external script's output appears (forwarding works)+ /// 1. The `wt-fake` script's output appears (forwarding works)/// 2. `_CLAP_COMPLETE_INDEX` is decremented by 1 (index adjustment)#[test]- fn test_fish_completion_forwards_to_external() {+ fn test_fish_completion_forwards_to_custom() {use std::os::unix::fs::PermissionsExt;let wt_bin = wt_bin();let (dir, clean_path) = completion_test_path(&wt_bin);@@ -3167,7 +3167,7 @@ for c in "${{COMPREPLY[@]}}"; do echo "${{c%% *}}"; donelet stdout = String::from_utf8_lossy(&output.stdout);assert!(stdout.contains("--fake-flag"),- "Forwarded completions should include external script output: {stdout}"+ "Forwarded completions should include the `wt-fake` script output: {stdout}");assert!(stdout.contains("idx:1"),@@ -3175,13 +3175,13 @@ for c in "${{COMPREPLY[@]}}"; do echo "${{c%% *}}"; done);}- /// Shell integration test: bash completion forwards to external subcommands.+ /// Shell integration test: bash completion forwards to custom subcommands.////// Sources the real `wt config shell init bash` output, places a `wt-fake`/// script on the hermetic PATH, and triggers `wt fake --<tab>` through/// bash's completion machinery.#[test]- fn test_bash_completion_forwards_to_external() {+ fn test_bash_completion_forwards_to_custom() {use std::os::unix::fs::PermissionsExt;let wt_bin = wt_bin();let (dir, clean_path) = completion_test_path(&wt_bin);