Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
fix: document and categorize diagnostic files in state logs (#1981)
Maximilian Roosed883d574770
diff --git a/docs/content/config.md b/docs/content/config.mdindex 329b24c6f..c34423124 100644--- a/docs/content/config.md+++ b/docs/content/config.md@@ -879,7 +879,7 @@ View and manage logs from background operations.### What's logged-Two kinds of logs live in `.git/wt/logs/`:+Three kinds of logs live in `.git/wt/logs/`:#### Command log (`commands.jsonl`)@@ -894,6 +894,15 @@ All hook executions and LLM commands are recorded automatically — one JSON objSource is `user` or `project` depending on where the hook is defined.+#### Diagnostic files++| File | Created when |+|------|-------------|+| `verbose.log` | Running with `-vv` |+| `diagnostic.md` | Running with `-vv` when warnings occur |++`verbose.log` is overwritten on each `-vv` run. `diagnostic.md` is a markdown report for pasting into GitHub issues — written only when warnings occur.+### LocationAll logs are stored in `.git/wt/logs/` (in the main worktree's git directory).diff --git a/docs/content/faq.md b/docs/content/faq.mdindex 2819f42c7..94ffbe235 100644--- a/docs/content/faq.md+++ b/docs/content/faq.md@@ -117,6 +117,8 @@ Worktrunk stores small amounts of cache and log data in the repository's `.git/`| `.git/wt/cache/ci-status/*.json` | CI status cache (~1KB each) | `wt list` when `gh` or `glab` CLI is installed || `.git/wt/logs/*.log` | Background command output | Hooks, background `wt remove` || `.git/wt/logs/commands.jsonl` | Command audit log (~2MB max) | Hooks, LLM commands |+| `.git/wt/logs/verbose.log` | Debug log for issue reporting | Running with `-vv` |+| `.git/wt/logs/diagnostic.md` | Diagnostic report for issue reporting | Running with `-vv` when warnings occur || `.git/wt/trash/<name>-<timestamp>` | Staged worktree contents pending background deletion | `wt remove` |None of this is tracked by git or pushed to remotes.diff --git a/skills/worktrunk/reference/config.md b/skills/worktrunk/reference/config.mdindex 731190add..254492143 100644--- a/skills/worktrunk/reference/config.md+++ b/skills/worktrunk/reference/config.md@@ -904,7 +904,7 @@ View and manage logs from background operations.### What's logged-Two kinds of logs live in `.git/wt/logs/`:+Three kinds of logs live in `.git/wt/logs/`:#### Command log (`commands.jsonl`)@@ -919,6 +919,15 @@ All hook executions and LLM commands are recorded automatically — one JSON objSource is `user` or `project` depending on where the hook is defined.+#### Diagnostic files++| File | Created when |+|------|-------------|+| `verbose.log` | Running with `-vv` |+| `diagnostic.md` | Running with `-vv` when warnings occur |++`verbose.log` is overwritten on each `-vv` run. `diagnostic.md` is a markdown report for pasting into GitHub issues — written only when warnings occur.+### LocationAll logs are stored in `.git/wt/logs/` (in the main worktree's git directory).diff --git a/skills/worktrunk/reference/faq.md b/skills/worktrunk/reference/faq.mdindex 24cfdf816..6ceb8a8b4 100644--- a/skills/worktrunk/reference/faq.md+++ b/skills/worktrunk/reference/faq.md@@ -110,6 +110,8 @@ Worktrunk stores small amounts of cache and log data in the repository's `.git/`| `.git/wt/cache/ci-status/*.json` | CI status cache (~1KB each) | `wt list` when `gh` or `glab` CLI is installed || `.git/wt/logs/*.log` | Background command output | Hooks, background `wt remove` || `.git/wt/logs/commands.jsonl` | Command audit log (~2MB max) | Hooks, LLM commands |+| `.git/wt/logs/verbose.log` | Debug log for issue reporting | Running with `-vv` |+| `.git/wt/logs/diagnostic.md` | Diagnostic report for issue reporting | Running with `-vv` when warnings occur || `.git/wt/trash/<name>-<timestamp>` | Staged worktree contents pending background deletion | `wt remove` |None of this is tracked by git or pushed to remotes.diff --git a/src/cli/config.rs b/src/cli/config.rsindex fb41cbacc..77bf7ded4 100644--- a/src/cli/config.rs+++ b/src/cli/config.rs@@ -604,7 +604,7 @@ Without a subcommand, runs `get` for the current branch. For `--branch`, use `ge## What's logged-Two kinds of logs live in `.git/wt/logs/`:+Three kinds of logs live in `.git/wt/logs/`:### Command log (`commands.jsonl`)@@ -619,6 +619,15 @@ All hook executions and LLM commands are recorded automatically — one JSON objSource is `user` or `project` depending on where the hook is defined.+### Diagnostic files++| File | Created when |+|------|-------------|+| `verbose.log` | Running with `-vv` |+| `diagnostic.md` | Running with `-vv` when warnings occur |++`verbose.log` is overwritten on each `-vv` run. `diagnostic.md` is a markdown report for pasting into GitHub issues — written only when warnings occur.+## LocationAll logs are stored in `.git/wt/logs/` (in the main worktree's git directory).diff --git a/src/commands/config/state.rs b/src/commands/config/state.rsindex 25bf5fca3..37947d01d 100644--- a/src/commands/config/state.rs+++ b/src/commands/config/state.rs@@ -39,12 +39,28 @@ pub fn require_user_config_path() -> anyhow::Result<PathBuf> {/// Check if a file in `.git/wt/logs/` is a worktrunk log file.///-/// Matches `.log` (hook output), `.jsonl` (command audit log), and `.jsonl.old` (rotated).+/// Matches `.log` (hook output + verbose), `.jsonl`/`.jsonl.old` (command audit log),+/// and known diagnostic files.fn is_wt_log_file(path: &std::path::Path) -> bool {let Some(name) = path.file_name().and_then(|n| n.to_str()) else {return false;};- name.ends_with(".log") || name.ends_with(".jsonl") || name.ends_with(".jsonl.old")+ name.ends_with(".log")+ || name.ends_with(".jsonl")+ || name.ends_with(".jsonl.old")+ || is_diagnostic_file(name)+}++/// Check if a file is a diagnostic file (`verbose.log` or `diagnostic.md`).+///+/// These are created by `-vv` and are separate from hook output and the command audit log.+fn is_diagnostic_file(name: &str) -> bool {+ name == "verbose.log" || name == "diagnostic.md"+}++/// Check if a file is a hook output log (branch-specific `.log` files, not diagnostic).+fn is_hook_output_file(name: &str) -> bool {+ name.ends_with(".log") && !is_diagnostic_file(name)}/// Clear stale entries from the wt/trash directory.@@ -160,15 +176,20 @@ fn render_log_table(out: &mut String, entries: &mut [std::fs::DirEntry]) -> std:Ok(())}-/// Render the COMMAND LOG section into the output buffer.-pub(super) fn render_command_log(out: &mut String, repo: &Repository) -> anyhow::Result<()> {+/// Render a single log section: heading, then filtered entries from the logs directory.+fn render_log_section(+ out: &mut String,+ repo: &Repository,+ heading: &str,+ filter: impl Fn(&str) -> bool,+) -> anyhow::Result<()> {let log_dir = repo.wt_logs_dir();let log_dir_display = format_path_for_display(&log_dir);writeln!(out,"{}",- format_heading("COMMAND LOG", Some(&format!("@ {log_dir_display}")))+ format_heading(heading, Some(&format!("@ {log_dir_display}"))))?;if !log_dir.exists() {@@ -178,41 +199,20 @@ pub(super) fn render_command_log(out: &mut String, repo: &Repository) -> anyhow:let mut entries: Vec<_> = std::fs::read_dir(&log_dir)?.filter_map(|e| e.ok())- .filter(|e| {- let name = e.file_name().to_string_lossy().to_string();- e.path().is_file() && is_command_log_file(&name)- })+ .filter(|e| e.path().is_file() && filter(&e.file_name().to_string_lossy())).collect();render_log_table(out, &mut entries)?;Ok(())}-/// Render the HOOK OUTPUT section into the output buffer.-pub(super) fn render_hook_output(out: &mut String, repo: &Repository) -> anyhow::Result<()> {- let log_dir = repo.wt_logs_dir();- let log_dir_display = format_path_for_display(&log_dir);-- writeln!(- out,- "{}",- format_heading("HOOK OUTPUT", Some(&format!("@ {log_dir_display}")))- )?;-- if !log_dir.exists() {- writeln!(out, "{}", format_with_gutter("(none)", None))?;- return Ok(());- }-- let mut entries: Vec<_> = std::fs::read_dir(&log_dir)?- .filter_map(|e| e.ok())- .filter(|e| {- let name = e.file_name().to_string_lossy().to_string();- e.path().is_file() && is_wt_log_file(&e.path()) && !is_command_log_file(&name)- })- .collect();-- render_log_table(out, &mut entries)?;+/// Render all three log sections (command log, hook output, diagnostic) into a buffer.+pub(super) fn render_all_log_sections(out: &mut String, repo: &Repository) -> anyhow::Result<()> {+ render_log_section(out, repo, "COMMAND LOG", is_command_log_file)?;+ writeln!(out)?;+ render_log_section(out, repo, "HOOK OUTPUT", is_hook_output_file)?;+ writeln!(out)?;+ render_log_section(out, repo, "DIAGNOSTIC", is_diagnostic_file)?;Ok(())}@@ -234,9 +234,7 @@ pub fn handle_logs_get(hook: Option<String>, branch: Option<String>) -> anyhow::None => {// No hook specified, show all log fileslet mut out = String::new();- render_command_log(&mut out, &repo)?;- writeln!(out)?;- render_hook_output(&mut out, &repo)?;+ render_all_log_sections(&mut out, &repo)?;// Display through pager (fall back to stderr if pager unavailable)if show_help_in_pager(&out, true).is_err() {@@ -381,9 +379,7 @@ pub fn handle_state_get(key: &str, branch: Option<String>) -> anyhow::Result<()>// TODO: Consider simplifying to just print the path and let users run `ls -al` themselves"logs" => {let mut out = String::new();- render_command_log(&mut out, &repo)?;- writeln!(out)?;- render_hook_output(&mut out, &repo)?;+ render_all_log_sections(&mut out, &repo)?;// Display through pager (fall back to stderr if pager unavailable)if show_help_in_pager(&out, true).is_err() {@@ -757,57 +753,63 @@ fn handle_state_show_json(repo: &Repository) -> anyhow::Result<()> {}).collect();- // Get log files, partitioned into command log and hook output+ // Get log files, partitioned into command log, hook output, and diagnosticlet log_dir = repo.wt_logs_dir();- let (command_log, hook_output): (Vec<serde_json::Value>, Vec<serde_json::Value>) =- if log_dir.exists() {- let mut all_entries: Vec<_> = std::fs::read_dir(&log_dir)?- .filter_map(|e| e.ok())- .filter(|e| e.path().is_file() && is_wt_log_file(&e.path()))- .collect();-- all_entries.sort_by(|a, b| {- let a_time = a.metadata().and_then(|m| m.modified()).ok();- let b_time = b.metadata().and_then(|m| m.modified()).ok();- b_time.cmp(&a_time)- });+ let (command_log, hook_output, diagnostic): (+ Vec<serde_json::Value>,+ Vec<serde_json::Value>,+ Vec<serde_json::Value>,+ ) = if log_dir.exists() {+ let mut all_entries: Vec<_> = std::fs::read_dir(&log_dir)?+ .filter_map(|e| e.ok())+ .filter(|e| e.path().is_file() && is_wt_log_file(&e.path()))+ .collect();- let to_json = |entry: &std::fs::DirEntry| -> serde_json::Value {- let path = entry.path();- let name = path- .file_name()- .unwrap_or_default()- .to_string_lossy()- .to_string();- let meta = entry.metadata().ok();- let size = meta.as_ref().map(|m| m.len()).unwrap_or(0);- let modified = meta- .and_then(|m| m.modified().ok())- .and_then(|t| t.duration_since(std::time::UNIX_EPOCH).ok())- .map(|d| d.as_secs());+ all_entries.sort_by(|a, b| {+ let a_time = a.metadata().and_then(|m| m.modified()).ok();+ let b_time = b.metadata().and_then(|m| m.modified()).ok();+ b_time.cmp(&a_time)+ });- serde_json::json!({- "file": name,- "size": size,- "modified_at": modified- })- };+ let to_json = |entry: &std::fs::DirEntry| -> serde_json::Value {+ let path = entry.path();+ let name = path+ .file_name()+ .unwrap_or_default()+ .to_string_lossy()+ .to_string();+ let meta = entry.metadata().ok();+ let size = meta.as_ref().map(|m| m.len()).unwrap_or(0);+ let modified = meta+ .and_then(|m| m.modified().ok())+ .and_then(|t| t.duration_since(std::time::UNIX_EPOCH).ok())+ .map(|d| d.as_secs());- let mut cmd_log = Vec::new();- let mut hook_out = Vec::new();- for entry in &all_entries {- let name = entry.file_name().to_string_lossy().to_string();- if is_command_log_file(&name) {- cmd_log.push(to_json(entry));- } else {- hook_out.push(to_json(entry));- }- }- (cmd_log, hook_out)- } else {- (vec![], vec![])+ serde_json::json!({+ "file": name,+ "size": size,+ "modified_at": modified+ })};+ let mut cmd_log = Vec::new();+ let mut hook_out = Vec::new();+ let mut diagnostic = Vec::new();+ for entry in &all_entries {+ let name = entry.file_name().to_string_lossy().to_string();+ if is_command_log_file(&name) {+ cmd_log.push(to_json(entry));+ } else if is_diagnostic_file(&name) {+ diagnostic.push(to_json(entry));+ } else {+ hook_out.push(to_json(entry));+ }+ }+ (cmd_log, hook_out, diagnostic)+ } else {+ (vec![], vec![], vec![])+ };+// Get vars data (all branches) — collect into BTreeMap for sorted outputlet all_vars: std::collections::BTreeMap<_, _> = repo.all_vars_entries().into_iter().collect();let vars_data: Vec<serde_json::Value> = all_vars@@ -834,6 +836,7 @@ fn handle_state_show_json(repo: &Repository) -> anyhow::Result<()> {"vars": vars_data,"command_log": command_log,"hook_output": hook_output,+ "diagnostic": diagnostic,"hints": hints});@@ -950,12 +953,8 @@ fn handle_state_show_table(repo: &Repository) -> anyhow::Result<()> {}writeln!(out)?;- // Show command log- render_command_log(&mut out, repo)?;- writeln!(out)?;-- // Show hook output logs- render_hook_output(&mut out, repo)?;+ // Show log files+ render_all_log_sections(&mut out, repo)?;// Display through pager (fall back to stderr if pager unavailable)if let Err(e) = show_help_in_pager(&out, true) {diff --git a/tests/integration_tests/config_state.rs b/tests/integration_tests/config_state.rsindex 7e17e0f24..156dabbf4 100644--- a/tests/integration_tests/config_state.rs+++ b/tests/integration_tests/config_state.rs@@ -24,9 +24,10 @@ fn internal_log_filename(branch: &str, op: &str) -> String {/// Settings for `wt config state get` snapshots (normalizes log paths)fn state_get_settings() -> insta::Settings {let mut settings = insta::Settings::clone_current();- // COMMAND LOG / HOOK OUTPUT paths vary per test (temp dir), normalize for stable snapshots+ // COMMAND LOG / HOOK OUTPUT / DIAGNOSTIC paths vary per test (temp dir), normalize for stable snapshotssettings.add_filter(r"(COMMAND LOG\x1b\[39m\s+@ )[^\n]+", "${1}<PATH>");settings.add_filter(r"(HOOK OUTPUT\x1b\[39m\s+@ )[^\n]+", "${1}<PATH>");+ settings.add_filter(r"(DIAGNOSTIC\x1b\[39m\s+@ )[^\n]+", "${1}<PATH>");settings}@@ -472,6 +473,9 @@ fn test_state_get_logs_empty(repo: TestRepo) {[36mHOOK OUTPUT[39m @ <PATH>[107m [0m (none)++ [36mDIAGNOSTIC[39m @ <PATH>+ [107m [0m (none)");});}@@ -494,18 +498,22 @@ fn test_state_get_logs_with_files(repo: TestRepo) {assert!(output.status.success());let mut settings = state_get_settings();// File sizes and ages vary across environments- settings.add_filter(r"(?m)\d+[BK]\s+\S+\s*$", "<SIZE> <AGE>");+ settings.add_filter(r"(?m)\d+[BK]\s+\S+[ \t]*$", "<SIZE> <AGE>");settings.bind(|| {assert_snapshot!(String::from_utf8_lossy(&output.stderr), @"[36mCOMMAND LOG[39m @ <PATH>File Size Age────────────── ──── ──────commands.jsonl <SIZE> <AGE>+[36mHOOK OUTPUT[39m @ <PATH>File Size Age────────────────────────── ──── ──────bugfix-remove.log <SIZE> <AGE>feature-post-start-npm.log <SIZE> <AGE>++ [36mDIAGNOSTIC[39m @ <PATH>+ [107m [0m (none)");});}@@ -528,10 +536,75 @@ fn test_state_get_logs_dir_exists_no_log_files(repo: TestRepo) {[36mHOOK OUTPUT[39m @ <PATH>[107m [0m (none)++ [36mDIAGNOSTIC[39m @ <PATH>+ [107m [0m (none)");});}+#[rstest]+fn test_state_get_logs_diagnostic_files(repo: TestRepo) {+ // Create wt/logs directory with diagnostic files+ let git_dir = repo.root_path().join(".git");+ let log_dir = git_dir.join("wt/logs");+ std::fs::create_dir_all(&log_dir).unwrap();+ std::fs::write(log_dir.join("verbose.log"), "debug output").unwrap();+ std::fs::write(log_dir.join("diagnostic.md"), "# Diagnostic Report").unwrap();+ // Also add a hook output file to verify separation+ std::fs::write(log_dir.join("feature-remove.log"), "remove output").unwrap();++ let output = wt_state_cmd(&repo, "logs", "get", &[]).output().unwrap();+ assert!(output.status.success());+ let stderr = String::from_utf8_lossy(&output.stderr);++ // Diagnostic files appear under DIAGNOSTIC, not HOOK OUTPUT+ assert!(stderr.contains("DIAGNOSTIC"), "Expected DIAGNOSTIC heading");+ assert!(+ stderr.contains("verbose.log"),+ "Expected verbose.log in output"+ );+ assert!(+ stderr.contains("diagnostic.md"),+ "Expected diagnostic.md in output"+ );++ // Hook output should have the remove log but not the diagnostic files+ let hook_section = stderr+ .split("DIAGNOSTIC")+ .next()+ .unwrap()+ .rsplit("HOOK OUTPUT")+ .next()+ .unwrap();+ assert!(+ hook_section.contains("feature-remove.log"),+ "Expected feature-remove.log in HOOK OUTPUT: {hook_section}"+ );+ assert!(+ !hook_section.contains("verbose.log"),+ "verbose.log should not be in HOOK OUTPUT: {hook_section}"+ );+}++#[rstest]+fn test_state_clear_logs_includes_diagnostic_files(repo: TestRepo) {+ // diagnostic files (.log and .md) should be cleared+ let git_dir = repo.root_path().join(".git");+ let log_dir = git_dir.join("wt/logs");+ std::fs::create_dir_all(&log_dir).unwrap();+ std::fs::write(log_dir.join("verbose.log"), "debug output").unwrap();+ std::fs::write(log_dir.join("diagnostic.md"), "# Report").unwrap();++ let output = wt_state_cmd(&repo, "logs", "clear", &[]).output().unwrap();+ assert!(output.status.success());+ assert_snapshot!(+ String::from_utf8_lossy(&output.stderr),+ @"[32m✓[39m [32mCleared [1m2[22m log files[39m"+ );+ assert!(!log_dir.exists());+}+#[rstest]fn test_state_clear_logs_empty(repo: TestRepo) {let output = wt_state_cmd(&repo, "logs", "clear", &[]).output().unwrap();@@ -737,6 +810,9 @@ fn test_state_get_empty(repo: TestRepo) {[36mHOOK OUTPUT[39m @ <PATH>[107m [0m (none)++ [36mDIAGNOSTIC[39m @ <PATH>+ [107m [0m (none)");});}@@ -843,6 +919,7 @@ fn test_state_get_json_empty(repo: TestRepo) {"ci_status": [],"command_log": [],"default_branch": "main",+ "diagnostic": [],"hints": [],"hook_output": [],"markers": [],@@ -899,6 +976,7 @@ fn test_state_get_json_comprehensive(repo: TestRepo) {],"command_log": [],"default_branch": "main",+ "diagnostic": [],"hints": [],"hook_output": [],"markers": [@@ -959,6 +1037,7 @@ fn test_state_get_json_with_logs(repo: TestRepo) {}],"default_branch": "main",+ "diagnostic": [],"hints": [],"hook_output": [{diff --git a/tests/snapshots/integration__integration_tests__config_state__state_get_comprehensive.snap b/tests/snapshots/integration__integration_tests__config_state__state_get_comprehensive.snapindex 59fbd0733..ac1f64ffe 100644--- a/tests/snapshots/integration__integration_tests__config_state__state_get_comprehensive.snap+++ b/tests/snapshots/integration__integration_tests__config_state__state_get_comprehensive.snap@@ -36,3 +36,6 @@ expression: "String::from_utf8_lossy(&output.stderr)"────────────────────────── ──── ──────bugfix-remove.log 13B futurefeature-post-start-npm.log 10B future++[36mDIAGNOSTIC[39m @ <PATH>+[107m [0m (none)diff --git a/tests/snapshots/integration__integration_tests__config_state__state_get_with_ci_entries.snap b/tests/snapshots/integration__integration_tests__config_state__state_get_with_ci_entries.snapindex 5c7142db5..529d418db 100644--- a/tests/snapshots/integration__integration_tests__config_state__state_get_with_ci_entries.snap+++ b/tests/snapshots/integration__integration_tests__config_state__state_get_with_ci_entries.snap@@ -29,3 +29,6 @@ expression: "String::from_utf8_lossy(&output.stderr)"[36mHOOK OUTPUT[39m @ <PATH>[107m [0m (none)++[36mDIAGNOSTIC[39m @ <PATH>+[107m [0m (none)diff --git a/tests/snapshots/integration__integration_tests__help__help_config_state_logs.snap b/tests/snapshots/integration__integration_tests__help__help_config_state_logs.snapindex e4fd68578..5970e957d 100644--- a/tests/snapshots/integration__integration_tests__help__help_config_state_logs.snap+++ b/tests/snapshots/integration__integration_tests__help__help_config_state_logs.snap@@ -60,7 +60,7 @@ View and manage logs from background operations.[1m[32mWhat's logged[0m-Two kinds of logs live in [2m.git/wt/logs/[0m:+Three kinds of logs live in [2m.git/wt/logs/[0m:[32mCommand log (`commands.jsonl`)[0m@@ -75,6 +75,15 @@ All hook executions and LLM commands are recorded automatically — one JSON objSource is [2muser[0m or [2mproject[0m depending on where the hook is defined.+[32mDiagnostic files[0m++ File Created when+ ───────────── ────────────────────────────────────+ [2mverbose.log[0m Running with [2m-vv[0m+ [2mdiagnostic.md[0m Running with [2m-vv[0m when warnings occur++[2mverbose.log[0m is overwritten on each [2m-vv[0m run. [2mdiagnostic.md[0m is a markdown report for pasting into GitHub issues — written only when warnings occur.+[1m[32mLocation[0mAll logs are stored in [2m.git/wt/logs/[0m (in the main worktree's git directory).