📖 Design Philosophy
The fundamental principle: read git's own filesystem state directly rather than spawning git subprocesses. Git's internal formats (.git/HEAD, .git/config, .git/packed-refs) are plain-text and machine-readable.
gitFilesystem.ts
Core filesystem reader: resolveGitDir, readGitHead, resolveRef, GitFileWatcher.
gitConfigParser.ts
Hand-written parser for .git/config INI format with section/subsection case rules.
gitignore.ts
Manages global gitignore at ~/.config/git/ignore.
gitOperationTracking.ts
Shell-agnostic regex detection of git operations.
ghAuthStatus.ts
Checks gh CLI auth using local keyring only - no network requests.
⚙️ Config Parser
Three-level lookup: section (case-insensitive), subsection (case-sensitive), key (case-insensitive). Values support unquoted, partially quoted, or fully quoted formats with backslash escapes.
💡 Section Header Parsing
[remote "origin"] parses to section='remote', subsection='origin'. Section names lowercased for matching; subsections are strict case-sensitive equality.
📁 Git Filesystem State
resolveGitDir
Handles worktrees and submodules where .git is a pointer file containing gitdir: path.
readGitHead
Parses .git/HEAD: 'ref: refs/heads/main' (branch) or 40-hex SHA (detached).
resolveRef
Checks loose ref file, then packed-refs, then worktree commonDir fallback.
🔍 GitFileWatcher: Lazy Cache
Singleton that keeps branch name, HEAD SHA, remote URL, and default branch in memory. Recomputes only when underlying files change using Node's fs.watchFile (inotify/kqueue-backed).
💡 Dirty-Bit Invalidation
Dirty flag cleared BEFORE async compute. If file-change fires during async read, invalidate() re-sets dirty. New value written back only if dirty still false - ensuring correctness under race conditions.
🛡️ Security: Ref Validation
isSafeRefName
Strict allowlist [a-zA-Z0-9/._+@-]. Blocks path traversal (..), argument injection (leading -), shell metacharacters.
isValidGitSha
Only full-length SHAs: 40 hex (SHA-1) or 64 hex (SHA-256). No abbreviated SHAs accepted.
💡 Graceful Degradation
Validation failure returns null, propagating to safe fallbacks (e.g., getCachedBranch returns 'HEAD'). Silent degradation rather than crash or passing tainted data.
🔎 Operation Tracking & PR Auto-Linking
detectGitOperation(command, output) uses shell-agnostic regexes working identically for Bash and PowerShell. Covers commits, pushes, merges, rebases, cherry-picks, and PR lifecycle via gh, glab, and curl.
💡 Dynamic Import Pattern
PR auto-linking uses double dynamic import() to break circular dependency between sessionStorage, bootstrap/state, and gitOperationTracking modules.