Skip to content

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

refactor: standardize global state patterns and add discoverability docs (#756)

Maximilian Roos0346647766ae
diff --git a/src/config/deprecation.rs b/src/config/deprecation.rs
index 9a8c938b1..2862cb19f 100644
--- a/src/config/deprecation.rs
+++ b/src/config/deprecation.rs
@@ -19,11 +19,12 @@ use std::borrow::Cow;
use std::collections::HashSet;
use std::io::Write;
use std::path::{Path, PathBuf};
-use std::sync::Mutex;
+use std::sync::{LazyLock, Mutex};
/// Tracks which config paths have already shown deprecation warnings this process.
/// Prevents repeated warnings when config is loaded multiple times.
-static WARNED_PATHS: Mutex<Option<HashSet<PathBuf>>> = Mutex::new(None);
+static WARNED_PATHS: LazyLock<Mutex<HashSet<PathBuf>>> =
+ LazyLock::new(|| Mutex::new(HashSet::new()));
/// Hint name for project config deprecation warnings
const HINT_DEPRECATED_PROJECT_CONFIG: &str = "deprecated-project-config";
@@ -179,11 +180,10 @@ pub fn check_and_migrate(
let canonical_path = path.canonicalize().unwrap_or_else(|_| path.to_path_buf());
{
let mut guard = WARNED_PATHS.lock().unwrap();
- let warned = guard.get_or_insert_with(HashSet::new);
- if warned.contains(&canonical_path) {
+ if guard.contains(&canonical_path) {
return Ok(true); // Already warned, skip
}
- warned.insert(canonical_path.clone());
+ guard.insert(canonical_path.clone());
}
// Build the .new path: "config.toml" -> "config.toml.new"
diff --git a/src/git/repository/mod.rs b/src/git/repository/mod.rs
index 0f6421e00..09e9d3f87 100644
--- a/src/git/repository/mod.rs
+++ b/src/git/repository/mod.rs
@@ -18,7 +18,7 @@
use crate::shell_exec::Cmd;
use std::path::{Path, PathBuf};
-use std::sync::{Arc, OnceLock};
+use std::sync::{Arc, LazyLock, OnceLock};
use dashmap::DashMap;
use once_cell::sync::OnceCell;
@@ -118,9 +118,12 @@ pub enum ResolvedWorktree {
},
}
-/// Global base path for repository operations, set by -C flag
+/// Global base path for repository operations, set by -C flag.
static BASE_PATH: OnceLock<PathBuf> = OnceLock::new();
+/// Default base path when -C flag is not provided.
+static DEFAULT_BASE_PATH: LazyLock<PathBuf> = LazyLock::new(|| PathBuf::from("."));
+
/// Initialize the global base path for repository operations.
///
/// This should be called once at program startup from main().
@@ -131,10 +134,7 @@ pub fn set_base_path(path: PathBuf) {
/// Get the base path for repository operations.
fn base_path() -> &'static PathBuf {
- static DEFAULT: OnceLock<PathBuf> = OnceLock::new();
- BASE_PATH
- .get()
- .unwrap_or_else(|| DEFAULT.get_or_init(|| PathBuf::from(".")))
+ BASE_PATH.get().unwrap_or(&DEFAULT_BASE_PATH)
}
/// Repository state for git operations.
diff --git a/src/lib.rs b/src/lib.rs
index 26b72bed4..11897cf96 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,3 +1,25 @@
+//! Worktrunk library - git worktree management.
+//!
+//! # Global State
+//!
+//! Global state is intentionally scattered to live near its domain.
+//! All globals use safe patterns (`OnceLock`, `LazyLock`, `AtomicU8`, `thread_local!`).
+//!
+//! | Module | Global | Purpose |
+//! |--------|--------|---------|
+//! | [`shell_exec`] | `CMD_SEMAPHORE` | Limits concurrent command execution |
+//! | [`shell_exec`] | `TRACE_EPOCH` | Monotonic base for trace timestamps |
+//! | [`shell_exec`] | `SHELL_CONFIG` | Cached platform shell detection |
+//! | [`shell_exec`] | `COMMAND_TIMEOUT` | Thread-local timeout for Rayon workers |
+//! | [`styling`] | `VERBOSITY` | CLI verbosity level (`-v`, `-vv`) |
+//! | [`config::deprecation`](config) | `WARNED_PATHS` | Deduplicates deprecation warnings |
+//! | [`config::user`](config) | `CONFIG_PATH` | `--config` CLI override |
+//! | [`git::repository`](git) | `BASE_PATH` | `-C` flag override |
+//!
+//! Binary-only globals (declared in `main.rs`, not part of library API):
+//! - `src/output/global.rs`: `OUTPUT_STATE` - Shell integration directive file
+//! - `src/verbose_log.rs`: `VERBOSE_LOG` - Verbose log file handle
+
pub mod config;
pub mod git;
pub mod path;