Skip to content

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.md
index 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 | sani
Run 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.md
index 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 setup
diff --git a/skills/worktrunk/reference/extending.md b/skills/worktrunk/reference/extending.md
index 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 | sani
Run 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 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/skills/worktrunk/reference/faq.md b/skills/worktrunk/reference/faq.md
index 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 setup
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index 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 merge
action: 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.rs
index 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.rs
similarity index 89%
rename from src/commands/external.rs
rename to src/commands/custom.rs
index 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.rs
index 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.rs
index 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 name
let 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 subcommand
let 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 subcommand
let 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.rs
index 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.rs
index 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` binary
let 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 present
assert!(
@@ -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.rs
similarity index 90%
rename from tests/integration_tests/external.rs
rename to tests/integration_tests/custom.rs
index 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.rs
index 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.rs
index 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%% *}}"; done
assert_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%% *}}"; done
let 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);