Skip to content

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

Limit concurrent command execution to prevent resource exhaustion (#239)

Maximilian Roosd42594be8786
diff --git a/benches/list.rs b/benches/list.rs
index f5a2f4567..4627f74af 100644
--- a/benches/list.rs
+++ b/benches/list.rs
@@ -251,7 +251,7 @@ fn add_worktree_with_divergence(
/// Benchmark time to render skeleton (before cell filling starts).
///
-/// Uses WT_SKELETON_ONLY=1 to exit after skeleton is rendered.
+/// Uses WORKTRUNK_SKELETON_ONLY=1 to exit after skeleton is rendered.
/// This measures the actual worktrunk code path: git I/O, parsing, layout, render skeleton.
fn bench_skeleton(c: &mut Criterion) {
let mut group = c.benchmark_group("skeleton");
@@ -292,7 +292,7 @@ fn bench_skeleton(c: &mut Criterion) {
b.iter(|| {
Command::new(&binary)
.arg("list")
- .env("WT_SKELETON_ONLY", "1")
+ .env("WORKTRUNK_SKELETON_ONLY", "1")
.current_dir(&repo_path)
.output()
.unwrap();
@@ -354,7 +354,7 @@ fn bench_skeleton_cold(c: &mut Criterion) {
|_| {
Command::new(&binary)
.arg("list")
- .env("WT_SKELETON_ONLY", "1")
+ .env("WORKTRUNK_SKELETON_ONLY", "1")
.current_dir(&repo_path)
.output()
.unwrap();
@@ -717,22 +717,6 @@ fn bench_sequential_vs_parallel(c: &mut Criterion) {
});
},
);
-
- // Benchmark sequential implementation (via WT_SEQUENTIAL env var)
- group.bench_with_input(
- BenchmarkId::new("sequential", num_worktrees),
- &num_worktrees,
- |b, _| {
- b.iter(|| {
- Command::new(&binary)
- .arg("list")
- .env("WT_SEQUENTIAL", "1")
- .current_dir(&repo_path)
- .output()
- .unwrap();
- });
- },
- );
}
group.finish();
diff --git a/docs/content/config.md b/docs/content/config.md
index a5fcb4314..43c637881 100644
--- a/docs/content/config.md
+++ b/docs/content/config.md
@@ -221,11 +221,12 @@ WORKTRUNK_COMMIT_GENERATION__ARGS="test: automated commit" \
wt merge
```
-### Special variables
+### Other environment variables
| Variable | Purpose |
|----------|---------|
-| `WORKTRUNK_CONFIG_PATH` | Override user config file location (not a config key) |
+| `WORKTRUNK_CONFIG_PATH` | Override user config file location |
+| `WORKTRUNK_MAX_CONCURRENT_COMMANDS` | Max parallel git commands (default: 32). Lower if hitting resource limits. |
| `NO_COLOR` | Disable colored output ([standard](https://no-color.org/)) |
| `CLICOLOR_FORCE` | Force colored output even when not a TTY |
diff --git a/docs/demos/wt/build b/docs/demos/wt/build
index 0f5e94080..86c5fc0ae 100755
--- a/docs/demos/wt/build
+++ b/docs/demos/wt/build
@@ -254,7 +254,6 @@ def record_text(demo_env: DemoEnv):
"PATH": f"{REPO_ROOT}/target/debug:{demo_env.home}/bin:{os.environ['PATH']}",
"STARSHIP_CONFIG": str(STARSHIP_CONFIG),
"STARSHIP_CACHE": str(demo_env.root / "starship-cache"),
- "WT_PROGRESSIVE": "false",
"NO_COLOR": "1",
"CLICOLOR": "0",
"NEXTEST_STATUS_LEVEL": "none",
diff --git a/src/cli.rs b/src/cli.rs
index d78899f36..d1aeb0363 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -1371,11 +1371,12 @@ WORKTRUNK_COMMIT_GENERATION__ARGS="test: automated commit" \
wt merge
```
-### Special variables
+### Other environment variables
| Variable | Purpose |
|----------|---------|
-| `WORKTRUNK_CONFIG_PATH` | Override user config file location (not a config key) |
+| `WORKTRUNK_CONFIG_PATH` | Override user config file location |
+| `WORKTRUNK_MAX_CONCURRENT_COMMANDS` | Max parallel git commands (default: 32). Lower if hitting resource limits. |
| `NO_COLOR` | Disable colored output ([standard](https://no-color.org/)) |
| `CLICOLOR_FORCE` | Force colored output even when not a TTY |
diff --git a/src/commands/list/collect.rs b/src/commands/list/collect.rs
index e4344e035..a17cc78f3 100644
--- a/src/commands/list/collect.rs
+++ b/src/commands/list/collect.rs
@@ -769,7 +769,7 @@ pub fn collect(
};
// Early exit for benchmarking skeleton render time
- if std::env::var("WT_SKELETON_ONLY").is_ok() {
+ if std::env::var("WORKTRUNK_SKELETON_ONLY").is_ok() {
return Ok(None);
}
diff --git a/src/commands/list/timing.rs b/src/commands/list/timing.rs
deleted file mode 100644
index bedbaddc0..000000000
--- a/src/commands/list/timing.rs
+++ /dev/null
@@ -1,130 +0,0 @@
-use std::collections::HashMap;
-use std::env;
-use std::sync::{Arc, Mutex};
-use std::time::{Duration, Instant};
-
-const DEBUG_ENV_VAR: &str = "WT_LIST_DEBUG";
-const DEBUG_ENV_VALUE: &str = "1";
-
-/// Operation names for tracking timing
-#[derive(Debug, Clone, Copy, Hash, Eq, PartialEq, strum::AsRefStr)]
-#[strum(serialize_all = "kebab-case")]
-pub enum OpName {
- CommitDetails,
- AheadBehind,
- UpstreamStatus,
- GitStatus,
- WorkingTreeDiff,
- WorkingTreeDiffWithMain,
- BranchDiff,
- GitOperation,
- // TODO(timing): Add PrStatus timing when CI/PR status collection is instrumented
- PrStatus,
- MergeConflicts,
- UserMarker,
-}
-
-/// Collects timing data for list operations.
-/// Thread-safe for use with parallel iterators (rayon).
-#[derive(Clone)]
-pub struct TimingCollector {
- inner: Option<Arc<Mutex<TimingData>>>,
-}
-
-#[derive(Default)]
-struct TimingData {
- timings: HashMap<OpName, Vec<Duration>>,
-}
-
-impl TimingCollector {
- /// Create a new collector if WT_LIST_DEBUG=1 is set
- pub fn new() -> Self {
- let enabled = env::var(DEBUG_ENV_VAR).ok().as_deref() == Some(DEBUG_ENV_VALUE);
- Self {
- inner: if enabled {
- Some(Arc::new(Mutex::new(TimingData::default())))
- } else {
- None
- },
- }
- }
-
- /// Execute a closure and record its timing
- pub fn measure<F, R>(&self, op: OpName, f: F) -> R
- where
- F: FnOnce() -> R,
- {
- if self.inner.is_none() {
- return f();
- }
-
- let start = Instant::now();
- let result = f();
- let duration = start.elapsed();
-
- if let Some(ref data) = self.inner {
- let mut guard = data.lock().unwrap();
- guard.timings.entry(op).or_default().push(duration);
- }
-
- result
- }
-
- /// Print timing summary to stderr
- pub fn print_summary(&self) {
- let Some(ref data) = self.inner else {
- return;
- };
-
- let guard = data.lock().unwrap();
- if guard.timings.is_empty() {
- return;
- }
-
- log::debug!("WT_LIST_DEBUG timing summary:");
-
- let mut ops: Vec<_> = guard.timings.iter().collect();
- ops.sort_by_key(|(op, _)| op.as_ref());
-
- for (op, durations) in ops {
- let stats = compute_stats(durations);
- log::debug!(
- " {:<30} median: {:>6.1}ms p95: {:>6.1}ms count: {}",
- op.as_ref(),
- stats.median_ms,
- stats.p95_ms,
- durations.len()
- );
- }
- }
-}
-
-struct Stats {
- median_ms: f64,
- p95_ms: f64,
-}
-
-fn compute_stats(durations: &[Duration]) -> Stats {
- let mut sorted: Vec<_> = durations.iter().map(|d| d.as_secs_f64() * 1000.0).collect();
- sorted.sort_by(|a, b| a.partial_cmp(b).unwrap());
-
- let median_ms = if sorted.is_empty() {
- 0.0
- } else {
- let mid = sorted.len() / 2;
- if sorted.len() % 2 == 0 {
- (sorted[mid - 1] + sorted[mid]) / 2.0
- } else {
- sorted[mid]
- }
- };
-
- let p95_ms = if sorted.is_empty() {
- 0.0
- } else {
- let idx = ((sorted.len() - 1) as f64 * 0.95).round() as usize;
- sorted[idx]
- };
-
- Stats { median_ms, p95_ms }
-}
diff --git a/src/git/mod.rs b/src/git/mod.rs
index e917f3363..539396348 100644
--- a/src/git/mod.rs
+++ b/src/git/mod.rs
@@ -7,7 +7,6 @@ mod diff;
mod error;
mod parse;
mod repository;
-mod semaphore;
#[cfg(test)]
mod test;
@@ -24,9 +23,9 @@ mod test;
// Heavy operations protected:
// - git rev-list --count (accesses commit-graph via mmap)
// - git diff --numstat (accesses pack files and indexes via mmap)
+use crate::sync::Semaphore;
use std::sync::LazyLock;
-static HEAVY_OPS_SEMAPHORE: LazyLock<semaphore::Semaphore> =
- LazyLock::new(|| semaphore::Semaphore::new(4));
+static HEAVY_OPS_SEMAPHORE: LazyLock<Semaphore> = LazyLock::new(|| Semaphore::new(4));
// Re-exports from submodules
pub use diff::{DiffStats, LineDiff};
diff --git a/src/lib.rs b/src/lib.rs
index c0bdf3ff9..596b7f7cd 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -4,6 +4,7 @@ pub mod path;
pub mod shell;
pub mod shell_exec;
pub mod styling;
+pub mod sync;
// Re-export HookType for convenience
pub use git::HookType;
diff --git a/src/shell_exec.rs b/src/shell_exec.rs
index e648dd544..2d497b367 100644
--- a/src/shell_exec.rs
+++ b/src/shell_exec.rs
@@ -19,6 +19,27 @@ use std::path::PathBuf;
use std::process::Command;
use std::sync::OnceLock;
+use crate::sync::Semaphore;
+
+/// Semaphore to limit concurrent command execution.
+/// Prevents resource exhaustion when spawning many parallel git commands.
+static CMD_SEMAPHORE: OnceLock<Semaphore> = OnceLock::new();
+
+/// Default concurrent external commands. Tuned to avoid hitting OS limits
+/// (file descriptors, process limits) while maintaining good parallelism.
+const DEFAULT_CONCURRENT_COMMANDS: usize = 32;
+
+fn max_concurrent_commands() -> usize {
+ std::env::var("WORKTRUNK_MAX_CONCURRENT_COMMANDS")
+ .ok()
+ .and_then(|s| s.parse().ok())
+ .unwrap_or(DEFAULT_CONCURRENT_COMMANDS)
+}
+
+fn get_semaphore() -> &'static Semaphore {
+ CMD_SEMAPHORE.get_or_init(|| Semaphore::new(max_concurrent_commands()))
+}
+
/// Cached shell configuration for the current platform
static SHELL_CONFIG: OnceLock<ShellConfig> = OnceLock::new();
@@ -209,6 +230,10 @@ pub fn run(cmd: &mut Command, context: Option<&str>) -> std::io::Result<std::pro
None => log::debug!("$ {}", cmd_str),
}
+ // Acquire semaphore to limit concurrent commands (prevents resource exhaustion)
+ // RAII guard ensures release even on panic
+ let _guard = get_semaphore().acquire();
+
let t0 = Instant::now();
let result = cmd.output();
let duration_ms = t0.elapsed().as_secs_f64() * 1000.0;
diff --git a/src/git/semaphore.rs b/src/sync.rs
similarity index 88%
rename from src/git/semaphore.rs
rename to src/sync.rs
index d1e582283..52da9fb3a 100644
--- a/src/git/semaphore.rs
+++ b/src/sync.rs
@@ -1,17 +1,20 @@
-//! Simple semaphore for limiting concurrent git operations.
-//!
-//! Used to prevent mmap thrash when many parallel git commands access shared
-//! resources like commit-graph and pack files.
+//! Synchronization primitives for worktrunk.
use std::sync::{Arc, Condvar, Mutex};
/// A counting semaphore for limiting concurrency.
+///
+/// Used to prevent resource exhaustion when many parallel operations need
+/// to run. Provides RAII-based permit management through [`SemaphoreGuard`].
#[derive(Clone)]
pub struct Semaphore {
state: Arc<(Mutex<usize>, Condvar)>,
}
/// RAII guard that releases a semaphore permit on drop.
+///
+/// Created by [`Semaphore::acquire`]. The permit is automatically released
+/// when this guard is dropped, even if the code panics.
pub struct SemaphoreGuard {
state: Arc<(Mutex<usize>, Condvar)>,
}
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 f409bffb7..f976885db 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_long.snap
@@ -225,10 +225,11 @@ Override the LLM command in CI to use a mock:
WORKTRUNK_COMMIT_GENERATION__ARGS="test: automated commit" \
 wt merge
-Special variables
-
- Variable Purpose
- ───────────────────── ─────────────────────────────────────────────────────
- WORKTRUNK_CONFIG_PATH Override user config file location (not a config key)
- NO_COLOR Disable colored output (standard)
- CLICOLOR_FORCE Force colored output even when not a TTY
+Other environment variables
+
+ Variable Purpose
+ ───────────────────────────────── ──────────────────────────────────────────────────────────────────────────
+ WORKTRUNK_CONFIG_PATH Override user config file location
+ WORKTRUNK_MAX_CONCURRENT_COMMANDS Max parallel git commands (default: 32). Lower if hitting resource limits.
+ NO_COLOR Disable colored output (standard)
+ CLICOLOR_FORCE Force colored output even when not a TTY