Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
//! Shell integration for worktrunk.
//!
//! This module provides:
//! - Shell detection and configuration path discovery
//! - Shell integration line detection for config files
//! - Shell initialization code generation (bash, zsh, fish, nushell, powershell)
mod detection;
mod paths;
mod utils;
use askama::Template;
// Re-export public types and functions
pub use detection::{
BypassAlias, DetectedLine, FileDetectionResult,
is_shell_integration_line_for_uninstall_any_cmd, scan_for_detection_details, shell_integration,
};
pub use paths::{
fish_completion_path, fish_config_dir, home_dir_required, line_based_config_paths,
nushell_autoload_candidates, profile_query_interruption,
};
pub use utils::{
AncestorShell, ZshStartupScope, ancestor_shell, current_shell, current_shell_name,
extract_filename_from_path, probe_zsh_compdef,
};
/// Validate a command name before embedding it in shell syntax or shell-owned paths.
pub fn validate_shell_command_name(cmd: &str) -> Result<(), String> {
if cmd.is_empty() {
return Err("Invalid shell integration command name: command name cannot be empty".into());
}
if cmd.starts_with('-') {
return Err(
"Invalid shell integration command name: command name cannot start with '-'".into(),
);
}
if !cmd
.bytes()
.all(|b| b.is_ascii_alphanumeric() || matches!(b, b'.' | b'_' | b'-'))
{
return Err(
"Invalid shell integration command name: use only ASCII letters, numbers, '.', '_', and '-'"
.into(),
);
}
Ok(())
}
/// Supported shells
///
/// Currently supported: bash, fish, nushell (experimental), zsh, powershell
///
/// On Windows, Git Bash users should use `bash` for shell integration.
/// PowerShell integration is available for native Windows users without Git Bash.
#[derive(Debug, Clone, Copy, PartialEq, Eq, strum::Display, strum::EnumString)]
#[cfg_attr(feature = "cli", derive(clap::ValueEnum))]
#[strum(serialize_all = "kebab-case", ascii_case_insensitive)]
pub enum Shell {
Bash,
Fish,
#[strum(serialize = "nu")]
#[cfg_attr(feature = "cli", clap(name = "nu"))]
Nushell,
Zsh,
#[strum(serialize = "powershell")]
#[cfg_attr(feature = "cli", clap(name = "powershell"))]
PowerShell,
}
impl Shell {
/// All supported shells, in the order `wt config shell install` /
/// `uninstall` scan them. The single source for that scan list.
pub fn all() -> Vec<Shell> {
vec![
Shell::Bash,
Shell::Zsh,
Shell::Fish,
Shell::Nushell,
Shell::PowerShell,
]
}
/// Whether this shell uses a standalone wrapper file as integration.
///
/// Wrapper-based shells (Fish, Nushell) install a complete function file that the shell
/// autoloads. The file itself IS the integration. Eval-based shells (Bash, Zsh, PowerShell)
/// add an `eval`/`source` line to an existing config file like `.bashrc`.
///
/// This distinction matters for:
/// - Installation: wrapper files are written whole; eval lines are appended
/// - Detection: wrapper file presence = confirmed integration, even if outdated
pub fn is_wrapper_based(&self) -> bool {
matches!(self, Self::Fish | Self::Nushell)
}
/// Whether this shell's binary is available on the system (in `$PATH`).
///
/// Used to suppress "Skipped" entries in `wt config show` and `wt config shell install`
/// for shells the user doesn't have installed (e.g., `nu`, `fish` on a stock zsh-only Mac).
/// PATH lookup is the cheapest reliable signal that doesn't depend on rc-file conventions.
///
/// Note: `bash` and `zsh` are preinstalled on macOS, so this returns true even when the
/// user never uses them. The skipped-entry filter still works because shells with rc files
/// land in `configured` rather than `skipped`.
pub fn is_installed(&self) -> bool {
// Allow tests to override detection. The Nushell variable retains its
// historical name (`_ENV`) to avoid churning hundreds of recorded
// snapshots; semantically it matches the others.
//
// Tests always set these via STATIC_TEST_ENV_VARS, so the `which::which`
// fallback is the production-only path — exercised on real users'
// machines, not in CI. The same pattern existed in the prior
// `is_nushell_available()` helper without dedicated coverage.
let env_var = match self {
Self::Bash => "WORKTRUNK_TEST_BASH_INSTALLED",
Self::Zsh => "WORKTRUNK_TEST_ZSH_INSTALLED",
Self::Fish => "WORKTRUNK_TEST_FISH_INSTALLED",
Self::Nushell => "WORKTRUNK_TEST_NUSHELL_ENV",
Self::PowerShell => "WORKTRUNK_TEST_POWERSHELL_INSTALLED",
};
if let Ok(val) = std::env::var(env_var) {
return val == "1";
}
let binaries: &[&str] = match self {
Self::Bash => &["bash"],
Self::Zsh => &["zsh"],
Self::Fish => &["fish"],
Self::Nushell => &["nu"],
Self::PowerShell => &["pwsh", "powershell"],
};
binaries.iter().any(|b| which::which(b).is_ok())
}
/// Returns the config file paths for this shell.
///
/// The `cmd` parameter affects the Fish functions filename (e.g., `wt.fish` or `git-wt.fish`).
/// Returns paths in order of preference. The first existing file should be used.
pub fn config_paths(&self, cmd: &str) -> Result<Vec<std::path::PathBuf>, std::io::Error> {
paths::config_paths(*self, cmd)
}
/// Returns the legacy fish conf.d path for cleanup purposes.
///
/// Previously, fish shell integration was installed to `~/.config/fish/conf.d/{cmd}.fish`.
/// This caused issues with Homebrew PATH setup (see issue #566). We now install to
/// `functions/{cmd}.fish` instead. This method returns the legacy path so install/uninstall
/// can clean it up.
pub fn legacy_fish_conf_d_path(cmd: &str) -> Result<std::path::PathBuf, std::io::Error> {
paths::legacy_fish_conf_d_path(cmd)
}
/// Returns the line to add to the config file for shell integration.
///
/// The `cmd` parameter specifies the command name (e.g., `wt` or `git-wt`).
/// All shells use a conditional wrapper to avoid errors when the command doesn't exist.
///
/// `cmd` must already be validated by [`validate_shell_command_name`]; command
/// entry points (`handle_init`, `handle_configure_shell`) validate at the edge.
///
/// Note: The generated line does not include `--cmd` because `binary_name()` already
/// detects the command name from argv\[0\] at runtime.
pub fn config_line(&self, cmd: &str) -> String {
match self {
Self::Bash | Self::Zsh => {
format!(
"if command -v {cmd} >/dev/null 2>&1; then eval \"$(command {cmd} config shell init {})\"; fi",
self
)
}
Self::Fish => {
format!(
"if type -q {cmd}; command {cmd} config shell init {} | source; end",
self
)
}
Self::Nushell => {
format!(
"if (which {cmd} | is-not-empty) {{ {cmd} config shell init nu | save --force ($nu.vendor-autoload-dirs | last | path join {cmd}.nu) }}",
)
}
Self::PowerShell => {
// Note: `| Out-String` is required because PowerShell command output is an array
// of strings by default, but Invoke-Expression expects a single string.
// Without it, Invoke-Expression fails with "Cannot convert 'System.Object[]'"
format!(
"if (Get-Command {cmd} -ErrorAction SilentlyContinue) {{ Invoke-Expression (& {cmd} config shell init powershell | Out-String) }}",
)
}
}
}
}
/// Shell integration configuration
pub struct ShellInit {
pub shell: Shell,
pub cmd: String,
}
impl ShellInit {
/// `cmd` must already be validated by [`validate_shell_command_name`]; command
/// entry points (`handle_init`, `handle_configure_shell`) validate at the edge.
pub fn with_prefix(shell: Shell, cmd: String) -> Self {
Self { shell, cmd }
}
/// Generate shell integration code (for `wt config shell init`)
pub fn generate(&self) -> Result<String, askama::Error> {
match self.shell {
Shell::Bash => {
let template = BashTemplate {
shell_name: self.shell.to_string(),
cmd: &self.cmd,
cmd_ident: clap_completer_ident(&self.cmd),
};
template.render()
}
Shell::Zsh => {
let template = ZshTemplate {
cmd: &self.cmd,
cmd_ident: clap_completer_ident(&self.cmd),
};
template.render()
}
Shell::Fish => {
let template = FishTemplate { cmd: &self.cmd };
template.render()
}
Shell::Nushell => {
let template = NushellTemplate { cmd: &self.cmd };
template.render()
}
Shell::PowerShell => {
let template = PowerShellTemplate { cmd: &self.cmd };
template.render()
}
}
}
/// Generate fish wrapper code (for `wt config shell install fish`)
///
/// This generates a minimal wrapper that sources the full function from the binary.
/// The wrapper file itself is static, but it loads the init output at runtime,
/// so users get updated behavior without reinstalling.
pub fn generate_fish_wrapper(&self) -> Result<String, askama::Error> {
let template = FishWrapperTemplate { cmd: &self.cmd };
template.render()
}
}
/// Suffix of the completer function clap names its registration script after.
///
/// clap builds it as `<prefix><command name with '-' replaced by '_'>`
/// (`_clap_complete_git_wt`, `_clap_dynamic_completer_git_wt`), so the lazy
/// loader in the bash and zsh templates has to apply the same escaping to guard
/// on and call the function the registration actually defines. The registration
/// is emitted under this command name via `WORKTRUNK_COMPLETE_NAME`, which the
/// templates set on the eval — see `registration_name` in `src/completion.rs`.
///
/// This is the one place the rule is encoded: `make_zsh_autoload_safe` in
/// `src/commands/init.rs` rewrites the same function name in clap's zsh
/// registration and calls here for it, so a change to clap's escaping is one
/// edit rather than two sites that can drift apart silently.
pub fn clap_completer_ident(cmd: &str) -> String {
cmd.replace('-', "_")
}
/// Bash shell template
#[derive(Template)]
#[template(path = "bash.sh", escape = "none")]
struct BashTemplate<'a> {
shell_name: String,
cmd: &'a str,
cmd_ident: String,
}
/// Zsh shell template
#[derive(Template)]
#[template(path = "zsh.zsh", escape = "none")]
struct ZshTemplate<'a> {
cmd: &'a str,
cmd_ident: String,
}
/// Fish shell template (full function for `wt config shell init fish`)
#[derive(Template)]
#[template(path = "fish.fish", escape = "none")]
struct FishTemplate<'a> {
cmd: &'a str,
}
/// Fish wrapper template (minimal wrapper for `functions/wt.fish`)
///
/// This wrapper is autoloaded by fish and sources the full function from the binary.
/// Unlike the full FishTemplate, this allows updates to worktrunk to automatically
/// provide the latest wrapper logic without requiring `wt config shell install`.
#[derive(Template)]
#[template(path = "fish_wrapper.fish", escape = "none")]
struct FishWrapperTemplate<'a> {
cmd: &'a str,
}
/// Nushell template
#[derive(Template)]
#[template(path = "nushell.nu", escape = "none")]
struct NushellTemplate<'a> {
cmd: &'a str,
}
/// PowerShell template
#[derive(Template)]
#[template(path = "powershell.ps1", escape = "none")]
struct PowerShellTemplate<'a> {
cmd: &'a str,
}
#[cfg(test)]
mod tests {
use super::*;
use rstest::rstest;
#[test]
fn test_shell_from_str() {
assert!(matches!("bash".parse::<Shell>(), Ok(Shell::Bash)));
assert!(matches!("BASH".parse::<Shell>(), Ok(Shell::Bash)));
assert!(matches!("fish".parse::<Shell>(), Ok(Shell::Fish)));
assert!(matches!("zsh".parse::<Shell>(), Ok(Shell::Zsh)));
assert!(matches!(
"powershell".parse::<Shell>(),
Ok(Shell::PowerShell)
));
assert!(matches!(
"POWERSHELL".parse::<Shell>(),
Ok(Shell::PowerShell)
));
assert!("invalid".parse::<Shell>().is_err());
}
#[test]
fn test_shell_display() {
assert_eq!(Shell::Bash.to_string(), "bash");
assert_eq!(Shell::Fish.to_string(), "fish");
assert_eq!(Shell::Zsh.to_string(), "zsh");
assert_eq!(Shell::PowerShell.to_string(), "powershell");
}
#[test]
fn test_shell_config_line() {
insta::assert_snapshot!("config_line_bash", Shell::Bash.config_line("wt"));
insta::assert_snapshot!("config_line_zsh", Shell::Zsh.config_line("wt"));
insta::assert_snapshot!("config_line_fish", Shell::Fish.config_line("wt"));
insta::assert_snapshot!("config_line_nu", Shell::Nushell.config_line("wt"));
insta::assert_snapshot!(
"config_line_powershell",
Shell::PowerShell.config_line("wt")
);
}
#[test]
fn test_config_line_uses_custom_prefix() {
// When using a custom prefix, the generated shell config line must use that prefix
// throughout - both in the command check AND the command invocation.
// This prevents the bug where we check for `git-wt` but then call `wt`.
insta::assert_snapshot!("config_line_bash_custom", Shell::Bash.config_line("git-wt"));
insta::assert_snapshot!("config_line_zsh_custom", Shell::Zsh.config_line("git-wt"));
insta::assert_snapshot!("config_line_fish_custom", Shell::Fish.config_line("git-wt"));
insta::assert_snapshot!(
"config_line_nu_custom",
Shell::Nushell.config_line("git-wt")
);
insta::assert_snapshot!(
"config_line_powershell_custom",
Shell::PowerShell.config_line("git-wt")
);
}
#[test]
fn test_shell_init_generate() {
for shell in [
Shell::Bash,
Shell::Zsh,
Shell::Fish,
Shell::Nushell,
Shell::PowerShell,
] {
let init = ShellInit::with_prefix(shell, "wt".to_string());
let output = init.generate().expect("Failed to generate");
insta::assert_snapshot!(format!("init_{shell}"), output);
}
}
#[test]
fn test_fish_init_uses_builtin_cd() {
// Regression test for #3159: the fish integration must change directory
// with `builtin cd`, not a bare `cd`. A bare `cd` is interceptable by
// shell `cd` overrides (e.g. the zoxide.fish plugin replaces `cd` with
// a zoxide query function). When wt called `cd -- "$target"`, zoxide
// saw `--` as a query argument and failed with "no match found". Using
// `builtin cd` bypasses any user `cd` function, matching bash and zsh.
let output = ShellInit::with_prefix(Shell::Fish, "wt".to_string())
.generate()
.expect("Failed to generate fish init");
assert!(
output.contains("builtin cd"),
"fish init must use `builtin cd` to bypass shell `cd` overrides; got:\n{output}"
);
assert!(
!output.contains("\n cd -- "),
"fish init must not use a bare `cd` that shell overrides can intercept; got:\n{output}"
);
}
#[test]
fn test_fish_wrapper_guards_completion_mode() {
// Regression for #3240: the lazy-load wrapper stub must short-circuit
// when COMPLETE is set, calling the binary directly rather than falling
// through to `wt config shell init fish | source` and the trailing
// `wt $argv` self-call. Without the guard, a stale third-party
// completion that invokes the bare `wt` command (e.g. an old Homebrew
// vendor_completions.d/wt.fish) re-enters the stub and recurses to
// fish's call-stack limit. Mirrors the bash/zsh COMPLETE guard.
let wrapper = ShellInit::with_prefix(Shell::Fish, "wt".to_string())
.generate_fish_wrapper()
.expect("Failed to generate fish wrapper");
assert!(
wrapper.contains("set -q COMPLETE"),
"fish wrapper must guard completion mode to avoid recursion (#3240); got:\n{wrapper}"
);
// The guard must precede the re-sourcing self-call so completion never
// reaches it.
let guard = wrapper
.find("set -q COMPLETE")
.expect("guard present per assertion above");
let resource = wrapper
.find("config shell init fish | source")
.expect("wrapper sources the full integration");
assert!(
guard < resource,
"the COMPLETE guard must come before the re-sourcing self-call; got:\n{wrapper}"
);
}
#[test]
fn test_shell_config_paths_returns_paths() {
// Shells whose paths don't depend on querying an installed shell.
// Nushell and Unix PowerShell paths come from `nu` and `pwsh`, and are
// empty without them.
let shells = [Shell::Bash, Shell::Zsh, Shell::Fish];
for shell in shells {
let result = shell.config_paths("wt");
assert!(result.is_ok(), "Failed to get config paths for {:?}", shell);
let paths = result.unwrap();
assert!(
!paths.is_empty(),
"No config paths returned for {:?}",
shell
);
}
}
#[test]
fn test_shell_config_paths_with_custom_prefix() {
// Test that custom prefix affects the paths where appropriate
let prefix = "custom-wt";
// Fish config path should include prefix in filename
let fish_paths = Shell::Fish.config_paths(prefix).unwrap();
assert!(
fish_paths[0]
.file_name()
.and_then(|n| n.to_str())
.is_some_and(|n| n.contains("custom-wt.fish")),
"Fish config should include prefix in filename"
);
// Bash and Zsh config paths are fixed (not affected by prefix)
let bash_paths = Shell::Bash.config_paths(prefix).unwrap();
assert!(
bash_paths[0]
.file_name()
.and_then(|n| n.to_str())
.is_some_and(|n| n.contains(".bashrc")),
"Bash config should be .bashrc"
);
let zsh_paths = Shell::Zsh.config_paths(prefix).unwrap();
assert!(
zsh_paths[0]
.file_name()
.and_then(|n| n.to_str())
.is_some_and(|n| n.contains(".zshrc")),
"Zsh config should be .zshrc"
);
}
#[test]
fn test_fish_completion_path_with_custom_prefix() {
let fish_path = fish_completion_path("my-prefix").unwrap();
assert!(
fish_path.ends_with("completions/my-prefix.fish"),
"{fish_path:?}"
);
}
#[test]
fn test_shell_init_with_custom_prefix() {
let init = ShellInit::with_prefix(Shell::Bash, "custom".to_string());
insta::assert_snapshot!(init.generate().expect("Should generate with custom prefix"));
}
#[rstest]
#[case("wt")]
#[case("git-wt")]
#[case("my.app_1")]
fn test_validate_shell_command_name_accepts_safe_names(#[case] cmd: &str) {
assert!(validate_shell_command_name(cmd).is_ok());
}
#[rstest]
#[case("")]
#[case("-wt")]
#[case("wt; touch")]
#[case("wt touch")]
#[case("wt/touch")]
#[case("wt\\touch")]
#[case("wt\ntouch")]
#[case("wt'touch")]
#[case("wüt")]
fn test_validate_shell_command_name_rejects_shell_syntax(#[case] cmd: &str) {
assert!(validate_shell_command_name(cmd).is_err());
}
/// Verify that `config_line()` generates lines that
/// `shell_integration()` can detect.
///
/// This prevents install and detection from drifting out of sync.
#[rstest]
fn test_config_line_detected_by_shell_integration(
#[values(
Shell::Bash,
Shell::Zsh,
Shell::Fish,
Shell::Nushell,
Shell::PowerShell
)]
shell: Shell,
#[values("wt", "git-wt", "my.tool_1", "git-wt.exe")] prefix: &str,
) {
let line = shell.config_line(prefix);
assert_eq!(
shell_integration(&line, prefix.trim_end_matches(".exe")),
Some(shell)
);
assert_eq!(shell_integration(&line, prefix), Some(shell));
assert!(is_shell_integration_line_for_uninstall_any_cmd(&line));
assert_eq!(shell_integration(&line, "other"), None);
}
// PowerShell config_line evaluation test is in tests/integration_tests/shell_powershell.rs
// because it needs CARGO_BIN_EXE_wt which is only available in integration tests.
}