Skip to content

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

Improve worktree command output and shell integration guidance

Maximilian Roosa0e9e414eea1
diff --git a/src/commands/worktree.rs b/src/commands/worktree.rs
index eb21b838b..4e45ca77f 100644
--- a/src/commands/worktree.rs
+++ b/src/commands/worktree.rs
@@ -1,3 +1,71 @@
+//! Worktree operations with dual-mode output for shell integration.
+//!
+//! # The Directory Change Problem
+//!
+//! Worktree commands (`switch`, `remove`, `merge`) need to change the user's working directory,
+//! but there's a fundamental Unix limitation: **child processes cannot change their parent's
+//! working directory**. This is a security feature and core Unix design principle.
+//!
+//! When a user runs `wt switch my-feature`, the `wt` binary runs as a child process of the shell.
+//! The binary can change *its own* working directory, but when it exits, the parent shell remains
+//! in the original directory.
+//!
+//! # Solution: Dual-Mode Output
+//!
+//! We solve this with two output modes:
+//!
+//! ## Without `--internal` (Direct Binary Call)
+//!
+//! ```bash
+//! $ wt switch my-feature
+//! Created new branch and worktree for 'my-feature' at /path/to/worktree
+//!
+//! To enable automatic cd, run: wt configure-shell
+//!
+//! $ pwd
+//! /original/directory # ← User is still here!
+//! ```
+//!
+//! The binary performs git operations and prints user-friendly messages, but **cannot** change
+//! the parent shell's directory. User must manually `cd` to the worktree.
+//!
+//! ## With `--internal` (Via Shell Wrapper)
+//!
+//! ```bash
+//! $ wt switch my-feature
+//! Created new branch and worktree for 'my-feature' at /path/to/worktree
+//!
+//! $ pwd
+//! /path/to/worktree # ← Automatically changed!
+//! ```
+//!
+//! When shell integration is enabled (`eval "$(wt init bash)"`), the shell function intercepts
+//! commands and adds `--internal`:
+//!
+//! 1. Shell wrapper calls: `wt switch --internal my-feature`
+//! 2. Binary outputs special directive protocol:
+//! ```
+//! __WORKTRUNK_CD__/path/to/worktree
+//! Created new branch and worktree for 'my-feature' at /path/to/worktree
+//! ```
+//! 3. Shell wrapper parses output line-by-line
+//! 4. When it sees `__WORKTRUNK_CD__<path>`, it executes `cd <path>` in the parent shell
+//! 5. Other lines are printed normally
+//!
+//! The binary **never changes directories itself** - it just communicates the desired path back
+//! to the shell wrapper via stdout using the `__WORKTRUNK_CD__` directive protocol.
+//!
+//! # Implementation Details
+//!
+//! Result types (`SwitchResult`, `RemoveResult`) provide two formatting methods:
+//!
+//! - `format_user_output()`: Returns human-friendly messages (no directives)
+//! - `format_internal_output()`: Returns directive protocol + messages
+//!
+//! The shell wrapper is generated by `wt init <shell>` from templates in `templates/`.
+//!
+//! See also: DEMO.md for detailed architecture explanation.
+
use std::io::{self, Write};
use std::path::PathBuf;
use worktrunk::config::{ProjectConfig, WorktrunkConfig};
diff --git a/tests/snapshots/integration__integration_tests__post_start_commands__post_start_empty_array.snap b/tests/snapshots/integration__integration_tests__post_start_commands__post_start_empty_array.snap
index 28c9da6b8..744357e6a 100644
--- a/tests/snapshots/integration__integration_tests__post_start_commands__post_start_empty_array.snap
+++ b/tests/snapshots/integration__integration_tests__post_start_commands__post_start_empty_array.snap
@@ -21,6 +21,7 @@ success: true
exit_code: 0
----- stdout -----
Created new branch and worktree for 'feature' at [REPO].feature
-Note: Use 'wt switch' (with shell integration) for automatic cd
+
+To enable automatic cd, run: wt configure-shell
----- stderr -----
diff --git a/tests/snapshots/integration__integration_tests__post_start_commands__post_start_failing_command.snap b/tests/snapshots/integration__integration_tests__post_start_commands__post_start_failing_command.snap
index f78dbb72e..872838e59 100644
--- a/tests/snapshots/integration__integration_tests__post_start_commands__post_start_failing_command.snap
+++ b/tests/snapshots/integration__integration_tests__post_start_commands__post_start_failing_command.snap
@@ -21,7 +21,8 @@ success: true
exit_code: 0
----- stdout -----
Created new branch and worktree for 'feature' at [REPO].feature
-Note: Use 'wt switch' (with shell integration) for automatic cd
+
+To enable automatic cd, run: wt configure-shell
----- stderr -----
Executing: exit 1
diff --git a/tests/snapshots/integration__integration_tests__post_start_commands__post_start_invalid_toml.snap b/tests/snapshots/integration__integration_tests__post_start_commands__post_start_invalid_toml.snap
index 7c45814f1..e0ce83428 100644
--- a/tests/snapshots/integration__integration_tests__post_start_commands__post_start_invalid_toml.snap
+++ b/tests/snapshots/integration__integration_tests__post_start_commands__post_start_invalid_toml.snap
@@ -21,7 +21,8 @@ success: true
exit_code: 0
----- stdout -----
Created new branch and worktree for 'feature' at [REPO].feature
-Note: Use 'wt switch' (with shell integration) for automatic cd
+
+To enable automatic cd, run: wt configure-shell
----- stderr -----
Warning: Failed to load project config from [REPO]/.config/wt.toml
diff --git a/tests/snapshots/integration__integration_tests__post_start_commands__post_start_multiple_commands.snap b/tests/snapshots/integration__integration_tests__post_start_commands__post_start_multiple_commands.snap
index d21015d5d..99264257f 100644
--- a/tests/snapshots/integration__integration_tests__post_start_commands__post_start_multiple_commands.snap
+++ b/tests/snapshots/integration__integration_tests__post_start_commands__post_start_multiple_commands.snap
@@ -23,7 +23,8 @@ exit_code: 0
First
Second
Created new branch and worktree for 'feature' at [REPO].feature
-Note: Use 'wt switch' (with shell integration) for automatic cd
+
+To enable automatic cd, run: wt configure-shell
----- stderr -----
Executing: echo 'First'
diff --git a/tests/snapshots/integration__integration_tests__post_start_commands__post_start_no_config.snap b/tests/snapshots/integration__integration_tests__post_start_commands__post_start_no_config.snap
index 28c9da6b8..744357e6a 100644
--- a/tests/snapshots/integration__integration_tests__post_start_commands__post_start_no_config.snap
+++ b/tests/snapshots/integration__integration_tests__post_start_commands__post_start_no_config.snap
@@ -21,6 +21,7 @@ success: true
exit_code: 0
----- stdout -----
Created new branch and worktree for 'feature' at [REPO].feature
-Note: Use 'wt switch' (with shell integration) for automatic cd
+
+To enable automatic cd, run: wt configure-shell
----- stderr -----
diff --git a/tests/snapshots/integration__integration_tests__post_start_commands__post_start_with_approval.snap b/tests/snapshots/integration__integration_tests__post_start_commands__post_start_with_approval.snap
index 5269a22d3..c6830f68c 100644
--- a/tests/snapshots/integration__integration_tests__post_start_commands__post_start_with_approval.snap
+++ b/tests/snapshots/integration__integration_tests__post_start_commands__post_start_with_approval.snap
@@ -22,7 +22,8 @@ exit_code: 0
----- stdout -----
Setup complete
Created new branch and worktree for 'feature' at [REPO].feature
-Note: Use 'wt switch' (with shell integration) for automatic cd
+
+To enable automatic cd, run: wt configure-shell
----- stderr -----
Executing: echo 'Setup complete'