git-architecture

Git Architecture

ShipIt uses git for version control at two levels: per-session workspace repos managed by GitManager, and a shared per-remote bare cache (from which each session gets its own independent local clone) managed by RepoGit. Both use the simple-git library.

Each session gets its own independent full clone — git clone --local from the bare cache, which hardlinks objects so the clone is fast and disk-cheap. Each session owns a complete .git/ and shares nothing mutable with its siblings.

Two Git Layers

GitManager (per-session)

src/server/shared/git.ts — operates on a single session's workspace directory.

Each session gets its own GitManager instance via the createGitManager(dir) factory. Used for:

• init() — initialize repo with initial commit (so rollback always has a base)
• autoCommit(summary) — stage all + commit if anything changed
• log(maxCount) — commit history
• rollback(hash) — hard reset to a previous commit
• push(remote, branch) — push with upstream tracking
• pull(remote, branch) — pull from remote
• addRemote(name, url) / getRemotes() — remote management
• checkoutNewBranch(name) / renameBranch(old, new) — branch operations
• diffSummary() — per-file diff stats for the working tree
• diffStatVsBranch(baseBranch) — insertions/deletions vs a base branch (for PR stats)
• getFileAtCommit(hash, filePath) — file content at a specific commit
• diffNameStatus(from, to) — changed files with status between commits
• merge(branchName) — merge with conflict detection

RepoGit (bare cache)

src/server/orchestrator/repo-git.ts — operates on a per-remote bare cache directory (one bare clone per remote URL, at {stateDir}/repo-cache/{hash}).

Used by the orchestrator to seed and refresh the cache, then cut per-session clones from it:

• cloneBare(url) — bare-clone the remote into the cache dir (git clone --bare)
• fetchCache(ttlMs?) — fetch the remote into the bare cache (advances local refs/heads/*); TTL-throttled
• cloneFromCache(sessionDir, remoteUrl?) — create a session's clone: git clone --local from the cache (hardlinked objects), set gc.auto=0, then reset origin to the real remote URL
• getDefaultBranch(remote) — detect main/master (tries local refs first to avoid network calls)
• deleteBranch(name) — delete local branch
• isEmpty() / createInitialCommit() — empty-repo handling
• readHead() / lastFetchAgeMs() — cache freshness checks used by the proactive pre-fetcher