Skip to content

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

docs(shell): correct who reads is_shell_integration_line (#4232)

Worktrunk Bot22bd6beba449
diff --git a/src/shell/detection.rs b/src/shell/detection.rs
index 0bd8a5ef7..0a7b383a0 100644
--- a/src/shell/detection.rs
+++ b/src/shell/detection.rs
@@ -65,25 +65,49 @@ use super::paths::{home_dir_required, powershell_profile_paths, zsh_config_dir};
/// # Usage
///
/// Used by:
-/// - `Shell::is_shell_configured()` - detect "configured but not restarted" state
-/// - `uninstall` - identify lines to remove from shell config
-/// - `wt config show` - display shell integration status
+/// - `Shell::is_shell_configured()` - detect the "configured but not restarted"
+/// state behind the shell-integration warnings
+/// - `wt config show` - render the matched integration line, and report a line
+/// that names the command but did not match as a possible false negative
+/// - `contains_shell_integration` - the install scan's idempotency check, which
+/// decides whether an rc file already carries this shell's line. It runs
+/// under `scan_shell_configs`, so three commands read it: `wt config shell
+/// install` skips the append when it answers yes, and `wt config show`'s
+/// per-shell rows and `wt switch`'s first-run integration offer read the same
+/// answer without writing
+///
+/// Not by uninstall, which reads
+/// [`is_shell_integration_line_for_uninstall_any_cmd`] instead: it asks only
+/// whether a line is worktrunk's, whatever binary name it was installed under.
///
/// # Impact of False Negatives
///
-/// Detection is ONLY used when shell integration is NOT active (i.e., user ran
-/// the binary directly without the shell wrapper). Once the shell wrapper is
-/// active (after shell restart), `WORKTRUNK_DIRECTIVE_CD_FILE` is set and no
-/// detection is needed.
+/// The messaging cases are benign, but they are not all gated the same way.
+/// `Shell::is_shell_configured()`'s callers ask only when shell integration is
+/// NOT active (i.e., user ran the binary directly without the shell wrapper);
+/// once the wrapper is active, `WORKTRUNK_DIRECTIVE_CD_FILE` is set and they
+/// stop asking.
///
/// **When binary is run directly (wrapper not active):**
/// - If detection finds integration → "installed but not active" (restart hint)
/// - If detection misses (false negative) → "shell integration not installed"
///
-/// **When wrapper is active:** No warnings shown regardless of detection.
+/// **When wrapper is active:** none of those warnings are shown, regardless of
+/// detection.
+///
+/// `wt config show` is not gated that way — it scans on every run, so a line
+/// that names the command but doesn't match is reported as a possible false
+/// negative whether or not the wrapper is active. That is still messaging, but
+/// it is a warning the user sees rather than silence.
///
-/// This means false negatives only cause incorrect messaging in `wt config show`
-/// and when users run the binary directly before restarting their shell.
+/// Install is the case that isn't benign: a miss there reads an
+/// already-configured rc file as unconfigured and appends a second copy of the
+/// line. `wt switch`'s offer reaches that same write by a longer route — a miss
+/// makes it offer an install the user doesn't need, and accepting appends the
+/// duplicate. Uninstall removes every line it matches, so the duplicate is not
+/// stranded — but this is a write to a user-owned file rather than a message,
+/// which is why the bar for a change here is higher than the messaging cases
+/// alone would set it.
pub fn is_shell_integration_line(line: &str, cmd: &str) -> bool {
has_init_invocation(line_code_portion(line), cmd)
}