Skip to content

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.md
index 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.0
diff --git a/CLAUDE.md b/CLAUDE.md
index 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.lock
index 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.toml
index 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.rs
index 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 exists
if 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 it
if 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(&current_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.rs
index 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(),