# How Worktrunk Caches Read-Only Git State for High-Performance CLI Operations > Discover how Worktrunk caches immutable Git metadata like branches and remotes for high-performance CLI operations. Learn how Arc eliminates redundant calls and shares state efficiently. - Repository: [Maximilian Roos/worktrunk](https://github.com/max-sixty/worktrunk) - Tags: performance - Published: 2026-09-14 --- **Worktrunk caches immutable Git metadata—branch names, remotes, and configuration—behind an `Arc` to eliminate redundant subprocess calls and share state efficiently across worktree operations.** Worktrunk is a Git worktree management tool designed to minimize command latency by maintaining an in-memory, read-only cache of repository state. Instead of invoking `git branch` or `git config` repeatedly, Worktrunk loads this immutable data once and shares it across all operations. This article examines the caching implementation found in the `max-sixty/worktrunk` repository, specifically how the `RepoCache` struct optimizes performance. ## The Core Caching Architecture The caching mechanism centers on the `RepoCache` struct, defined at line 229 in [`src/git/repository/mod.rs`](https://github.com/max-sixty/worktrunk/blob/main/src/git/repository/mod.rs). This structure acts as a centralized store for Git metadata that does not change during the lifetime of a repository session. The `Repository` type owns this cache through an `Arc`, specifically a field named `repo_cache`. Using an atomic reference counter allows multiple `Repository` clones—created when Worktrunk operates across several worktrees—to share the same cached data without duplication. ### What Gets Cached? `RepoCache` stores several categories of immutable Git state: - **Branch metadata** – including branch names, upstream tracking information, and HEAD OIDs. - **Remote definitions** – URLs and fetch specifications parsed from the repository configuration. - **Git configuration values** – Settings inherited from `.git/config` and system-level Git configuration. - **Reference snapshots** – Lightweight views of the ref namespace enabling fast lookups without repeated disk access. ### Shared State Across Worktrees Because the cache lives behind an `Arc`, every clone of the `Repository` struct points to the same underlying `RepoCache`. This design is critical for Worktrunk's performance when managing multiple worktrees, as it prevents redundant parsing of the same Git data for each worktree instance. ## Lazy Loading and Accessor Methods Worktrunk employs a lazy loading strategy to populate the cache. The first request for a specific piece of information triggers a Git subprocess, stores the result in the cache, and returns the data. All subsequent requests retrieve the value directly from memory. The `Repository` struct provides several accessor methods: - `Repository::branches()` – Returns a reference to the cached branch map. - `Repository::remotes()` – Returns the cached remote list. - `Repository::config()` – Returns the parsed Git configuration. These methods rely on internal helper functions such as `load_branches()`, `load_remotes()`, and `load_config()`. These helpers execute the actual Git commands—`git branch --format=…`, `git remote -v`, and `git config --list`—only on the first invocation. After the initial population, the helpers return the stored values without spawning new processes. ```rust // Create a Repository – it lazily builds the read-only cache. let repo = Repository::discover(".")?; // First call loads branches from Git (expensive). let branches = repo.branches()?; // Internally calls `git branch …` // Subsequent calls are cheap – the data comes from the cache. let same_branches = repo.branches()?; // No Git process spawned. ``` ## Why Read-Only Caching Is Safe Worktrunk never modifies Git data directly through the cache. All mutating operations—such as creating branches or deleting worktrees—execute via standard Git commands that update the on-disk repository. Because the cache contains only snapshots of the on-disk state, the data remains immutable after construction. This immutability makes the cache thread-safe without requiring additional synchronization primitives. When a command does mutate the repository, Worktrunk invalidates the relevant cache entries by either creating a fresh `Repository` instance or explicitly clearing the affected fields. Dropping the old `Repository` forces a new cache build on the next operation. ```rust // When a command mutates the repo, drop the old Repository // to force a fresh cache on the next operation. drop(repo); let repo = Repository::discover(".")?; // New cache built. ``` ## Performance Impact and Benchmarks By avoiding repeated Git subprocess calls for data that rarely changes, Worktrunk significantly reduces CLI latency. For example, the `wt list` command displays branch and remote information instantly because the heavy-weight `git branch` and `git remote` commands execute only once per repository session. The performance benefits are measurable and documented in [`benches/time_to_first_output.rs`](https://github.com/max-sixty/worktrunk/blob/main/benches/time_to_first_output.rs). These benchmarks demonstrate the speedup gained by eliminating redundant Git invocations, particularly when operations must reference the same metadata multiple times. ## Key Implementation Files The read-only caching layer spans several source files in the `max-sixty/worktrunk` repository: - **[`src/git/repository/mod.rs`](https://github.com/max-sixty/worktrunk/blob/main/src/git/repository/mod.rs)** – Contains the `RepoCache` struct definition at line 229 and the `Arc` integration. - **[`src/git/repository/branches.rs`](https://github.com/max-sixty/worktrunk/blob/main/src/git/repository/branches.rs)** – Implements lazy loading of branch data into the cache. - **[`src/git/repository/remotes.rs`](https://github.com/max-sixty/worktrunk/blob/main/src/git/repository/remotes.rs)** – Handles population of the remote cache. - **[`src/git/repository/config.rs`](https://github.com/max-sixty/worktrunk/blob/main/src/git/repository/config.rs)** – Parses and caches Git configuration values. - **[`src/git/repository/sha_cache.rs`](https://github.com/max-sixty/worktrunk/blob/main/src/git/repository/sha_cache.rs)** – Provides a secondary cache for object-ID lookups. - **[`benches/time_to_first_output.rs`](https://github.com/max-sixty/worktrunk/blob/main/benches/time_to_first_output.rs)** – Contains performance benchmarks validating the caching optimization. ## Summary - Worktrunk caches immutable Git state—branches, remotes, and configuration—in a `RepoCache` struct wrapped in an `Arc` for shared ownership. - The cache populates lazily: the first access executes Git commands, while subsequent reads return cached data instantly. - Located in [`src/git/repository/mod.rs`](https://github.com/max-sixty/worktrunk/blob/main/src/git/repository/mod.rs) at line 229, `RepoCache` enables thread-safe, read-only access to repository metadata. - Cache invalidation occurs by dropping the `Repository` instance or clearing specific fields when mutations occur. - Performance benchmarks in [`benches/time_to_first_output.rs`](https://github.com/max-sixty/worktrunk/blob/main/benches/time_to_first_output.rs) demonstrate measurable latency reductions for CLI commands. ## Frequently Asked Questions ### What specific Git data does Worktrunk cache? Worktrunk caches branch metadata (names, upstream tracking, and HEAD OIDs), remote definitions (URLs and fetch specifications), parsed configuration values from `.git/config`, and reference snapshots. These data structures remain immutable while the repository is open, making them safe to cache. ### How does Worktrunk share the cache across multiple worktrees? The `Repository` struct holds the cache behind an `Arc`. When Worktrunk clones the `Repository` instance to work with different worktrees, all instances share the same underlying cache through the atomic reference counter, preventing memory duplication and repeated Git calls. ### When does Worktrunk invalidate the read-only cache? Worktrunk invalidates the cache when Git operations modify the repository state. Because the cache is read-only, the system cannot update individual entries in place. Instead, Worktrunk either drops the existing `Repository` instance to create a fresh one with a new cache, or explicitly clears the affected cache fields to force reloading on the next access. ### Where is the cache implementation located in the source code? The primary cache definition resides in [`src/git/repository/mod.rs`](https://github.com/max-sixty/worktrunk/blob/main/src/git/repository/mod.rs) at line 229, where the `RepoCache` struct is defined. Supporting implementations for branches, remotes, and configuration exist in [`src/git/repository/branches.rs`](https://github.com/max-sixty/worktrunk/blob/main/src/git/repository/branches.rs), [`src/git/repository/remotes.rs`](https://github.com/max-sixty/worktrunk/blob/main/src/git/repository/remotes.rs), and [`src/git/repository/config.rs`](https://github.com/max-sixty/worktrunk/blob/main/src/git/repository/config.rs) respectively. Performance validation lives in [`benches/time_to_first_output.rs`](https://github.com/max-sixty/worktrunk/blob/main/benches/time_to_first_output.rs).