Skip to content

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

docs: fix inaccurate logs documentation (#1986)

Maximilian Roos045fd2594152
diff --git a/CLAUDE.md b/CLAUDE.md
index 5712eea94..eb585434f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -238,12 +238,12 @@ if msg.contains("no merge base") { return Ok(true); }
When no structured alternative exists, document the fragility inline.
-## Background Operation Logs
+## Hook Output Logs
-All background logs are centralized in `.git/wt/logs/` (main worktree's git directory). Same operation on same branch overwrites the previous log.
+Hook output logs are centralized in `.git/wt/logs/` (main worktree's git directory). Same operation on same branch overwrites the previous log.
-- **Post-start commands**: `{branch}-{source}-post-start-{command}.log` (source: `user` or `project`)
-- **Background removal**: `{branch}-remove.log`
+- **Background hooks**: `{branch}-{hash}-{source}-{hook-type}-{name}-{hash}.log` (source: `user` or `project`)
+- **Background removal**: `{branch}-{hash}-remove.log`
## Coverage
diff --git a/docs/content/config.md b/docs/content/config.md
index 461867046..32490a6d1 100644
--- a/docs/content/config.md
+++ b/docs/content/config.md
@@ -580,7 +580,7 @@ State is stored in `.git/` (config entries and log files), separate from configu
- **ci-status**: CI/PR status for a branch (passed, running, failed, conflicts, no-ci, error)
- **marker**: Custom status marker for a branch (shown in `wt list`)
- **vars**: <span class="badge-experimental"></span> Custom variables per branch
-- **logs**: Background operation logs
+- **logs**: Operation and debug logs
### Examples
@@ -617,7 +617,7 @@ Usage: <b><span class=c>wt config state</span></b> <span class=c>[OPTIONS]</span
<b><span class=c>previous-branch</span></b> Previous branch (for <b>wt switch -</b>)
<b><span class=c>ci-status</span></b> CI status cache
<b><span class=c>marker</span></b> Branch markers
- <b><span class=c>logs</span></b> Background operation logs
+ <b><span class=c>logs</span></b> Operation and debug logs
<b><span class=c>hints</span></b> One-time hints shown in this repo
<b><span class=c>vars</span></b> [experimental] Custom variables per branch
<b><span class=c>get</span></b> Get all stored state
@@ -883,9 +883,9 @@ Usage: <b><span class=c>wt config state vars</span></b> <span class=c>[OPTIONS]<
## wt config state logs
-Background operation logs.
+Operation and debug logs.
-View and manage logs from background operations.
+View and manage log files — hook output, command audit trail, and debug diagnostics.
### What's logged
@@ -893,16 +893,27 @@ Three kinds of logs live in `.git/wt/logs/`:
#### Command log (`commands.jsonl`)
-All hook executions and LLM commands are recorded automatically — one JSON object per line with timestamp, command, exit code, and duration. Rotates to `commands.jsonl.old` at 1MB (~2MB total).
+All hook executions and LLM commands are recorded automatically — one JSON object per line. Rotates to `commands.jsonl.old` at 1MB (~2MB total). Fields:
+
+| Field | Description |
+|-------|-------------|
+| `ts` | ISO 8601 timestamp |
+| `wt` | The `wt` command that triggered this (e.g., `wt hook pre-merge --yes`) |
+| `label` | What ran (e.g., `pre-merge user:lint`, `commit.generation`) |
+| `cmd` | Shell command executed |
+| `exit` | Exit code (`null` for background commands) |
+| `dur_ms` | Duration in milliseconds (`null` for background commands) |
+
+The command log appends entries and is not branch-specific — it records all activity across all worktrees.
#### Hook output logs
| Operation | Log file |
|-----------|----------|
-| post-start hooks | `{branch}-{source}-post-start-{name}.log` |
-| Background removal | `{branch}-remove.log` |
+| Background hooks | `{branch}-{hash}-{source}-{hook-type}-{name}-{hash}.log` |
+| Background removal | `{branch}-{hash}-remove.log` |
-Source is `user` or `project` depending on where the hook is defined.
+All `post-*` hooks (post-start, post-switch, post-commit, post-merge) run in the background and produce log files. Source is `user` or `project`. Hash suffixes are added by filename sanitization. Same operation on same branch overwrites the previous log. Logs from deleted branches remain until manually cleared.
#### Diagnostic files
@@ -915,13 +926,7 @@ Source is `user` or `project` depending on where the hook is defined.
### Location
-All logs are stored in `.git/wt/logs/` (in the main worktree's git directory).
-
-### Behavior
-
-- **Overwrites** — Same operation on same branch overwrites previous log
-- **Persists** — Logs from deleted branches remain until manually cleared
-- **Shared** — All worktrees write to the same log directory
+All logs are stored in `.git/wt/logs/` (in the main worktree's git directory). All worktrees write to the same directory.
### Examples
@@ -932,7 +937,7 @@ Query the command log:
{{ terminal(cmd="tail -5 .git/wt/logs/commands.jsonl | jq .") }}
View a specific hook log:
-{{ terminal(cmd="cat __WT_QUOT__$(git rev-parse --git-dir)/wt/logs/feature-project-post-start-build.log__WT_QUOT__") }}
+{{ terminal(cmd="cat __WT_QUOT__$(git rev-parse --git-dir)/wt/logs/feature-a1b-project-post-start-build-seq.log__WT_QUOT__") }}
Clear all logs:
{{ terminal(cmd="wt config state logs clear") }}
@@ -940,13 +945,13 @@ Clear all logs:
### Command reference
{% terminal() %}
-wt config state logs - Background operation logs
+wt config state logs - Operation and debug logs
Usage: <b><span class=c>wt config state logs</span></b> <span class=c>[OPTIONS]</span> <span class=c>[COMMAND]</span>
<b><span class=g>Commands:</span></b>
<b><span class=c>get</span></b> Get log file paths
- <b><span class=c>clear</span></b> Clear background operation logs
+ <b><span class=c>clear</span></b> Clear all log files
<b><span class=g>Options:</span></b>
<b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>
diff --git a/docs/content/faq.md b/docs/content/faq.md
index 94ffbe235..63759555a 100644
--- a/docs/content/faq.md
+++ b/docs/content/faq.md
@@ -115,7 +115,7 @@ Worktrunk stores small amounts of cache and log data in the repository's `.git/`
|----------|---------|------------|
| `.git/config` keys under `worktrunk.*` | Cached default branch, switch history, branch markers, custom variables | Various commands |
| `.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/{branch}-*.log` | Background hook 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 |
@@ -123,7 +123,7 @@ Worktrunk stores small amounts of cache and log data in the repository's `.git/`
None of this is tracked by git or pushed to remotes.
-**To remove:** `wt config state clear` removes all worktrunk keys from `.git/config`, deletes CI cache, clears logs, and removes stale trash.
+**To remove:** `wt config state clear` removes all worktrunk data — config keys, CI cache, markers, hints, variables, logs, and stale trash.
### What Worktrunk does NOT create
@@ -156,7 +156,7 @@ Use `-D` to force-delete branches with unmerged changes. Use `--no-delete-branch
### Other cleanup
-- `wt config state clear` — removes cached state from `.git/config`, clears CI cache/logs, and removes stale trash from worktree removal
+- `wt config state clear` — removes all worktrunk data from `.git/` (config keys, CI cache, markers, hints, variables, logs, stale trash)
- `wt config shell uninstall` — removes shell integration from rc files
See [What files does Worktrunk create?](#what-files-does-worktrunk-create) for details.
@@ -191,7 +191,7 @@ Use `--yes` to bypass prompts (useful for CI/automation).
### Command log
-All hook executions and LLM commands are recorded in `.git/wt/logs/commands.jsonl` — one JSON object per line with timestamp, command, exit code, and duration. This provides a debugging trail without requiring `-vv` verbose output. The file rotates to `commands.jsonl.old` at 1MB, bounding storage to ~2MB.
+All hook executions and LLM commands are recorded in `.git/wt/logs/commands.jsonl` — one JSON object per line. Fields: `ts` (timestamp), `wt` (the wt command that triggered it), `label` (what ran, e.g., `pre-merge user:lint`), `cmd` (shell command), `exit` (exit code, `null` for background), `dur_ms` (duration, `null` for background). The file rotates to `commands.jsonl.old` at 1MB, bounding storage to ~2MB.
View the log with `wt config state logs get`, or query directly:
diff --git a/skills/worktrunk/reference/config.md b/skills/worktrunk/reference/config.md
index cfd3838fa..293d2a45b 100644
--- a/skills/worktrunk/reference/config.md
+++ b/skills/worktrunk/reference/config.md
@@ -585,7 +585,7 @@ State is stored in `.git/` (config entries and log files), separate from configu
- **ci-status**: CI/PR status for a branch (passed, running, failed, conflicts, no-ci, error)
- **marker**: Custom status marker for a branch (shown in `wt list`)
- **vars**: [experimental] Custom variables per branch
-- **logs**: Background operation logs
+- **logs**: Operation and debug logs
### Examples
@@ -636,7 +636,7 @@ Commands:
previous-branch Previous branch (for wt switch -)
ci-status CI status cache
marker Branch markers
- logs Background operation logs
+ logs Operation and debug logs
hints One-time hints shown in this repo
vars [experimental] Custom variables per branch
get Get all stored state
@@ -908,9 +908,9 @@ Global Options:
## wt config state logs
-Background operation logs.
+Operation and debug logs.
-View and manage logs from background operations.
+View and manage log files — hook output, command audit trail, and debug diagnostics.
### What's logged
@@ -918,16 +918,27 @@ Three kinds of logs live in `.git/wt/logs/`:
#### Command log (`commands.jsonl`)
-All hook executions and LLM commands are recorded automatically — one JSON object per line with timestamp, command, exit code, and duration. Rotates to `commands.jsonl.old` at 1MB (~2MB total).
+All hook executions and LLM commands are recorded automatically — one JSON object per line. Rotates to `commands.jsonl.old` at 1MB (~2MB total). Fields:
+
+| Field | Description |
+|-------|-------------|
+| `ts` | ISO 8601 timestamp |
+| `wt` | The `wt` command that triggered this (e.g., `wt hook pre-merge --yes`) |
+| `label` | What ran (e.g., `pre-merge user:lint`, `commit.generation`) |
+| `cmd` | Shell command executed |
+| `exit` | Exit code (`null` for background commands) |
+| `dur_ms` | Duration in milliseconds (`null` for background commands) |
+
+The command log appends entries and is not branch-specific — it records all activity across all worktrees.
#### Hook output logs
| Operation | Log file |
|-----------|----------|
-| post-start hooks | `{branch}-{source}-post-start-{name}.log` |
-| Background removal | `{branch}-remove.log` |
+| Background hooks | `{branch}-{hash}-{source}-{hook-type}-{name}-{hash}.log` |
+| Background removal | `{branch}-{hash}-remove.log` |
-Source is `user` or `project` depending on where the hook is defined.
+All `post-*` hooks (post-start, post-switch, post-commit, post-merge) run in the background and produce log files. Source is `user` or `project`. Hash suffixes are added by filename sanitization. Same operation on same branch overwrites the previous log. Logs from deleted branches remain until manually cleared.
#### Diagnostic files
@@ -940,13 +951,7 @@ Source is `user` or `project` depending on where the hook is defined.
### Location
-All logs are stored in `.git/wt/logs/` (in the main worktree's git directory).
-
-### Behavior
-
-- **Overwrites** — Same operation on same branch overwrites previous log
-- **Persists** — Logs from deleted branches remain until manually cleared
-- **Shared** — All worktrees write to the same log directory
+All logs are stored in `.git/wt/logs/` (in the main worktree's git directory). All worktrees write to the same directory.
### Examples
@@ -962,7 +967,7 @@ $ tail -5 .git/wt/logs/commands.jsonl | jq .
View a specific hook log:
```bash
-$ cat "$(git rev-parse --git-dir)/wt/logs/feature-project-post-start-build.log"
+$ cat "$(git rev-parse --git-dir)/wt/logs/feature-a1b-project-post-start-build-seq.log"
```
Clear all logs:
@@ -973,13 +978,13 @@ $ wt config state logs clear
### Command reference
```
-wt config state logs - Background operation logs
+wt config state logs - Operation and debug logs
Usage: wt config state logs [OPTIONS] [COMMAND]
Commands:
get Get log file paths
- clear Clear background operation logs
+ clear Clear all log files
Options:
-h, --help
diff --git a/skills/worktrunk/reference/faq.md b/skills/worktrunk/reference/faq.md
index 6ceb8a8b4..32cebcc96 100644
--- a/skills/worktrunk/reference/faq.md
+++ b/skills/worktrunk/reference/faq.md
@@ -108,7 +108,7 @@ Worktrunk stores small amounts of cache and log data in the repository's `.git/`
|----------|---------|------------|
| `.git/config` keys under `worktrunk.*` | Cached default branch, switch history, branch markers, custom variables | Various commands |
| `.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/{branch}-*.log` | Background hook 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 |
@@ -116,7 +116,7 @@ Worktrunk stores small amounts of cache and log data in the repository's `.git/`
None of this is tracked by git or pushed to remotes.
-**To remove:** `wt config state clear` removes all worktrunk keys from `.git/config`, deletes CI cache, clears logs, and removes stale trash.
+**To remove:** `wt config state clear` removes all worktrunk data — config keys, CI cache, markers, hints, variables, logs, and stale trash.
### What Worktrunk does NOT create
@@ -149,7 +149,7 @@ Use `-D` to force-delete branches with unmerged changes. Use `--no-delete-branch
### Other cleanup
-- `wt config state clear` — removes cached state from `.git/config`, clears CI cache/logs, and removes stale trash from worktree removal
+- `wt config state clear` — removes all worktrunk data from `.git/` (config keys, CI cache, markers, hints, variables, logs, stale trash)
- `wt config shell uninstall` — removes shell integration from rc files
See [What files does Worktrunk create?](#what-files-does-worktrunk-create) for details.
@@ -182,7 +182,7 @@ Use `--yes` to bypass prompts (useful for CI/automation).
### Command log
-All hook executions and LLM commands are recorded in `.git/wt/logs/commands.jsonl` — one JSON object per line with timestamp, command, exit code, and duration. This provides a debugging trail without requiring `-vv` verbose output. The file rotates to `commands.jsonl.old` at 1MB, bounding storage to ~2MB.
+All hook executions and LLM commands are recorded in `.git/wt/logs/commands.jsonl` — one JSON object per line. Fields: `ts` (timestamp), `wt` (the wt command that triggered it), `label` (what ran, e.g., `pre-merge user:lint`), `cmd` (shell command), `exit` (exit code, `null` for background), `dur_ms` (duration, `null` for background). The file rotates to `commands.jsonl.old` at 1MB, bounding storage to ~2MB.
View the log with `wt config state logs get`, or query directly:
diff --git a/src/cli/config.rs b/src/cli/config.rs
index bba4d0bbe..94dc2381f 100644
--- a/src/cli/config.rs
+++ b/src/cli/config.rs
@@ -438,7 +438,7 @@ $ wt config plugins opencode install
- **ci-status**: CI/PR status for a branch (passed, running, failed, conflicts, no-ci, error)
- **marker**: Custom status marker for a branch (shown in `wt list`)
- **vars**: [experimental] Custom variables per branch
-- **logs**: Background operation logs
+- **logs**: Operation and debug logs
## Examples
@@ -604,8 +604,9 @@ Without a subcommand, runs `get` for the current branch. For `--branch`, use `ge
action: Option<MarkerAction>,
},
- /// Background operation logs
- #[command(after_long_help = r#"View and manage logs from background operations.
+ /// Operation and debug logs
+ #[command(
+ after_long_help = r#"View and manage log files — hook output, command audit trail, and debug diagnostics.
## What's logged
@@ -613,16 +614,27 @@ Three kinds of logs live in `.git/wt/logs/`:
### Command log (`commands.jsonl`)
-All hook executions and LLM commands are recorded automatically — one JSON object per line with timestamp, command, exit code, and duration. Rotates to `commands.jsonl.old` at 1MB (~2MB total).
+All hook executions and LLM commands are recorded automatically — one JSON object per line. Rotates to `commands.jsonl.old` at 1MB (~2MB total). Fields:
+
+| Field | Description |
+|-------|-------------|
+| `ts` | ISO 8601 timestamp |
+| `wt` | The `wt` command that triggered this (e.g., `wt hook pre-merge --yes`) |
+| `label` | What ran (e.g., `pre-merge user:lint`, `commit.generation`) |
+| `cmd` | Shell command executed |
+| `exit` | Exit code (`null` for background commands) |
+| `dur_ms` | Duration in milliseconds (`null` for background commands) |
+
+The command log appends entries and is not branch-specific — it records all activity across all worktrees.
### Hook output logs
| Operation | Log file |
|-----------|----------|
-| post-start hooks | `{branch}-{source}-post-start-{name}.log` |
-| Background removal | `{branch}-remove.log` |
+| Background hooks | `{branch}-{hash}-{source}-{hook-type}-{name}-{hash}.log` |
+| Background removal | `{branch}-{hash}-remove.log` |
-Source is `user` or `project` depending on where the hook is defined.
+All `post-*` hooks (post-start, post-switch, post-commit, post-merge) run in the background and produce log files. Source is `user` or `project`. Hash suffixes are added by filename sanitization. Same operation on same branch overwrites the previous log. Logs from deleted branches remain until manually cleared.
### Diagnostic files
@@ -635,13 +647,7 @@ Source is `user` or `project` depending on where the hook is defined.
## Location
-All logs are stored in `.git/wt/logs/` (in the main worktree's git directory).
-
-## Behavior
-
-- **Overwrites** — Same operation on same branch overwrites previous log
-- **Persists** — Logs from deleted branches remain until manually cleared
-- **Shared** — All worktrees write to the same log directory
+All logs are stored in `.git/wt/logs/` (in the main worktree's git directory). All worktrees write to the same directory.
## Examples
@@ -657,13 +663,14 @@ $ tail -5 .git/wt/logs/commands.jsonl | jq .
View a specific hook log:
```console
-$ cat "$(git rev-parse --git-dir)/wt/logs/feature-project-post-start-build.log"
+$ cat "$(git rev-parse --git-dir)/wt/logs/feature-a1b-project-post-start-build-seq.log"
```
Clear all logs:
```console
$ wt config state logs clear
-```"#)]
+```"#
+ )]
Logs {
#[command(subcommand)]
action: Option<LogsAction>,
@@ -758,7 +765,7 @@ Stored in git config as `worktrunk.state.<branch>.vars.<key>`. Keys must contain
- **Vars**: Custom variables per branch
- **CI status**: Cached GitHub/GitLab CI status per branch (30s TTL)
- **Hints**: One-time hints that have been shown
-- **Log files**: Background operation logs
+- **Log files**: Operation and debug logs
CI cache entries show status, age, and the commit SHA they were fetched for."#)]
Get {
@@ -1035,7 +1042,7 @@ $ wt config state logs get --hook=user:post-start:server --branch=feature
format: SwitchFormat,
},
- /// Clear background operation logs
+ /// Clear all log files
Clear,
}
diff --git a/src/commands/config/state.rs b/src/commands/config/state.rs
index a88014743..6c0e5d729 100644
--- a/src/commands/config/state.rs
+++ b/src/commands/config/state.rs
@@ -465,16 +465,6 @@ pub fn handle_state_get(
println!("{status_str}");
}
}
- // TODO: Consider simplifying to just print the path and let users run `ls -al` themselves
- "logs" => {
- let mut out = String::new();
- 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() {
- eprintln!("{}", out);
- }
- }
_ => {
anyhow::bail!(
"Unknown key: {key}. Valid keys: default-branch, previous-branch, ci-status, marker, logs"
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_state.snap b/tests/snapshots/integration__integration_tests__help__help_config_state.snap
index 49afcebf2..592efd540 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_state.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_state.snap
@@ -42,7 +42,7 @@ Usage: wt config state [OPTIONS] <COMMAND>
previous-branch Previous branch (for wt switch -)
ci-status CI status cache
marker Branch markers
- logs Background operation logs
+ logs Operation and debug logs
hints One-time hints shown in this repo
vars [experimental] Custom variables per branch
get Get all stored state
@@ -71,7 +71,7 @@ State is stored in .git/ (config entries and log files), separate from c
- ci-status: CI/PR status for a branch (passed, running, failed, conflicts, no-ci, error)
- marker: Custom status marker for a branch (shown in wt list)
- vars: [experimental] Custom variables per branch
-- logs: Background operation logs
+- logs: Operation and debug logs
Examples
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_state_get.snap b/tests/snapshots/integration__integration_tests__help__help_config_state_get.snap
index 4bda2b801..2f803294a 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_state_get.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_state_get.snap
@@ -65,6 +65,6 @@ Shows all stored state including:
- Vars: Custom variables per branch
- CI status: Cached GitHub/GitLab CI status per branch (30s TTL)
- Hints: One-time hints that have been shown
-- Log files: Background operation logs
+- Log files: Operation and debug logs
CI cache entries show status, age, and the commit SHA they were fetched for.
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 3574a0b99..ffe610f14 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
@@ -34,13 +34,13 @@ exit_code: 0
----- stdout -----
----- stderr -----
-wt config state logs - Background operation logs
+wt config state logs - Operation and debug logs
Usage: wt config state logs [OPTIONS] [COMMAND]
Commands:
get Get log file paths
- clear Clear background operation logs
+ clear Clear all log files
Options:
-h, --help
@@ -56,7 +56,7 @@ Usage: wt config state logs [OPTIONS] [COMMAND]
-v, --verbose...
Verbose output (-v: hooks, templates; -vv: debug report)
-View and manage logs from background operations.
+View and manage log files — hook output, command audit trail, and debug diagnostics.
What's logged
@@ -64,16 +64,27 @@ Three kinds of logs live in .git/wt/logs/:
Command log (`commands.jsonl`)
-All hook executions and LLM commands are recorded automatically — one JSON object per line with timestamp, command, exit code, and duration. Rotates to commands.jsonl.old at 1MB (~2MB total).
+All hook executions and LLM commands are recorded automatically — one JSON object per line. Rotates to commands.jsonl.old at 1MB (~2MB total). Fields:
+
+ Field Description
+ ────── ──────────────────────────────────────────────────────────────────
+ ts ISO 8601 timestamp
+ wt The wt command that triggered this (e.g., wt hook pre-merge --yes)
+ label What ran (e.g., pre-merge user:lint, commit.generation)
+ cmd Shell command executed
+ exit Exit code (null for background commands)
+ dur_ms Duration in milliseconds (null for background commands)
+
+The command log appends entries and is not branch-specific — it records all activity across all worktrees.
Hook output logs
- Operation Log file
- ────────────────── ───────────────────────────────────────
- post-start hooks {branch}-{source}-post-start-{name}.log
- Background removal {branch}-remove.log
+ Operation Log file
+ ────────────────── ──────────────────────────────────────────────────────
+ Background hooks {branch}-{hash}-{source}-{hook-type}-{name}-{hash}.log
+ Background removal {branch}-{hash}-remove.log
-Source is user or project depending on where the hook is defined.
+All post-* hooks (post-start, post-switch, post-commit, post-merge) run in the background and produce log files. Source is user or project. Hash suffixes are added by filename sanitization. Same operation on same branch overwrites the previous log. Logs from deleted branches remain until manually cleared.
Diagnostic files
@@ -86,13 +97,7 @@ Source is user or project depending on where the hook is defined
Location
-All logs are stored in .git/wt/logs/ (in the main worktree's git directory).
-
-Behavior
-
-- Overwrites — Same operation on same branch overwrites previous log
-- Persists — Logs from deleted branches remain until manually cleared
-- Shared — All worktrees write to the same log directory
+All logs are stored in .git/wt/logs/ (in the main worktree's git directory). All worktrees write to the same directory.
Examples
@@ -103,7 +108,7 @@ Query the command log:
  tail -5 .git/wt/logs/commands.jsonl | jq .
View a specific hook log:
-  cat "$(git rev-parse --git-dir)/wt/logs/feature-project-post-start-build.log"
+  cat "$(git rev-parse --git-dir)/wt/logs/feature-a1b-project-post-start-build-seq.log"
Clear all logs:
  wt config state logs clear