Skip to content

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

feat: add hint for explicit path invocation with shell integration (#721)

Maximilian Roos6874e9856444
diff --git a/src/output/handlers.rs b/src/output/handlers.rs
index ba956940a..292e69052 100644
--- a/src/output/handlers.rs
+++ b/src/output/handlers.rs
@@ -22,7 +22,8 @@ use worktrunk::styling::{
};
use super::shell_integration::{
- compute_shell_warning_reason, git_subcommand_warning, shell_integration_hint,
+ compute_shell_warning_reason, explicit_path_hint, git_subcommand_warning,
+ shell_integration_hint, should_show_explicit_path_hint,
};
/// Format a switch message based on what was created
@@ -254,7 +255,12 @@ fn print_switch_message_if_changed(
super::print(warning_message(cformat!(
"Cannot change directory — {reason}"
)))?;
- super::print(hint_message(shell_integration_hint()))?;
+ // Show appropriate hint based on invocation mode
+ if should_show_explicit_path_hint() {
+ super::print(hint_message(explicit_path_hint(&dest_branch)))?;
+ } else {
+ super::print(hint_message(shell_integration_hint()))?;
+ }
}
Ok(())
}
@@ -343,10 +349,12 @@ pub fn handle_switch_output(
super::print(warning_message(cformat!(
"Worktree for <bold>{branch}</> @ <bold>{path_display}</>, but cannot change directory — {reason}"
)))?;
- // Show git subcommand hint if running as git wt
+ // Show appropriate hint based on invocation mode
// (regular shell integration hint is shown by prompt_shell_integration in main.rs)
if is_git_subcommand {
super::print(hint_message(git_subcommand_warning()))?;
+ } else if should_show_explicit_path_hint() {
+ super::print(hint_message(explicit_path_hint(branch)))?;
}
// User won't be there - show path in hook announcements
Some(path.clone())
@@ -403,10 +411,12 @@ pub fn handle_switch_output(
super::print(warning_message(cformat!(
"Cannot change directory — {reason}"
)))?;
- // Show git subcommand hint if running as git wt
+ // Show appropriate hint based on invocation mode
// (regular shell integration hint is shown by prompt_shell_integration in main.rs)
if is_git_subcommand {
super::print(hint_message(git_subcommand_warning()))?;
+ } else if should_show_explicit_path_hint() {
+ super::print(hint_message(explicit_path_hint(branch)))?;
}
// User won't be there - show path in hook announcements
Some(path.clone())
diff --git a/src/output/shell_integration.rs b/src/output/shell_integration.rs
index cdb76c652..2c1720327 100644
--- a/src/output/shell_integration.rs
+++ b/src/output/shell_integration.rs
@@ -10,7 +10,7 @@
//! |-----------|---------|------|
//! | Not installed | `Worktree for X @ path, but cannot change directory — shell integration not installed` | `To enable automatic cd, run wt config shell install` |
//! | Needs restart | `Worktree for X @ path, but cannot change directory — shell requires restart` | `Restart shell to activate shell integration` |
-//! | Explicit path | `Worktree for X @ path, but cannot change directory — ran ./wt; shell integration wraps wt` | (none) |
+//! | Explicit path | `Worktree for X @ path, but cannot change directory — ran ./wt; shell integration wraps wt` | `To change directory, run wt switch X` |
//! | Git subcommand | `Worktree for X @ path, but cannot change directory — ran git wt; running through git prevents cd` | `Use git-wt directly (via shell function) for automatic cd` |
//!
//! ## Switch to New Worktree (`wt switch --create X`)
@@ -21,6 +21,7 @@
//! |-----------|---------|---------|------|
//! | Shell active | `Created new worktree for X from base @ path` | (none) | (none) |
//! | Not installed | `Created new worktree for X from base @ path` | `Cannot change directory — shell integration not installed` | `To enable automatic cd, run wt config shell install` |
+//! | Explicit path | `Created new worktree for X from base @ path` | `Cannot change directory — ran ./wt; shell integration wraps wt` | `To change directory, run wt switch X` |
//! | Git subcommand | `Created new worktree for X from base @ path` | `Cannot change directory — ran git wt; running through git prevents cd` | `Use git-wt directly (via shell function) for automatic cd` |
//!
//! ## After Merge/Remove (switching to main worktree)
@@ -29,6 +30,7 @@
//! |-----------|---------|------|
//! | Shell active | (info) `Switched to worktree for main @ path` | (none) |
//! | Git subcommand | `Cannot change directory — ran git wt; running through git prevents cd` | `Use git-wt directly (via shell function) for automatic cd` |
+//! | Explicit path | `Cannot change directory — ran ./wt; shell integration wraps wt` | `To change directory, run wt switch main` |
//! | Other | `Cannot change directory — {reason}` | `To enable automatic cd, run wt config shell install` |
//!
//! ## Prompt Decision Flow
@@ -93,6 +95,23 @@ pub(crate) fn git_subcommand_warning() -> String {
)
}
+/// Hint when shell integration IS configured but user ran an explicit path.
+/// Suggests using the shell-wrapped command for automatic cd.
+pub(crate) fn explicit_path_hint(branch: &str) -> String {
+ let wraps = crate::binary_name();
+ cformat!("To change directory, run <bright-black>{wraps} switch {branch}</>")
+}
+
+/// Check if we should show the explicit path hint.
+/// True when: explicit path invocation AND shell integration IS configured.
+pub(crate) fn should_show_explicit_path_hint() -> bool {
+ crate::was_invoked_with_explicit_path()
+ && Shell::is_integration_configured(&crate::binary_name())
+ .ok()
+ .flatten()
+ .is_some()
+}
+
/// Compute the shell warning reason for display in messages.
///
/// Returns a reason string explaining why shell integration isn't working.
@@ -488,4 +507,13 @@ mod tests {
let reason = compute_shell_warning_reason_inner(true, false, "wt", "wt");
assert_eq!(reason, "shell requires restart");
}
+
+ #[test]
+ fn test_explicit_path_hint_format() {
+ // Verify hint contains the branch name and "switch" command
+ let hint = explicit_path_hint("feature-branch");
+ assert!(hint.contains("switch"));
+ assert!(hint.contains("feature-branch"));
+ assert!(hint.contains("To change directory"));
+ }
}
diff --git a/tests/snapshots/integration__integration_tests__approval_pty__approval_prompt_accept.snap b/tests/snapshots/integration__integration_tests__approval_pty__approval_prompt_accept.snap
index 629d7adb3..3ccb38116 100644
--- a/tests/snapshots/integration__integration_tests__approval_pty__approval_prompt_accept.snap
+++ b/tests/snapshots/integration__integration_tests__approval_pty__approval_prompt_accept.snap
@@ -15,3 +15,4 @@ test command
✓ Created branch test-approve from main and worktree @ _REPO_.test-approve
↳ To customize worktree locations, run wt config create
▲ Cannot change directory — ran [BIN]; shell integration wraps wt
+↳ To change directory, run wt switch test-approve
diff --git a/tests/snapshots/integration__integration_tests__approval_pty__approval_prompt_decline.snap b/tests/snapshots/integration__integration_tests__approval_pty__approval_prompt_decline.snap
index 954317af0..65b8247db 100644
--- a/tests/snapshots/integration__integration_tests__approval_pty__approval_prompt_decline.snap
+++ b/tests/snapshots/integration__integration_tests__approval_pty__approval_prompt_decline.snap
@@ -13,3 +13,4 @@ n
✓ Created branch test-decline from main and worktree @ _REPO_.test-decline
↳ To customize worktree locations, run wt config create
▲ Cannot change directory — ran [BIN]; shell integration wraps wt
+↳ To change directory, run wt switch test-decline
diff --git a/tests/snapshots/integration__integration_tests__approval_pty__approval_prompt_mixed_approved_unapproved_accept.snap b/tests/snapshots/integration__integration_tests__approval_pty__approval_prompt_mixed_approved_unapproved_accept.snap
index 368f06003..daa904bc3 100644
--- a/tests/snapshots/integration__integration_tests__approval_pty__approval_prompt_mixed_approved_unapproved_accept.snap
+++ b/tests/snapshots/integration__integration_tests__approval_pty__approval_prompt_mixed_approved_unapproved_accept.snap
@@ -23,3 +23,4 @@ Third command
✓ Created branch test-mixed-accept from main and worktree @ _REPO_.test-mixed-accept
↳ To customize worktree locations, run wt config create
▲ Cannot change directory — ran [BIN]; shell integration wraps wt
+↳ To change directory, run wt switch test-mixed-accept
diff --git a/tests/snapshots/integration__integration_tests__approval_pty__approval_prompt_mixed_approved_unapproved_decline.snap b/tests/snapshots/integration__integration_tests__approval_pty__approval_prompt_mixed_approved_unapproved_decline.snap
index 73d51cf3d..f032eb5cf 100644
--- a/tests/snapshots/integration__integration_tests__approval_pty__approval_prompt_mixed_approved_unapproved_decline.snap
+++ b/tests/snapshots/integration__integration_tests__approval_pty__approval_prompt_mixed_approved_unapproved_decline.snap
@@ -15,3 +15,4 @@ n
✓ Created branch test-mixed-decline from main and worktree @ _REPO_.test-mixed-decline
↳ To customize worktree locations, run wt config create
▲ Cannot change directory — ran [BIN]; shell integration wraps wt
+↳ To change directory, run wt switch test-mixed-decline
diff --git a/tests/snapshots/integration__integration_tests__approval_pty__approval_prompt_multiple_commands.snap b/tests/snapshots/integration__integration_tests__approval_pty__approval_prompt_multiple_commands.snap
index 53cd2dc28..570c7cc82 100644
--- a/tests/snapshots/integration__integration_tests__approval_pty__approval_prompt_multiple_commands.snap
+++ b/tests/snapshots/integration__integration_tests__approval_pty__approval_prompt_multiple_commands.snap
@@ -25,3 +25,4 @@ Third command
✓ Created branch test-multi from main and worktree @ _REPO_.test-multi
↳ To customize worktree locations, run wt config create
▲ Cannot change directory — ran [BIN]; shell integration wraps wt
+↳ To change directory, run wt switch test-multi
diff --git a/tests/snapshots/integration__integration_tests__approval_pty__approval_prompt_named_commands.snap b/tests/snapshots/integration__integration_tests__approval_pty__approval_prompt_named_commands.snap
index dfed37a2b..124072532 100644
--- a/tests/snapshots/integration__integration_tests__approval_pty__approval_prompt_named_commands.snap
+++ b/tests/snapshots/integration__integration_tests__approval_pty__approval_prompt_named_commands.snap
@@ -25,3 +25,4 @@ Running tests...
✓ Created branch test-named from main and worktree @ _REPO_.test-named
↳ To customize worktree locations, run wt config create
▲ Cannot change directory — ran [BIN]; shell integration wraps wt
+↳ To change directory, run wt switch test-named
diff --git a/tests/snapshots/integration__integration_tests__approval_pty__approval_prompt_permission_error.snap b/tests/snapshots/integration__integration_tests__approval_pty__approval_prompt_permission_error.snap
index b97f10265..a6da2b6ba 100644
--- a/tests/snapshots/integration__integration_tests__approval_pty__approval_prompt_permission_error.snap
+++ b/tests/snapshots/integration__integration_tests__approval_pty__approval_prompt_permission_error.snap
@@ -17,3 +17,4 @@ test command
✓ Created branch test-permission from main and worktree @ _REPO_.test-permission
↳ To customize worktree locations, run wt config create
▲ Cannot change directory — ran [BIN]; shell integration wraps wt
+↳ To change directory, run wt switch test-permission
diff --git a/tests/snapshots/integration__integration_tests__switch__switch_existing_with_shell_configured.snap b/tests/snapshots/integration__integration_tests__switch__switch_existing_with_shell_configured.snap
index 127e64d9f..f72de947e 100644
--- a/tests/snapshots/integration__integration_tests__switch__switch_existing_with_shell_configured.snap
+++ b/tests/snapshots/integration__integration_tests__switch__switch_existing_with_shell_configured.snap
@@ -13,6 +13,7 @@ info:
GIT_COMMITTER_DATE: "2025-01-01T00:00:00Z"
GIT_CONFIG_GLOBAL: "[TEST_GIT_CONFIG]"
GIT_CONFIG_SYSTEM: /dev/null
+ GIT_EDITOR: ""
GIT_TERMINAL_PROMPT: "0"
HOME: "[TEST_HOME]"
LANG: C
@@ -34,3 +35,4 @@ exit_code: 0
----- stderr -----
▲ Worktree for shell-configured @ _REPO_.shell-configured, but cannot change directory — ran [PROJECT_ROOT]/target/debug/wt; shell integration wraps wt
+↳ To change directory, run wt switch shell-configured