// ZSH-GIT-REPO-CACHE — ENGINEERING REPORT

>_EXECUTIVE SUMMARY

zsh-git-repo-cache is the indexing layer for "every git repo on the machine". The plugin crawls the root filesystem once with fd (or falls back to find), strips trailing /.git, removes macOS /System/Volumes read-only mirror prefixes, and writes the deduped, sorted list to $ZPWR_ALL_GIT_DIRS. A second pass walks each path with git diff-index --quiet HEAD + git ls-files --exclude-standard --others and bisects the master list into a dirty and clean cache. All queries — live and cache-backed, list and fzf-interactive — are 6 thin shims over those three files. The plugin is the upstream feeder for cd-like fzf workflows in zpwr; its job is to make the master list cheap enough that the prompt can read it on every command.

#FILE STRUCTURE

Every autoload file follows the canonical zsh-plugin pattern: # -*- mode: sh -*- + function name(){...} + a trailing self-call so the file is also source-able as a script. Stems match function names, so fpath autoload + direct source both resolve identically.

$DATA MODEL

Three plain-text caches under $HOME, one path per line, sorted + deduped. No SQLite, no LMDB, no on-disk format version — the file format is "newline-separated absolute paths." Reading is cat + fzf; writing is sort | uniq. The format choice is load-bearing for the prompt-read use case: read -t0 against a flat file is the fastest possible "is this repo dirty?" answer.

@SCAN PIPELINE

A single regenAllGitRepos invocation produces a fully normalized master list. Two-tool dispatch (fd when available, find as fallback) means the plugin works on a fresh box and gets the 8-thread fd speedup on developer machines. Two perl -i -pe passes strip trailing /.git and (on macOS) the read-only Apple-mounted mirror prefixes that would otherwise produce a 2x-duplicated list.

  /                                                  ZPWR_ALL_GIT_DIRS
   │                                                       ▲
   │ sudo fd '\.git$' / --type d --threads=8                │ sort | uniq
   │   --hidden --no-ignore        (or)  sudo find /        │
   ▼                              -name .git -type d -prune │
  ┌──────────────────────┐                                  │
  │ raw .git path stream │                                  │
  └─────────┬────────────┘                                  │
            │ perl -ne 'print "$1\n" if m{(/.*.git)/*$}'    │
            ▼                                                │
  ┌──────────────────────┐                                  │
  │ ZPWR_TEMPFILE3       │                                  │
  └─────────┬────────────┘                                  │
            │ perl -i -pe 's@/.git$@@'                       │
            │ perl -i -pe 's@^/System/Volumes/Data@@'       │ (macOS)
            │ perl -i -pe 's@^/System/Volumes/Update/mnt1@@'│ (macOS)
            ▼                                                │
  ┌──────────────────────┐                                  │
  │ normalized repo dirs │──────────────────────────────────┘
  └──────────────────────┘
            │
            │ regenAllGitReposDirty: walk + git diff-index --quiet HEAD
            │                       + git ls-files --exclude-standard --others
            ▼
  ┌──────────────────────┐    ┌──────────────────────┐
  │ ZPWR_ALL_GIT_DIRS_   │    │ ZPWR_ALL_GIT_DIRS_   │
  │ DIRTY (exec 3>)      │    │ CLEAN (exec 4>)      │
  └──────────────────────┘    └──────────────────────┘

The dirty/clean bisection writes to both files concurrently via two long-lived file descriptors (exec 3>, exec 4>) so a single while read loop over the master list produces both caches in one pass. Branch order matters: git diff-index --quiet HEAD first (cheapest, no I/O when clean), then git ls-files --exclude-standard --others only on the clean side to catch repos that have untracked files but no staged delta. Worktree is saved/restored via origPwd="$PWD" + builtin cd -q "$origPwd" at the end — the function is reentrant and won't poison the caller's CWD even on error.

&QUERY SURFACE

Two axes of query: live (walk master list, ask git fresh) vs cached (read pre-computed dirty/clean files), and list (stdout) vs fzf (interactive). Six query functions + 1 shared tail = full matrix. The cached path is the prompt-friendly one (no fork-per-repo); the live path is the up-to-the-second one (no stale-cache risk).

Each query fn defines two inner closures — zsh-git-repo-goThere (pipe through fzf, materialize a cd "..." command) and zsh-git-repo-listThere (raw stdout). The dispatch is one if [[ $cmd == list ]] guard; the regen guard (shouldRegen == regen OR cache missing OR cache empty) is identical across all 5 search variants so adding a new cache type is a copy-paste-rename, not a redesign.

~ZPWR VERB BINDINGS

When the plugin loads inside zpwr ((( ${+ZPWR_VERBS} )) guard), it registers 10 verbs into the global ZPWR_VERBS hash: 5 list-mode + 5 fzf-mode, full cross product of (all / clean / dirty / clean-cached / dirty-cached). Each value is the function name to run plus a free-text help line zpwr surfaces in its help screen.

*TEST COVERAGE

29 zunit @test cases across 6 test files pin behavioural invariants: plugin-contract (entrypoint name, zsh -n clean parse, #compdef directive on completions), function-level contract (autoload presence, ZPWR_VERBS values, defensive fallback definitions), and surface syntax (every autoload file parses, every fn name matches its file stem). 21 additional .sh doc-hygiene gates pin README/docs/workflow structure — final newlines, body+html tags, h1 presence, https-only links, target=_blank rel=noopener pairing, no inline handlers, no placeholder hrefs, no deprecated tags.

// DOC GATES

?KEY DESIGN DECISIONS

Each call-out is a decision the implementation could have gone either way on, with the rationale for the path taken.

!STRATEGIC POSITION

The plugin is the upstream feeder for any "jump to a git repo on this machine" workflow. zpwr's gitrepos* verbs are the public face; the same files back ad-hoc prompts, dirty-tree indicators, and CI-side audits ("which repos on this host have uncommitted work").

+LOAD MODEL

The plugin is autoload-clean: sourcing the entrypoint costs only env-var defaults + fpath append + 10 hash assignments. The 8 autoload functions don't run until called, and each runs the file body exactly once (the trailing self-call inside each file is also the autoload-time body). Zero git invocations, zero fd/find invocations, zero stat calls at source time.

.GIT POSTURE

42 commits on main. The repo carries no submodules, no generated artifacts, and no vendored deps — every byte is hand-written zsh + the docs cyberpunk template (hud-static.css + tutorial.css) shared across the MenkeTechnologies plugin stack. CI runs the zunit + doc-gate suite on every push (.github/workflows/ci.yml).

Compat floor: works on every zsh 5.x. Hard deps: zsh, perl (system perl, for the trailing-slash + Volumes-mirror strip passes), git. Soft deps: fd (accelerated crawl), fzf (interactive pick), sudo (full-disk crawl). No deps on zpwr — the plugin works standalone, ZPWR_VERBS is opt-in.