Skip to content

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.md
index 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 obj
Source 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.
+
### Location
All 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.md
index 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.md
index 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 obj
Source 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.
+
### Location
All 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.md
index 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.rs
index 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 obj
Source 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.
+
## Location
All 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.rs
index 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 files
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() {
@@ -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 diagnostic
let 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 output
let 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.rs
index 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 snapshots
settings.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) {
HOOK OUTPUT @ <PATH>
  (none)
+
+ DIAGNOSTIC @ <PATH>
+   (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), @"
COMMAND LOG @ <PATH>
File Size Age
────────────── ──── ──────
commands.jsonl <SIZE> <AGE>
+
HOOK OUTPUT @ <PATH>
File Size Age
────────────────────────── ──── ──────
bugfix-remove.log <SIZE> <AGE>
feature-post-start-npm.log <SIZE> <AGE>
+
+ DIAGNOSTIC @ <PATH>
+   (none)
");
});
}
@@ -528,10 +536,75 @@ fn test_state_get_logs_dir_exists_no_log_files(repo: TestRepo) {
HOOK OUTPUT @ <PATH>
  (none)
+
+ DIAGNOSTIC @ <PATH>
+   (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),
+ @"✓ Cleared 2 log files"
+ );
+ 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) {
HOOK OUTPUT @ <PATH>
  (none)
+
+ DIAGNOSTIC @ <PATH>
+   (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.snap
index 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 future
feature-post-start-npm.log 10B future
+
+DIAGNOSTIC @ <PATH>
+  (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.snap
index 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)"
HOOK OUTPUT @ <PATH>
  (none)
+
+DIAGNOSTIC @ <PATH>
+  (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.snap
index 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.
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`)
@@ -75,6 +75,15 @@ All hook executions and LLM commands are recorded automatically — one JSON obj
Source 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.
+
Location
All logs are stored in .git/wt/logs/ (in the main worktree's git directory).