Skip to content

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

docs(claude): relocate Hook Output Logs and Repository Caching out of root CLAUDE.md (#2825)

Maximilian Roos4d5dfde5d8fa
diff --git a/CLAUDE.md b/CLAUDE.md
index 7a3ae7187..246740f33 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -118,13 +118,7 @@ Why: wt installs a `signal_hook` SIGINT/SIGTERM handler so it can forward signal
## Hook Output Logs
-Centralized in `.git/wt/logs/` (the main worktree's git directory). Per-branch logs live in subtrees; the same operation on the same branch overwrites the previous log.
-
-- Background hooks: `{branch}/{source}/{hook-type}/{name}.log` (source: `user` or `project`)
-- Background removal: `{branch}/internal/remove.log`
-- Repo-wide internal ops (e.g. trash sweep): `internal/{op}.log` (no branch segment)
-
-Top-level *files* are shared logs (`commands.jsonl*`, `trace.log`, `output.log`, `diagnostic.md`); the top-level `internal/` directory holds repo-wide internal-op logs; every other top-level directory is a per-branch tree. Branch and hook names go through `sanitize_for_filename` (already-safe names pass through; invalid characters become `-` plus a short collision-avoidance hash).
+`.git/wt/logs/` layout — per-branch and repo-wide log paths, plus the `sanitize_for_filename` filename rule: the `HookLog` spec in `src/commands/process.rs`. The top-level file-vs-directory split that `wt config state` walks: the "Log layout invariant" in `src/commands/config/state.rs`.
## Coverage
@@ -182,7 +176,7 @@ No `get_*` — bare nouns follow Rust stdlib convention.
## Repository Caching
-`Repository` caches read-only values (remote URLs, config, branch metadata) via `Arc<RepoCache>`; cloning a Repository shares the cache. **Not cached** (they mutate mid-command): `is_dirty()`, `head_sha()` (a stale SHA would surface in `{{ commit }}` for hooks firing after the move). `list_worktrees()` *is* cached even though `wt switch --create` / `wt remove` mutate the list — a mutating path must not re-read the list through the same `Repository` after its own mutation: read once up front and thread the slice through, or call `Repository::at(...)` for a fresh cache before any post-mutation probe. Patterns and the full contract: `RepoCache` in `src/git/repository/mod.rs`.
+`Repository` caches read-only values via `Arc<RepoCache>` (cloning shares it). What is and isn't cached, the `list_worktrees()` post-mutation invariant, and the two storage patterns: the `# Caching` section in `src/git/repository/mod.rs`.
## Releases
diff --git a/src/commands/process.rs b/src/commands/process.rs
index d9ead528e..e12d51799 100644
--- a/src/commands/process.rs
+++ b/src/commands/process.rs
@@ -29,9 +29,17 @@ pub enum InternalOp {
/// This is the single source of truth for hook log file paths.
/// Used by log creation in `spawn_detached` to place background hook output.
///
+/// All hook output is centralized under the main worktree's `.git/wt/logs/`
+/// directory (`Repository::wt_logs_dir()`); per-branch logs live in subtrees,
+/// and rerunning the same operation on the same branch overwrites its previous
+/// log. The complementary categorization rule — top-level *files* are shared
+/// logs, top-level *directories* are per-branch trees — is the "Log layout
+/// invariant" documented in `commands::config::state`.
+///
/// # Log file layout
///
/// Hook commands produce logs at: `{branch}/{source}/{hook-type}/{name}.log`
+/// (`source` is `user` or `project`)
/// - Example: `feature/user/post-start/server.log`
///
/// Per-branch internal operations produce logs at: `{branch}/internal/{op}.log`