Skip to content

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

Add process-level singletons to caching spec (#2027)

Maximilian Roosa47448e8939c
diff --git a/src/git/repository/mod.rs b/src/git/repository/mod.rs
index 82cc66c3d..d1f56a473 100644
--- a/src/git/repository/mod.rs
+++ b/src/git/repository/mod.rs
@@ -45,6 +45,17 @@
//! - Code that mutates repository state (committing, creating worktrees) must not read
//! its own mutations through the cache. Use direct git commands for post-mutation
//! state.
+//!
+//! **Process-level singletons.** Outside `RepoCache`, several modules use `OnceLock`/`LazyLock`
+//! for process-global singletons that are computed once and never change:
+//! - Resource limiters: `CMD_SEMAPHORE` (shell_exec), `HEAVY_OPS_SEMAPHORE` (git),
+//! `LLM_SEMAPHORE` (summary), `COPY_POOL` (copy)
+//! - Global state: `OUTPUT_STATE` (output), `VERBOSE_LOG`, `COMMAND_LOG`
+//! - Config: `CONFIG_PATH` (config/user/path), `SHELL_CONFIG`, `GIT_ENV_OVERRIDES` (shell_exec)
+//!
+//! These are lazy initialization, not caches — they have no invalidation concerns
+//! because the container is initialized once and never replaced — unlike `RepoCache`,
+//! there is no risk of reading stale external state.
use std::io::{BufRead, BufReader, Write};
use std::path::{Path, PathBuf};