Skip to content

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

chore(output): emit deprecation warning when only legacy directive var is set (#2880)

Worktrunk Botb5d85455ac7b
diff --git a/src/output/global.rs b/src/output/global.rs
index 75e94010b..31eab7b01 100644
--- a/src/output/global.rs
+++ b/src/output/global.rs
@@ -41,7 +41,8 @@
//! Users who upgrade wt without restarting their shell still run the previous
//! release's shell wrapper, which only sets `WORKTRUNK_DIRECTIVE_FILE`. When
//! only that variable is set, wt falls back to the pre-split protocol (shell
-//! commands written to the single file) silently. For bash, zsh, fish, and
+//! commands written to the single file) and emits a one-shot deprecation
+//! warning hinting at `wt config shell install`. For bash, zsh, fish, and
//! PowerShell a shell restart picks up the new wrapper automatically; nushell
//! is the only shell where users have to rerun `wt config shell install`
//! because its wrapper is a static file. Remove the legacy path in the next
@@ -270,23 +271,41 @@ fn compute_directive_mode() -> DirectiveMode {
exec_file: exec,
},
None => match legacy {
- // Silent fallback: bash/zsh/fish/PowerShell self-update on restart,
- // and nushell is the only shell that needs a manual reinstall. A
- // global "your wrapper is old" warning would hit everyone else with
- // noise they can't avoid until their next terminal restart.
- //
- // TODO(2026-05): emit a deprecation warning here. By then the
- // self-healing shells (bash/zsh/fish/PowerShell) have had a
- // release to cycle, so anything still hitting this branch is
- // almost certainly an outdated nushell wrapper whose user needs
- // to rerun `wt config shell install nu` before the legacy
- // fallback is removed in the following release.
- Some(file) => DirectiveMode::Legacy { file },
+ // Hitting this branch means the active shell wrapper still sets
+ // only `WORKTRUNK_DIRECTIVE_FILE` (pre-split protocol). bash, zsh,
+ // fish, and PowerShell wrappers self-update on shell restart, so
+ // any wt invocation still landing here is using an outdated
+ // wrapper — most often nushell, where the wrapper is a static
+ // file the user must reinstall via `wt config shell install`.
+ // Warn once per process so the user is prompted to refresh it
+ // before the legacy fallback is removed in a future release.
+ Some(file) => {
+ warn_legacy_directive();
+ DirectiveMode::Legacy { file }
+ }
None => DirectiveMode::Interactive,
},
}
}
+/// Warn that the active shell wrapper is using the pre-split directive-file
+/// protocol. The caller (`compute_directive_mode`) runs once per process from
+/// `OUTPUT_STATE.get_or_init`, so this naturally fires at most once.
+fn warn_legacy_directive() {
+ eprintln!(
+ "{}",
+ warning_message(cformat!(
+ "Shell wrapper uses the legacy directive-file protocol; it will be removed in a future release"
+ ))
+ );
+ eprintln!(
+ "{}",
+ hint_message(cformat!(
+ "To update, run <underline>wt config shell install</>"
+ ))
+ );
+}
+
/// Warn that `--execute` was refused because we're running inside an alias or
/// hook body with the EXEC file scrubbed. Fires at most once per process so
/// repeated refusals don't spam the terminal.
diff --git a/tests/snapshots/integration__integration_tests__directives__switch_legacy_directive_file.snap b/tests/snapshots/integration__integration_tests__directives__switch_legacy_directive_file.snap
index eecbd21b2..41c9177de 100644
--- a/tests/snapshots/integration__integration_tests__directives__switch_legacy_directive_file.snap
+++ b/tests/snapshots/integration__integration_tests__directives__switch_legacy_directive_file.snap
@@ -11,13 +11,19 @@ info:
COLUMNS: "500"
GIT_AUTHOR_DATE: "2025-01-01T00:00:00Z"
GIT_COMMITTER_DATE: "2025-01-01T00:00:00Z"
+ GIT_COMMON_DIR: ""
GIT_CONFIG_GLOBAL: "[TEST_GIT_CONFIG]"
GIT_CONFIG_SYSTEM: /dev/null
+ GIT_DIR: ""
GIT_EDITOR: ""
+ GIT_INDEX_FILE: ""
+ GIT_OBJECT_DIRECTORY: ""
GIT_TERMINAL_PROMPT: "0"
+ GIT_WORK_TREE: ""
HOME: "[TEST_HOME]"
LANG: C
LC_ALL: C
+ LLVM_PROFILE_FILE: "[LLVM_PROFILE_FILE]"
MOCK_CONFIG_DIR: "[MOCK_CONFIG_DIR]"
NO_COLOR: ""
OPENCODE_CONFIG_DIR: "[TEST_OPENCODE_CONFIG]"
@@ -31,13 +37,19 @@ info:
WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"
WORKTRUNK_DIRECTIVE_FILE: "[DIRECTIVE_FILE]"
WORKTRUNK_SYSTEM_CONFIG_PATH: "[TEST_SYSTEM_CONFIG]"
+ WORKTRUNK_TEST_BASH_INSTALLED: "0"
WORKTRUNK_TEST_CLAUDE_INSTALLED: "0"
+ WORKTRUNK_TEST_CODEX_INSTALLED: "0"
WORKTRUNK_TEST_DELAYED_STREAM_MS: "-1"
WORKTRUNK_TEST_EPOCH: "1735776000"
+ WORKTRUNK_TEST_FISH_INSTALLED: "0"
+ WORKTRUNK_TEST_GEMINI_INSTALLED: "0"
WORKTRUNK_TEST_NUSHELL_ENV: "0"
WORKTRUNK_TEST_OPENCODE_INSTALLED: "0"
WORKTRUNK_TEST_POWERSHELL_ENV: "0"
+ WORKTRUNK_TEST_POWERSHELL_INSTALLED: "0"
WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WORKTRUNK_TEST_ZSH_INSTALLED: "0"
XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
---
success: true
@@ -45,4 +57,6 @@ exit_code: 0
----- stdout -----
----- stderr -----
+▲ Shell wrapper uses the legacy directive-file protocol; it will be removed in a future release
+↳ To update, run wt config shell install
○ Switched to worktree for feature @ _REPO_.feature
diff --git a/tests/snapshots/integration__integration_tests__directives__switch_legacy_directive_file_fish.snap b/tests/snapshots/integration__integration_tests__directives__switch_legacy_directive_file_fish.snap
index a750ea054..18f013876 100644
--- a/tests/snapshots/integration__integration_tests__directives__switch_legacy_directive_file_fish.snap
+++ b/tests/snapshots/integration__integration_tests__directives__switch_legacy_directive_file_fish.snap
@@ -58,4 +58,6 @@ exit_code: 0
----- stdout -----
----- stderr -----
+▲ Shell wrapper uses the legacy directive-file protocol; it will be removed in a future release
+↳ To update, run wt config shell install
○ Switched to worktree for feature @ _REPO_.feature
diff --git a/tests/snapshots/integration__integration_tests__directives__switch_legacy_directive_file_powershell.snap b/tests/snapshots/integration__integration_tests__directives__switch_legacy_directive_file_powershell.snap
index 43c1b3619..bafda8789 100644
--- a/tests/snapshots/integration__integration_tests__directives__switch_legacy_directive_file_powershell.snap
+++ b/tests/snapshots/integration__integration_tests__directives__switch_legacy_directive_file_powershell.snap
@@ -11,13 +11,19 @@ info:
COLUMNS: "500"
GIT_AUTHOR_DATE: "2025-01-01T00:00:00Z"
GIT_COMMITTER_DATE: "2025-01-01T00:00:00Z"
+ GIT_COMMON_DIR: ""
GIT_CONFIG_GLOBAL: "[TEST_GIT_CONFIG]"
GIT_CONFIG_SYSTEM: /dev/null
+ GIT_DIR: ""
GIT_EDITOR: ""
+ GIT_INDEX_FILE: ""
+ GIT_OBJECT_DIRECTORY: ""
GIT_TERMINAL_PROMPT: "0"
+ GIT_WORK_TREE: ""
HOME: "[TEST_HOME]"
LANG: C
LC_ALL: C
+ LLVM_PROFILE_FILE: "[LLVM_PROFILE_FILE]"
MOCK_CONFIG_DIR: "[MOCK_CONFIG_DIR]"
NO_COLOR: ""
OPENCODE_CONFIG_DIR: "[TEST_OPENCODE_CONFIG]"
@@ -32,13 +38,19 @@ info:
WORKTRUNK_DIRECTIVE_FILE: "[DIRECTIVE_FILE]"
WORKTRUNK_SHELL: powershell
WORKTRUNK_SYSTEM_CONFIG_PATH: "[TEST_SYSTEM_CONFIG]"
+ WORKTRUNK_TEST_BASH_INSTALLED: "0"
WORKTRUNK_TEST_CLAUDE_INSTALLED: "0"
+ WORKTRUNK_TEST_CODEX_INSTALLED: "0"
WORKTRUNK_TEST_DELAYED_STREAM_MS: "-1"
WORKTRUNK_TEST_EPOCH: "1735776000"
+ WORKTRUNK_TEST_FISH_INSTALLED: "0"
+ WORKTRUNK_TEST_GEMINI_INSTALLED: "0"
WORKTRUNK_TEST_NUSHELL_ENV: "0"
WORKTRUNK_TEST_OPENCODE_INSTALLED: "0"
WORKTRUNK_TEST_POWERSHELL_ENV: "0"
+ WORKTRUNK_TEST_POWERSHELL_INSTALLED: "0"
WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WORKTRUNK_TEST_ZSH_INSTALLED: "0"
XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
---
success: true
@@ -46,4 +58,6 @@ exit_code: 0
----- stdout -----
----- stderr -----
+▲ Shell wrapper uses the legacy directive-file protocol; it will be removed in a future release
+↳ To update, run wt config shell install
○ Switched to worktree for feature @ _REPO_.feature
diff --git a/tests/snapshots/integration__integration_tests__directives__switch_legacy_directive_file_with_execute.snap b/tests/snapshots/integration__integration_tests__directives__switch_legacy_directive_file_with_execute.snap
index a79a59bc1..added5fe2 100644
--- a/tests/snapshots/integration__integration_tests__directives__switch_legacy_directive_file_with_execute.snap
+++ b/tests/snapshots/integration__integration_tests__directives__switch_legacy_directive_file_with_execute.snap
@@ -62,6 +62,8 @@ exit_code: 0
----- stderr -----
▲ --execute will change in a future release: it will run a single program, with arguments after --, not a shell command line
↳ Comment at https://github.com/max-sixty/worktrunk/issues/2860 if the new single-program form would make a workflow worse; to run this command line unchanged, pass it to a shell: --execute sh -- -c 'echo hello'
+▲ Shell wrapper uses the legacy directive-file protocol; it will be removed in a future release
+↳ To update, run wt config shell install
✓ Created branch exec-legacy from main and worktree @ _REPO_.exec-legacy
↳ To customize worktree locations, run wt config create
◎ Executing (--execute):