Skip to content

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

docs: update stale documentation and fix version snapshot filter (#1113)

Maximilian Roos8587b660802a
diff --git a/.claude/skills/pr-review/SKILL.md b/.claude/skills/pr-review/SKILL.md
index 2ffc236ec..a9c1bef4f 100644
--- a/.claude/skills/pr-review/SKILL.md
+++ b/.claude/skills/pr-review/SKILL.md
@@ -105,6 +105,19 @@ tactical checklist.
- Are the changes adequately tested?
- Do the tests follow the project's testing conventions (see tests/CLAUDE.md)?
+**Documentation accuracy:**
+
+When a PR changes behavior, check that related documentation still matches.
+This is a common source of staleness — new features get added or behavior
+changes, but help text, config comments, and doc pages aren't updated.
+
+- Does `after_long_help` in `src/cli/mod.rs` and `src/cli/config.rs` still
+ describe what the code does? (These are the primary sources for doc pages.)
+- Do inline TOML comments in config examples match the actual behavior?
+- Are references to CLI commands still valid? (e.g., a migration note
+ referencing `wt config show` when the right command is `wt config update`)
+- If a new feature was added, does the relevant help text mention it?
+
**Same pattern elsewhere:**
When a PR fixes a bug or changes a pattern, search for the same pattern in
diff --git a/CLAUDE.md b/CLAUDE.md
index 1cb44bd7a..9235e369d 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -119,7 +119,7 @@ Ask: "Does `--help` still describe what the code does?" If not, update `src/cli/
Documentation has three categories:
-1. **Command pages** (config, hook, list, merge, remove, select, step, switch):
+1. **Command pages** (config, hook, list, merge, remove, step, switch):
```
src/cli/mod.rs (PRIMARY SOURCE)
↓ test_command_pages_and_skill_files_are_in_sync
diff --git a/dev/config.example.toml b/dev/config.example.toml
index 7c204721c..ce579eae8 100644
--- a/dev/config.example.toml
+++ b/dev/config.example.toml
@@ -90,18 +90,10 @@
#
# - Project config (https://worktrunk.dev/config/#project-configuration) settings are shared with teammates.
# - User configs generally apply to all projects.
-# - User configs _also_ has a `[projects]` table which holds project-specific settings for the user, such as approved hook commands and worktree layout. That's what this section covers.
+# - User configs _also_ has a `[projects]` table which holds project-specific settings for the user, such as worktree layout and setting overrides. That's what this section covers.
#
# Entries are keyed by project identifier (e.g., `github.com/user/repo`).
#
-# #### Approved hook commands
-#
-# When a project hook runs for the first time, Worktrunk asks for approval. Approved commands are saved to `~/.config/worktrunk/approvals.toml` (separate from user config to allow dotfile management of config.toml).
-#
-# To reset, run `wt hook approvals clear`.
-#
-# > **Migration note:** Approvals were previously stored as `approved-commands` in config.toml. Run `wt config show` to generate a migration file that removes stale entries.
-#
# #### Setting overrides (Experimental)
#
# Override global user config for a specific project. Scalar values (like `worktree-path`) replace the global value. Hooks append — both global and per-project hooks run.
diff --git a/docs/content/config.md b/docs/content/config.md
index 485bfc173..c6bb768ca 100644
--- a/docs/content/config.md
+++ b/docs/content/config.md
@@ -169,18 +169,10 @@ For context:
- [Project config](@/config.md#project-configuration) settings are shared with teammates.
- User configs generally apply to all projects.
-- User configs _also_ has a `[projects]` table which holds project-specific settings for the user, such as approved hook commands and worktree layout. That's what this section covers.
+- User configs _also_ has a `[projects]` table which holds project-specific settings for the user, such as worktree layout and setting overrides. That's what this section covers.
Entries are keyed by project identifier (e.g., `github.com/user/repo`).
-#### Approved hook commands
-
-When a project hook runs for the first time, Worktrunk asks for approval. Approved commands are saved to `~/.config/worktrunk/approvals.toml` (separate from user config to allow dotfile management of config.toml).
-
-To reset, run `wt hook approvals clear`.
-
-> **Migration note:** Approvals were previously stored as `approved-commands` in config.toml. Run `wt config show` to generate a migration file that removes stale entries.
-
#### Setting overrides (Experimental)
Override global user config for a specific project. Scalar values (like `worktree-path`) replace the global value. Hooks append — both global and per-project hooks run.
@@ -702,6 +694,14 @@ View and manage logs from background operations.
### What's logged
+Two 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).
+
+#### Hook output logs
+
| Operation | Log file |
|-----------|----------|
| post-start hooks | `{branch}-{source}-post-start-{name}.log` |
@@ -726,7 +726,12 @@ List all log files:
wt config state logs get
```
-View a specific log:
+Query the command log:
+```bash
+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"
```
diff --git a/docs/content/step.md b/docs/content/step.md
index ddf45b372..914e36740 100644
--- a/docs/content/step.md
+++ b/docs/content/step.md
@@ -36,6 +36,7 @@ wt step push
- `diff` — Show all changes since branching (committed, staged, unstaged, untracked)
- `copy-ignored` — Copy gitignored files between worktrees
- `for-each` — [experimental] Run a command in every worktree
+- `relocate` — [experimental] Move worktrees to expected paths
## See also
@@ -443,4 +444,101 @@ Usage: <b><span class=c>wt step for-each</span></b> <span class=c>[OPTIONS]</spa
Verbose output (-v: hooks, templates; -vv: debug report)
{% end %}
+## wt step relocate
+
+[experimental] Move worktrees to expected paths. Relocates worktrees whose path doesn't match the worktree-path template.
+
+Moves worktrees to match the configured `worktree-path` template.
+
+### Examples
+
+Preview what would be moved:
+
+```bash
+wt step relocate --dry-run
+```
+
+Move all mismatched worktrees:
+
+```bash
+wt step relocate
+```
+
+Auto-commit and clobber blockers (never fails):
+
+```bash
+wt step relocate --commit --clobber
+```
+
+Move specific worktrees:
+
+```bash
+wt step relocate feature bugfix
+```
+
+### Swap handling
+
+When worktrees are at each other's expected locations (e.g., `alpha` at
+`repo.beta` and `beta` at `repo.alpha`), relocate automatically resolves
+this by using a temporary location.
+
+### Clobbering
+
+With `--clobber`, non-worktree paths at target locations are moved to
+`<path>.bak-<timestamp>` before relocating.
+
+### Main worktree behavior
+
+The main worktree can't be moved with `git worktree move`. Instead, relocate
+switches it to the default branch and creates a new linked worktree at the
+expected path. Untracked and gitignored files remain at the original location.
+
+### Skipped worktrees
+
+- **Dirty** (without `--commit`) — use `--commit` to auto-commit first
+- **Locked** — unlock with `git worktree unlock`
+- **Target blocked** (without `--clobber`) — use `--clobber` to backup blocker
+- **Detached HEAD** — no branch to compute expected path
+
+Note: This command is experimental and may change in future versions.
+
+### Command reference
+
+{% terminal() %}
+wt step relocate - [experimental] Move worktrees to expected paths
+
+Relocates worktrees whose path doesn&#39;t match the <b>worktree-path</b> template.
+
+Usage: <b><span class=c>wt step relocate</span></b> <span class=c>[OPTIONS]</span> <span class=c>[BRANCHES]...</span>
+
+<b><span class=g>Arguments:</span></b>
+ <span class=c>[BRANCHES]...</span>
+ Worktrees to relocate (defaults to all mismatched)
+
+<b><span class=g>Options:</span></b>
+ <b><span class=c>--dry-run</span></b>
+ Show what would be moved
+
+ <b><span class=c>--commit</span></b>
+ Commit uncommitted changes before relocating
+
+ <b><span class=c>--clobber</span></b>
+ Backup non-worktree paths at target locations
+
+ Moves blocking paths to <b>&lt;path&gt;.bak-&lt;timestamp&gt;</b>.
+
+ <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>
+ Print help (see a summary with &#39;-h&#39;)
+
+<b><span class=g>Global Options:</span></b>
+ <b><span class=c>-C</span></b><span class=c> &lt;path&gt;</span>
+ Working directory for this command
+
+ <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</span>
+ User config file path
+
+ <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>
+ Verbose output (-v: hooks, templates; -vv: debug report)
+{% end %}
+
<!-- END AUTO-GENERATED from `wt step --help-page` -->
diff --git a/docs/demos/CLAUDE.md b/docs/demos/CLAUDE.md
index 068aec8e6..6d7c37b69 100644
--- a/docs/demos/CLAUDE.md
+++ b/docs/demos/CLAUDE.md
@@ -251,7 +251,7 @@ After spawning the shell, these files control Claude Code behavior:
- `$HOME/.claude.json` - Claude Code global config (onboarding flags, marketplace settings)
- `$HOME/.claude/settings.json` - Claude Code settings (statusLine config)
-- `$HOME/.config/worktrunk/config.toml` - Worktrunk user config (approved commands)
+- `$HOME/.config/worktrunk/config.toml` - Worktrunk user config
- `$HOME/w/acme/.config/wt.toml` - Project hooks config
Key fields in `.claude.json` for suppressing notifications:
diff --git a/skills/worktrunk/SKILL.md b/skills/worktrunk/SKILL.md
index 58b267496..4186ceab6 100644
--- a/skills/worktrunk/SKILL.md
+++ b/skills/worktrunk/SKILL.md
@@ -3,7 +3,7 @@ name: worktrunk
description: Guidance for Worktrunk, a CLI tool for managing git worktrees. Covers configuration (user config at ~/.config/worktrunk/config.toml and project hooks at .config/wt.toml), usage, and troubleshooting. Use for "setting up commit message generation", "configuring hooks", "automating tasks", or general worktrunk questions.
---
-<!-- worktrunk-skill-version: 0.9.3 -->
+<!-- worktrunk-skill-version: 0.26.1 -->
# Worktrunk
diff --git a/skills/worktrunk/reference/config.md b/skills/worktrunk/reference/config.md
index 83b4afb42..0cacadec1 100644
--- a/skills/worktrunk/reference/config.md
+++ b/skills/worktrunk/reference/config.md
@@ -161,18 +161,10 @@ For context:
- [Project config](https://worktrunk.dev/config/#project-configuration) settings are shared with teammates.
- User configs generally apply to all projects.
-- User configs _also_ has a `[projects]` table which holds project-specific settings for the user, such as approved hook commands and worktree layout. That's what this section covers.
+- User configs _also_ has a `[projects]` table which holds project-specific settings for the user, such as worktree layout and setting overrides. That's what this section covers.
Entries are keyed by project identifier (e.g., `github.com/user/repo`).
-#### Approved hook commands
-
-When a project hook runs for the first time, Worktrunk asks for approval. Approved commands are saved to `~/.config/worktrunk/approvals.toml` (separate from user config to allow dotfile management of config.toml).
-
-To reset, run `wt hook approvals clear`.
-
-> **Migration note:** Approvals were previously stored as `approved-commands` in config.toml. Run `wt config show` to generate a migration file that removes stale entries.
-
#### Setting overrides (Experimental)
Override global user config for a specific project. Scalar values (like `worktree-path`) replace the global value. Hooks append — both global and per-project hooks run.
@@ -682,6 +674,14 @@ View and manage logs from background operations.
### What's logged
+Two 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).
+
+#### Hook output logs
+
| Operation | Log file |
|-----------|----------|
| post-start hooks | `{branch}-{source}-post-start-{name}.log` |
@@ -706,7 +706,12 @@ List all log files:
wt config state logs get
```
-View a specific log:
+Query the command log:
+```bash
+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"
```
diff --git a/skills/worktrunk/reference/step.md b/skills/worktrunk/reference/step.md
index c25e6fa6d..e63597cd2 100644
--- a/skills/worktrunk/reference/step.md
+++ b/skills/worktrunk/reference/step.md
@@ -28,6 +28,7 @@ wt step push
- `diff` — Show all changes since branching (committed, staged, unstaged, untracked)
- `copy-ignored` — Copy gitignored files between worktrees
- `for-each` — [experimental] Run a command in every worktree
+- `relocate` — [experimental] Move worktrees to expected paths
## Command reference
@@ -419,3 +420,98 @@ Usage: <b><span class=c>wt step for-each</span></b> <span class=c>[OPTIONS]</spa
<b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>
Verbose output (-v: hooks, templates; -vv: debug report)
+
+## wt step relocate
+
+[experimental] Move worktrees to expected paths. Relocates worktrees whose path doesn't match the worktree-path template.
+
+Moves worktrees to match the configured `worktree-path` template.
+
+### Examples
+
+Preview what would be moved:
+
+```bash
+wt step relocate --dry-run
+```
+
+Move all mismatched worktrees:
+
+```bash
+wt step relocate
+```
+
+Auto-commit and clobber blockers (never fails):
+
+```bash
+wt step relocate --commit --clobber
+```
+
+Move specific worktrees:
+
+```bash
+wt step relocate feature bugfix
+```
+
+### Swap handling
+
+When worktrees are at each other's expected locations (e.g., `alpha` at
+`repo.beta` and `beta` at `repo.alpha`), relocate automatically resolves
+this by using a temporary location.
+
+### Clobbering
+
+With `--clobber`, non-worktree paths at target locations are moved to
+`<path>.bak-<timestamp>` before relocating.
+
+### Main worktree behavior
+
+The main worktree can't be moved with `git worktree move`. Instead, relocate
+switches it to the default branch and creates a new linked worktree at the
+expected path. Untracked and gitignored files remain at the original location.
+
+### Skipped worktrees
+
+- **Dirty** (without `--commit`) — use `--commit` to auto-commit first
+- **Locked** — unlock with `git worktree unlock`
+- **Target blocked** (without `--clobber`) — use `--clobber` to backup blocker
+- **Detached HEAD** — no branch to compute expected path
+
+Note: This command is experimental and may change in future versions.
+
+### Command reference
+
+wt step relocate - [experimental] Move worktrees to expected paths
+
+Relocates worktrees whose path doesn&#39;t match the <b>worktree-path</b> template.
+
+Usage: <b><span class=c>wt step relocate</span></b> <span class=c>[OPTIONS]</span> <span class=c>[BRANCHES]...</span>
+
+<b><span class=g>Arguments:</span></b>
+ <span class=c>[BRANCHES]...</span>
+ Worktrees to relocate (defaults to all mismatched)
+
+<b><span class=g>Options:</span></b>
+ <b><span class=c>--dry-run</span></b>
+ Show what would be moved
+
+ <b><span class=c>--commit</span></b>
+ Commit uncommitted changes before relocating
+
+ <b><span class=c>--clobber</span></b>
+ Backup non-worktree paths at target locations
+
+ Moves blocking paths to <b>&lt;path&gt;.bak-&lt;timestamp&gt;</b>.
+
+ <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>
+ Print help (see a summary with &#39;-h&#39;)
+
+<b><span class=g>Global Options:</span></b>
+ <b><span class=c>-C</span></b><span class=c> &lt;path&gt;</span>
+ Working directory for this command
+
+ <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</span>
+ User config file path
+
+ <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>
+ Verbose output (-v: hooks, templates; -vv: debug report)
diff --git a/src/cli/config.rs b/src/cli/config.rs
index e63135eb4..dc4b55fad 100644
--- a/src/cli/config.rs
+++ b/src/cli/config.rs
@@ -437,6 +437,14 @@ 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/`:
+
+### 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).
+
+### Hook output logs
+
| Operation | Log file |
|-----------|----------|
| post-start hooks | `{branch}-{source}-post-start-{name}.log` |
@@ -461,7 +469,12 @@ List all log files:
wt config state logs get
```
-View a specific log:
+Query the command log:
+```console
+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"
```
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index 27ca3459e..5802de3fc 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -1027,6 +1027,7 @@ wt step push
- `diff` — Show all changes since branching (committed, staged, unstaged, untracked)
- `copy-ignored` — Copy gitignored files between worktrees
- `for-each` — [experimental] Run a command in every worktree
+- `relocate` — [experimental] Move worktrees to expected paths
## See also
@@ -1035,7 +1036,8 @@ wt step push
<!-- subdoc: commit -->
<!-- subdoc: squash -->
<!-- subdoc: copy-ignored -->
-<!-- subdoc: for-each -->"#
+<!-- subdoc: for-each -->
+<!-- subdoc: relocate -->"#
)]
Step {
#[command(subcommand)]
@@ -1638,18 +1640,10 @@ For context:
- [Project config](@/config.md#project-configuration) settings are shared with teammates.
- User configs generally apply to all projects.
-- User configs _also_ has a `[projects]` table which holds project-specific settings for the user, such as approved hook commands and worktree layout. That's what this section covers.
+- User configs _also_ has a `[projects]` table which holds project-specific settings for the user, such as worktree layout and setting overrides. That's what this section covers.
Entries are keyed by project identifier (e.g., `github.com/user/repo`).
-#### Approved hook commands
-
-When a project hook runs for the first time, Worktrunk asks for approval. Approved commands are saved to `~/.config/worktrunk/approvals.toml` (separate from user config to allow dotfile management of config.toml).
-
-To reset, run `wt hook approvals clear`.
-
-> **Migration note:** Approvals were previously stored as `approved-commands` in config.toml. Run `wt config show` to generate a migration file that removes stale entries.
-
#### Setting overrides (Experimental)
Override global user config for a specific project. Scalar values (like `worktree-path`) replace the global value. Hooks append — both global and per-project hooks run.
diff --git a/tests/common/mod.rs b/tests/common/mod.rs
index fc4b4cd33..36237df13 100644
--- a/tests/common/mod.rs
+++ b/tests/common/mod.rs
@@ -2766,7 +2766,7 @@ fn setup_snapshot_settings_for_paths_with_home(
// wt version can be: v0.8.5, v0.8.5-2-gabcdef, v0.8.5-dirty, or bare git hash (b9ffe83)
// Format: "○ wt: <bold>VERSION</>" on its own line
settings.add_filter(
- r"(wt: \x1b\[1m)(?:v[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9]+-g[0-9a-f]+)?(?:-dirty)?|[0-9a-f]{7,40})",
+ r"(wt: \x1b\[1m)(?:v[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9]+-g[0-9a-f]+)?(?:-dirty)?|[0-9a-f]{7,40}(?:-dirty)?)",
"${1}[VERSION]",
);
// git version format: "○ git: <bold>VERSION</>" (e.g., "2.47.1")
@@ -2777,7 +2777,7 @@ fn setup_snapshot_settings_for_paths_with_home(
// Version check: "Up to date (<bold>VERSION</>)" or "current: VERSION)"
// version_str() can be: v0.8.5, v0.8.5-2-gabcdef, v0.8.5-dirty, 0.8.5, or bare hash (8465a1f)
settings.add_filter(
- r"(current: |Up to date \(\x1b\[1m)(?:v?[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9]+-g[0-9a-f]+)?(?:-dirty)?|[0-9a-f]{7,40})",
+ r"(current: |Up to date \(\x1b\[1m)(?:v?[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9]+-g[0-9a-f]+)?(?:-dirty)?|[0-9a-f]{7,40}(?:-dirty)?)",
"${1}[VERSION]",
);
diff --git a/tests/integration_tests/help.rs b/tests/integration_tests/help.rs
index b8e06078c..b9e66ede5 100644
--- a/tests/integration_tests/help.rs
+++ b/tests/integration_tests/help.rs
@@ -97,8 +97,9 @@ fn test_version() {
// Formats:
// - wt v0.4.0-25-gc9bcf6c0 (version with git commit info)
// - wt 7df940e (just git short hash in CI)
+ // - wt v0.4.0-dirty or wt 7df940e-dirty (uncommitted changes)
settings.add_filter(
- r"wt (v\d+\.\d+\.\d+(-[\w.-]+)?|[a-f0-9]{7,40})",
+ r"wt (v\d+\.\d+\.\d+(-[\w.-]+)?|[a-f0-9]{7,40}(?:-dirty)?)",
"wt [VERSION]",
);
settings.bind(|| {
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_create.snap b/tests/snapshots/integration__integration_tests__help__help_config_create.snap
index feb2376bc..dce90dc7c 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_create.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_create.snap
@@ -148,18 +148,10 @@ Creates ~/.config/worktrunk/config.toml with the following content:
#
# - Project config (https://worktrunk.dev/config/#project-configuration) settings are shared with teammates.
# - User configs generally apply to all projects.
- # - User configs _also_ has a `[projects]` table which holds project-specific settings for the user, such as approved hook commands and worktree layout. That's what this section covers.
+ # - User configs _also_ has a `[projects]` table which holds project-specific settings for the user, such as worktree layout and setting overrides. That's what this section covers.
#
# Entries are keyed by project identifier (e.g., `github.com/user/repo`).
#
- # #### Approved hook commands
- #
- # When a project hook runs for the first time, Worktrunk asks for approval. Approved commands are saved to `~/.config/worktrunk/approvals.toml` (separate from user config to allow dotfile management of config.toml).
- #
- # To reset, run `wt hook approvals clear`.
- #
- # > **Migration note:** Approvals were previously stored as `approved-commands` in config.toml. Run `wt config show` to generate a migration file that removes stale entries.
- #
# #### Setting overrides (Experimental)
#
# Override global user config for a specific project. Scalar values (like `worktree-path`) replace the global value. Hooks append — both global and per-project hooks run.
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_long.snap b/tests/snapshots/integration__integration_tests__help__help_config_long.snap
index edbab82d1..2240c16e8 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_long.snap
@@ -193,18 +193,10 @@ For context:
- Project config settings are shared with teammates.
- User configs generally apply to all projects.
-- User configs _also_ has a [projects] table which holds project-specific settings for the user, such as approved hook commands and worktree layout. That's what this section covers.
+- User configs _also_ has a [projects] table which holds project-specific settings for the user, such as worktree layout and setting overrides. That's what this section covers.
Entries are keyed by project identifier (e.g., github.com/user/repo).
-Approved hook commands
-
-When a project hook runs for the first time, Worktrunk asks for approval. Approved commands are saved to ~/.config/worktrunk/approvals.toml (separate from user config to allow dotfile management of config.toml).
-
-To reset, run wt hook approvals clear.
-
-> Migration note: Approvals were previously stored as approved-commands in config.toml. Run wt config show to generate a migration file that removes stale entries.
-
Setting overrides (Experimental)
Override global user config for a specific project. Scalar values (like worktree-path) replace the global value. Hooks append — both global and per-project hooks run.
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 232f9baf0..39cc5905e 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
@@ -17,10 +17,13 @@ info:
RUST_LOG: warn
SHELL: ""
TERM: alacritty
+ WORKTRUNK_APPROVALS_PATH: /nonexistent/test/approvals.toml
WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_SYSTEM_CONFIG_PATH: /etc/xdg/worktrunk/config.toml
WORKTRUNK_TEST_CLAUDE_INSTALLED: "0"
WORKTRUNK_TEST_DELAYED_STREAM_MS: "-1"
WORKTRUNK_TEST_EPOCH: "1735776000"
+ WORKTRUNK_TEST_NUSHELL_ENV: "0"
WORKTRUNK_TEST_POWERSHELL_ENV: "0"
WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
---
@@ -55,6 +58,14 @@ View and manage logs from background operations.
What's logged
+Two 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).
+
+Hook output logs
+
Operation Log file
────────────────── ───────────────────────────────────────
post-start hooks {branch}-{source}-post-start-{name}.log
@@ -77,7 +88,10 @@ All logs are stored in .git/wt-logs/ (in the main worktree's git directo
List all log files:
wt config state logs get
-View a specific log:
+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"
Clear all logs:
diff --git a/tests/snapshots/integration__integration_tests__help__help_step_long.snap b/tests/snapshots/integration__integration_tests__help__help_step_long.snap
index 1f30923a4..a33789c28 100644
--- a/tests/snapshots/integration__integration_tests__help__help_step_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_step_long.snap
@@ -17,6 +17,7 @@ info:
TERM: alacritty
WORKTRUNK_APPROVALS_PATH: /nonexistent/test/approvals.toml
WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_SYSTEM_CONFIG_PATH: /etc/xdg/worktrunk/config.toml
WORKTRUNK_TEST_CLAUDE_INSTALLED: "0"
WORKTRUNK_TEST_DELAYED_STREAM_MS: "-1"
WORKTRUNK_TEST_EPOCH: "1735776000"
@@ -81,6 +82,7 @@ Manual merge workflow with review between steps:
- diff — Show all changes since branching (committed, staged, unstaged, untracked)
- copy-ignored — Copy gitignored files between worktrees
- for-each — [experimental] Run a command in every worktree
+- relocate — [experimental] Move worktrees to expected paths
See also
diff --git a/tests/snapshots/integration__integration_tests__help__version.snap b/tests/snapshots/integration__integration_tests__help__version.snap
index 3703ed5f4..ae900cccb 100644
--- a/tests/snapshots/integration__integration_tests__help__version.snap
+++ b/tests/snapshots/integration__integration_tests__help__version.snap
@@ -14,10 +14,13 @@ info:
RUST_LOG: warn
SHELL: ""
TERM: alacritty
+ WORKTRUNK_APPROVALS_PATH: /nonexistent/test/approvals.toml
WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_SYSTEM_CONFIG_PATH: /etc/xdg/worktrunk/config.toml
WORKTRUNK_TEST_CLAUDE_INSTALLED: "0"
WORKTRUNK_TEST_DELAYED_STREAM_MS: "-1"
WORKTRUNK_TEST_EPOCH: "1735776000"
+ WORKTRUNK_TEST_NUSHELL_ENV: "0"
WORKTRUNK_TEST_POWERSHELL_ENV: "0"
WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
---