Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
Release v0.75.0 (#3924)
Maximilian Roos24d09cf05632
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex afcbce01d..8f4271daa 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -1,10 +1,44 @@# Changelog-## Unreleased+## 0.75.0++### Improved++- **The `wt switch` picker opens on one unified diff**: local rows combine committed, staged, unstaged, and untracked changes. Tab skips empty subsidiary views, while `Alt-1` through `Alt-8` retain direct access. [Docs](https://worktrunk.dev/switch/#interactive-picker) ([#3865](https://github.com/max-sixty/worktrunk/pull/3865))++- **Git 2.43 is now the minimum supported version**: older Git exits with an upgrade message before Git-dependent commands run; `wt config shell` remains available so shell startup continues. (Breaking.) ([#3895](https://github.com/max-sixty/worktrunk/pull/3895))### Fixed-- **Windows: a path past the 260-character limit compared as if it were on another drive**: `dunce` strips the `\\?\` prefix only below that length, so a deep `node_modules` came back spelled `\\?\C:\…` while its worktree root stayed `C:\…`. `wt step copy-ignored` refused to copy into it, and `wt switch` (and `remove`, `merge`, `step relocate`) silently landed the shell at the worktree root instead of your subdirectory. The canonicalizer now returns one spelling at any length. (fixes [#3898](https://github.com/max-sixty/worktrunk/issues/3898), thanks @Persedes for reporting)+- **`wt list` no longer grows `.git/objects` during advisory conflict checks**: untracked content stays visible but is excluded from synthetic trees, and all probe-only objects use temporary storage. ([#3906](https://github.com/max-sixty/worktrunk/pull/3906), fixes [#3883](https://github.com/max-sixty/worktrunk/issues/3883), thanks @srobroek for reporting and the original fix)++- **Timed child processes no longer abort `wt` in restricted sandboxes**: `wt switch --create`, picker pagers, and other bounded commands survive denied signal-handler wakes. TERM→KILL cleanup also returns promptly once the process group is gone. ([#3857](https://github.com/max-sixty/worktrunk/pull/3857), [#3887](https://github.com/max-sixty/worktrunk/pull/3887), fixes [#3856](https://github.com/max-sixty/worktrunk/issues/3856), thanks @tomascamargo for reporting)++- **JSON list output ignores display-column gates**: `[list] columns` no longer makes `wt list --format json` contact a forge or generate summaries. CI requires `--full`; summaries also require `[list] summary = true` and a configured generator. (Breaking: schema 1 loses config-driven `ci` and `summary` fields.) ([#3812](https://github.com/max-sixty/worktrunk/pull/3812), thanks @emeren for the request)++- **Long Windows paths compare consistently**: paths beyond 260 characters could retain a `\\?\` prefix and appear to be on another drive. `copy-ignored` then refused them, while switch, remove, merge, and relocate landed at the worktree root instead of the original subdirectory. ([#3899](https://github.com/max-sixty/worktrunk/pull/3899), fixes [#3898](https://github.com/max-sixty/worktrunk/issues/3898), thanks @Persedes for reporting and verifying the fix)++- **Shell configuration rechecks before it writes**: overlapping installs lock and reread rc files; Fish completion installs preserve files created after preview; uninstall applies only previewed rc removals and rejects changed Worktrunk-owned files. ([#3853](https://github.com/max-sixty/worktrunk/pull/3853), [#3924](https://github.com/max-sixty/worktrunk/pull/3924))++- **`-vv` profiles exclude their own collector commands**: command counts and cache summaries no longer include duplicate-looking work performed only to assemble the diagnostic report; raw traces still retain it. ([#3900](https://github.com/max-sixty/worktrunk/pull/3900))++- **Fenced HTML comments survive picker Markdown rendering**: PR descriptions and comments now preserve fenced `<!-- … -->` lines; fenced `<!-- wt list … -->` markers also no longer affect the following block. ([#3908](https://github.com/max-sixty/worktrunk/pull/3908))++### Documentation++- **Agent CLIs without a plugin can publish activity markers**: the integration guide now specifies the session-start, turn-end, and session-end calls, working-directory requirement, error guard, and cleanup contract. [Docs](https://worktrunk.dev/claude-code/#agent-clis-without-a-plugin) ([#3848](https://github.com/max-sixty/worktrunk/pull/3848), thanks @AsafMah for requesting generic-agent guidance and @ortonomy for the related Pi use case)++- **Agent guidance explains worktree selection**: commands that name a branch already select its worktree; `-C` changes repository context and is needed only for commands without a worktree selector or callers outside the repository. ([#3890](https://github.com/max-sixty/worktrunk/pull/3890))++- **The `wt up` recipe safely updates dirty worktrees**: it fetches all remotes, fast-forwards dirty branches without autostash, rebases clean branches, and continues past an ordinary refusal or a failed remote. [Docs](https://worktrunk.dev/extending/#recipe-rebase-every-worktree-onto-its-upstream) ([#3882](https://github.com/max-sixty/worktrunk/pull/3882))++- **The docs site has a new responsive design**: rebuilt on Astro and Starlight while preserving public routes, anchors, and crawler URLs; generated reference pages remain synchronized. ([#3866](https://github.com/max-sixty/worktrunk/pull/3866))++### Internal++- **Library API rework** (Breaking library API): `BranchDiffSpec` gained `working_base`, while remote-URL, shell-path, branch-push, approval, temporary-index, and repository helpers were removed. ([#3833](https://github.com/max-sixty/worktrunk/pull/3833), [#3853](https://github.com/max-sixty/worktrunk/pull/3853), [#3865](https://github.com/max-sixty/worktrunk/pull/3865), [#3866](https://github.com/max-sixty/worktrunk/pull/3866), [#3875](https://github.com/max-sixty/worktrunk/pull/3875))++- **Codex loads repository maintainer skills**: `.agents/skills` now exposes the canonical `.claude/skills` tree; checkouts without symlink support keep the existing limitation. ([#3903](https://github.com/max-sixty/worktrunk/pull/3903))## 0.74.0diff --git a/CLAUDE.md b/CLAUDE.mdindex e40ef90e6..fd89143d1 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -59,7 +59,7 @@ Never risk data loss without explicit user consent. A failed command that preser- **No implicit destructive side effects** — never silently delete/overwrite as a side effect of an unrelated operation; make cleanup a separate explicit action the user chooses.- **Favor the failing variant on races** — `git reset --keep` (fails if tracked files were modified) over `--hard`; `git checkout --merge` over `--force`. If no safer variant exists, document the risk inline.- **Time-of-check vs time-of-use** — be conservative when there's a gap between the safety check and the operation. `wt merge` verifies clean before rebasing, but files could appear before cleanup — don't force-remove during cleanup.-- **Replace files, never truncate them** — `fs::write` truncates before it writes, so a crash mid-write leaves the file empty. Every write to a file worktrunk can't put back (rc files, shell wrappers, `config.toml`, `approvals.toml`, another tool's `settings.json`) goes through `utils::write_atomically`, which renames a sibling temp file over the target; the spec on that function covers symlinks, mode, and what a rename costs. Regenerable content (the cache, the `-vv` diagnostic report) keeps the plain write.+- **Replace full files, never truncate them** — `fs::write` truncates before it writes, so a crash mid-write leaves the file empty. Every full-file rewrite worktrunk can't put back (shell wrappers, `config.toml`, `approvals.toml`, another tool's `settings.json`) goes through `utils::write_atomically`, which renames a sibling temp file over the target; the spec on that function covers symlinks, mode, and what a rename costs. Adding to a user-owned file (the Bash, Zsh, and PowerShell rc files) instead opens it in append mode, so a stale snapshot cannot replace concurrent edits; offer the addition as one buffer, and report a short write without truncating the file. Don't grow the install path into a rebuild. Removal still rewrites those rc files whole (`uninstall_previewed_lines`), which is why the `write_atomically` spec still names them. Regenerable content (the cache, the `-vv` diagnostic report) keeps the plain write.These stop where git's own protections stop, and matching git is deliberate in each case. The named spec says why:diff --git a/Cargo.lock b/Cargo.lockindex a1fb2d23b..e0cb454bd 100644--- a/Cargo.lock+++ b/Cargo.lock@@ -4813,7 +4813,7 @@ dependencies = [[[package]]name = "worktrunk"-version = "0.74.0"+version = "0.75.0"dependencies = ["ansi-str","ansi-to-tui",diff --git a/Cargo.toml b/Cargo.tomlindex cdaf05faf..69f8c9a38 100644--- a/Cargo.toml+++ b/Cargo.toml@@ -48,7 +48,7 @@ filterset = "test(/readme_sync/)"[package]name = "worktrunk"-version = "0.74.0"+version = "0.75.0"edition = "2024"rust-version = "1.97"build = "build.rs"diff --git a/src/commands/configure_shell.rs b/src/commands/configure_shell.rsindex 43515d0d6..17c60bcb3 100644--- a/src/commands/configure_shell.rs+++ b/src/commands/configure_shell.rs@@ -1,9 +1,10 @@use std::collections::HashSet;use std::fs;-use std::io::{self, Write};+use std::io::{self, Read, Seek, Write};use std::path::{Path, PathBuf};use anstyle::Style;+use fs2::FileExt;use worktrunk::path::format_path_for_display;use worktrunk::shell::{self, Shell};use worktrunk::styling::{@@ -655,29 +656,19 @@ fn configure_shell_file(// For other shells, check if file existsif path.exists() {- // Read the file and check if our integration already exists+ // Read the file and check if our integration already exists. Do this+ // read-only first so an already-configured read-only rc file succeeds.let content = fs::read(path).map_err(|e| format!("Failed to read {}: {}", format_path_for_display(path), e))?;- // Check for the canonical line and older/manual forms for this shell.- for line in content.split(|byte| *byte == b'\n') {- let line = std::str::from_utf8(line).map_err(|e| {- format!(- "Failed to read line from {}: {e}",- format_path_for_display(path)- )- })?;- if is_install_shell_integration_line(line.trim_end_matches('\r'), shell, cmd) {- return Ok(Some(ConfigureResult {- shell,- path: path.to_path_buf(),- action: ConfigAction::AlreadyExists,- config_line,- }));- }+ if contains_shell_integration(&content, path, shell, cmd)? {+ return Ok(Some(ConfigureResult {+ shell,+ path: path.to_path_buf(),+ action: ConfigAction::AlreadyExists,+ config_line,+ }));}- let mut content = String::from_utf8(content)- .map_err(|e| format!("Failed to read {}: {e}", format_path_for_display(path)))?;// Line doesn't exist, add itif dry_run {@@ -689,22 +680,17 @@ fn configure_shell_file(}));}- // Add blank line before config, then the config line with its own newline- content.push('\n');- content.push_str(&config_line);- content.push('\n');- write_atomically(path, &content).map_err(|e| {- format!(- "Failed to write to {}: {}",- format_path_for_display(path),- e- )- })?;+ // Append through one open file handle. Replacing an rc file from the+ // snapshot above would discard edits made in the meantime and would+ // also sever hard links and file metadata that belong to the user.+ let mut file = open_locked_rc_file(path)?;+ let action =+ append_shell_integration_if_missing(&mut file, path, shell, cmd, &config_line)?;Ok(Some(ConfigureResult {shell,path: path.to_path_buf(),- action: ConfigAction::Added,+ action,config_line,}))} else {@@ -753,6 +739,112 @@ fn configure_shell_file(}}+fn open_locked_rc_file(path: &Path) -> Result<fs::File, String> {+ let file = fs::OpenOptions::new()+ .read(true)+ .append(true)+ .open(path)+ .map_err(|e| {+ format!(+ "Failed to open {} for writing: {}",+ format_path_for_display(path),+ e+ )+ })?;+ file.lock_exclusive().map_err(|e| {+ format!(+ "Failed to lock {} for writing: {}",+ format_path_for_display(path),+ e+ )+ })?;+ Ok(file)+}++/// Offer an rc-file addition in one successful write.+///+/// `write_all` can append part of its buffer and then fail on a later write,+/// hiding how much of the shell line reached the file. A single short write is+/// instead an error of its own. Never truncate the user-owned file in response:+/// no portable operation can keep a later concurrent append out of that race.+fn write_append_buffer(+ mut write_once: impl FnMut(&[u8]) -> io::Result<usize>,+ addition: &[u8],+) -> io::Result<()> {+ let written = loop {+ match write_once(addition) {+ Err(error) if error.kind() == io::ErrorKind::Interrupted => continue,+ result => break result?,+ }+ };+ if written == addition.len() {+ return Ok(());+ }++ Err(io::Error::new(+ io::ErrorKind::WriteZero,+ format!(+ "only {written} of {} bytes were written; the file may end with a partial Worktrunk shell integration line",+ addition.len()+ ),+ ))+}++/// Recheck an open rc file and append the integration line if it is still absent.+///+/// The caller holds the file's exclusive lock. Re-reading through the same+/// append-mode handle includes changes made after the preliminary read without+/// replacing unrelated bytes or the file's inode.+fn append_shell_integration_if_missing(+ file: &mut fs::File,+ path: &Path,+ shell: Shell,+ cmd: &str,+ config_line: &str,+) -> Result<ConfigAction, String> {+ file.rewind()+ .map_err(|e| format!("Failed to read {}: {}", format_path_for_display(path), e))?;+ let mut current_content = Vec::new();+ file.read_to_end(&mut current_content)+ .map_err(|e| format!("Failed to read {}: {}", format_path_for_display(path), e))?;+ if contains_shell_integration(¤t_content, path, shell, cmd)? {+ return Ok(ConfigAction::AlreadyExists);+ }++ // Add a blank line before config, then the config line with its own newline.+ // Offer the whole addition as one buffer rather than split formatted writes.+ let addition = format!("\n{config_line}\n");+ write_append_buffer(|buffer| file.write(buffer), addition.as_bytes()).map_err(|e| {+ format!(+ "Failed to write to {}: {}",+ format_path_for_display(path),+ e+ )+ })?;+ Ok(ConfigAction::Added)+}++fn contains_shell_integration(+ content: &[u8],+ path: &Path,+ shell: Shell,+ cmd: &str,+) -> Result<bool, String> {+ // Check for the canonical line and older/manual forms for this shell.+ for line in content.split(|byte| *byte == b'\n') {+ let line = std::str::from_utf8(line).map_err(|e| {+ format!(+ "Failed to read line from {}: {e}",+ format_path_for_display(path)+ )+ })?;+ if is_install_shell_integration_line(line.trim_end_matches('\r'), shell, cmd) {+ return Ok(true);+ }+ }+ Ok(false)+}+fn is_install_shell_integration_line(line: &str, shell: Shell, cmd: &str) -> bool {shell::is_shell_integration_line(line, cmd)&& line@@ -1896,6 +1988,194 @@ mod tests {assert_eq!(fs::read(&rc).unwrap(), content);}+ #[test]+ fn test_configure_shell_appends_without_replacing_existing_file() {+ let dir = tempfile::TempDir::new().unwrap();+ let rc = dir.path().join(".zshrc");+ let hard_link = dir.path().join("zshrc-hard-link");+ fs::write(&rc, "export EDITOR=hx\n").unwrap();+ fs::hard_link(&rc, &hard_link).unwrap();++ let result = configure_shell_file(Shell::Zsh, &rc, false, false, "wt").unwrap();++ assert_eq!(result.unwrap().action, ConfigAction::Added);+ let expected = concat!(+ "export EDITOR=hx\n",+ "\n",+ "if command -v wt >/dev/null 2>&1; then eval \"$(command wt config shell init zsh)\"; fi\n"+ );+ assert_eq!(fs::read_to_string(&rc).unwrap(), expected);+ assert_eq!(fs::read_to_string(&hard_link).unwrap(), expected);+ }++ #[test]+ fn test_configure_shell_opens_rc_with_exclusive_lock() {+ let dir = tempfile::TempDir::new().unwrap();+ let rc = dir.path().join(".zshrc");+ fs::write(&rc, "export EDITOR=hx\n").unwrap();++ let locked = open_locked_rc_file(&rc).unwrap();+ let contender = fs::OpenOptions::new()+ .read(true)+ .append(true)+ .open(&rc)+ .unwrap();+ assert!(contender.try_lock_exclusive().is_err());+ drop(locked);+ contender.try_lock_exclusive().unwrap();+ }++ #[test]+ fn test_open_locked_rc_file_reports_open_errors() {+ let dir = tempfile::TempDir::new().unwrap();+ let missing = dir.path().join("missing-zshrc");++ let error = open_locked_rc_file(&missing).unwrap_err();++ assert!(error.starts_with(&format!(+ "Failed to open {} for writing:",+ format_path_for_display(&missing)+ )));+ }++ #[test]+ fn test_append_write_retries_interrupt_and_reports_incomplete_writes() {+ let original = b"export EDITOR=hx\n";+ let addition = b"\nif command -v wt; then eval ...\n";+ let mut short_content = original.to_vec();+ let mut short_calls = 0;++ let error = write_append_buffer(+ |buffer| {+ short_calls += 1;+ let written = buffer.len().min(12);+ short_content.extend_from_slice(&buffer[..written]);+ Ok(written)+ },+ addition,+ )+ .unwrap_err();++ assert_eq!(error.kind(), io::ErrorKind::WriteZero);+ assert!(+ error+ .to_string()+ .contains("partial Worktrunk shell integration line")+ );+ assert_eq!(+ short_content,+ [original.as_slice(), &addition[..12]].concat()+ );+ assert_eq!(short_calls, 1, "a short append must not write again");++ let mut interrupted_content = original.to_vec();+ let mut interrupted_calls = 0;+ write_append_buffer(+ |buffer| {+ interrupted_calls += 1;+ if interrupted_calls == 1 {+ return Err(io::Error::new(+ io::ErrorKind::Interrupted,+ "injected write error",+ ));+ }+ interrupted_content.extend_from_slice(buffer);+ Ok(buffer.len())+ },+ addition,+ )+ .unwrap();++ assert_eq!(+ interrupted_content,+ [original.as_slice(), addition.as_slice()].concat()+ );+ assert_eq!(interrupted_calls, 2);++ let mut failed_calls = 0;+ let error = write_append_buffer(+ |_| {+ failed_calls += 1;+ Err(io::Error::new(+ io::ErrorKind::StorageFull,+ "injected write error",+ ))+ },+ addition,+ )+ .unwrap_err();++ assert_eq!(error.kind(), io::ErrorKind::StorageFull);+ assert!(+ !error+ .to_string()+ .contains("partial Worktrunk shell integration line")+ );+ assert_eq!(failed_calls, 1);+ }++ #[test]+ fn test_append_shell_integration_reports_write_errors() {+ let dir = tempfile::TempDir::new().unwrap();+ let rc = dir.path().join(".zshrc");+ let original = "export EDITOR=hx\n";+ fs::write(&rc, original).unwrap();+ let mut read_only = fs::File::open(&rc).unwrap();+ let config_line = Shell::Zsh.config_line("wt");++ let error = append_shell_integration_if_missing(+ &mut read_only,+ &rc,+ Shell::Zsh,+ "wt",+ &config_line,+ )+ .unwrap_err();++ assert!(error.starts_with(&format!(+ "Failed to write to {}:",+ format_path_for_display(&rc)+ )));+ assert!(!error.contains("partial Worktrunk shell integration line"));+ assert_eq!(fs::read_to_string(&rc).unwrap(), original);+ }++ #[test]+ fn test_configure_shell_rereads_open_file_before_appending() {+ let dir = tempfile::TempDir::new().unwrap();+ let rc = dir.path().join(".zshrc");+ fs::write(&rc, "export EDITOR=hx\n").unwrap();++ let mut pending_installer = fs::OpenOptions::new()+ .read(true)+ .append(true)+ .open(&rc)+ .unwrap();++ let config_line = Shell::Zsh.config_line("wt");+ let mut concurrent_installer = fs::OpenOptions::new().append(true).open(&rc).unwrap();+ write!(concurrent_installer, "\n{config_line}\n").unwrap();+ drop(concurrent_installer);++ let action = append_shell_integration_if_missing(+ &mut pending_installer,+ &rc,+ Shell::Zsh,+ "wt",+ &config_line,+ )+ .unwrap();++ assert_eq!(action, ConfigAction::AlreadyExists);+ assert_eq!(+ fs::read_to_string(&rc)+ .unwrap()+ .matches(&config_line)+ .count(),+ 1+ );+ }+#[test]fn test_uninstall_previewed_lines_preserves_mixed_line_endings() {let dir = tempfile::TempDir::new().unwrap();diff --git a/src/git/repository/diff.rs b/src/git/repository/diff.rsindex 7c7e0f6ee..ef28d21a1 100644--- a/src/git/repository/diff.rs+++ b/src/git/repository/diff.rs@@ -184,7 +184,9 @@ fn parse_commit_message_details_output(output: &str) -> anyhow::Result<Vec<Commi}Ok(parts- .chunks_exact(2)+ .as_chunks::<2>()+ .0+ .iter().map(|pair| CommitMessageDetail {subject: pair[0].to_string(),body: pair[1].to_string(),