# Git Module Documentation ## Purpose This module provides Git repository operations for the web server runtime, including repository management, branch/worktree operations, status/diff queries, commit handling, and merge/rebase workflows. ## Entrypoints and structure - `packages/web/server/lib/git/`: Git module directory containing all Git-related functionality. - `index.js`: Public API entry point imported by `packages/web/server/index.js`. - `routes.js`: Express route registration for `/api/git/*` endpoints. - `service.js`: Core Git operations (repository, branch, worktree, commit, merge/rebase, status/diff, log). - `credentials.js`: Git credentials management. - `identity-storage.js`: Git identity (user.name, user.email) storage. ## Public API The following functions are exported and used by the web server: ### HTTP routes (discovery) - `GET /api/git/check?directory=...`: Single-directory repo probe. Returns `{ isGitRepository }`. - `GET /api/git/primary-root?directory=...`: Single-directory primary worktree root. Returns `{ root }`. - `GET /api/git/discover?directories=a&directories=b...`: Batch discovery for cold-start project lists. Accepts one or more `directories` query values (Express may surface a single value as a string). Returns a JSON array of `{ directory, isGitRepository, primaryRoot, error? }`. Per-directory failures are isolated: that entry gets `isGitRepository: false` / `primaryRoot: null` (or `isGitRepository: true` with `primaryRoot: null` when only root resolution fails) plus `error`, and the overall response stays HTTP 200. Empty/missing `directories` is HTTP 400. Legacy `/check` and `/primary-root` remain for other callers. ### Repository Operations - `isGitRepository(directory)`: Check if a directory is a Git repository. - `getGlobalIdentity()`: Get global Git user.name, user.email, and core.sshCommand. - `getCurrentIdentity(directory)`: Get local Git identity (fallback to global if not set locally). - `hasLocalIdentity(directory)`: Check if local Git identity is configured. - `setLocalIdentity(directory, profile)`: Set local Git identity (userName, userEmail, authType, sshKey/host). - `getRemoteUrl(directory, remoteName)`: Get URL for a specific remote. ### Status and Diff Operations - `getStatus(directory)`: Get comprehensive Git status including current branch, tracking, ahead/behind, file changes, diff stats, merge/rebase state. - `getDiff(directory, { path, staged, contextLines })`: Get diff output for files or entire working tree. - `getRangeDiff(directory, { base, head, path, contextLines })`: Get diff between two refs. - `getRangeFiles(directory, { base, head })`: Get list of changed files between two refs. - `getFileDiff(directory, { path, staged })`: Get original and modified file contents for a single file (handles images as data URLs). - `collectDiffs(directory, files)`: Collect diff output for multiple files. - `revertFile(directory, filePath, options)`: Revert a file. Default scope `all` discards staged and working-tree changes; scope `working` discards only unstaged/working-tree changes. - `stageFile(directory, filePath)`: Add one file path to the index. - `unstageFile(directory, filePath)`: Remove one file path from the index while preserving working-tree content. - `applyHunk(directory, filePath, options)`: Apply a single-hunk patch via `git apply`. `options.action` is `stage` (`git apply --cached`), `unstage` (`git apply --cached --reverse`), or `discard` (`git apply --reverse` in the working tree). The patch is written to a temp file; a `--check` runs first so a stale hunk fails with a clear "refresh and try again" error instead of a partial mutation. The patch target path must match the requested file. ### Branch Operations - `getBranches(directory)`: Get list of local and remote branches (filtered to active remote branches). - `createBranch(directory, branchName, options)`: Create and checkout a new branch. - `checkoutBranch(directory, branchName)`: Checkout an existing branch. - `deleteBranch(directory, branch, options)`: Delete a branch (supports force flag). - `renameBranch(directory, oldName, newName)`: Rename a branch and preserve upstream tracking. - `getRemotes(directory)`: Get list of configured remotes. ### Worktree Operations - `getWorktrees(directory)`: List all git worktrees for a repository. - `validateWorktreeCreate(directory, input)`: Validate worktree creation parameters (mode, branchName, startRef, upstream config). - `createWorktree(directory, input)`: Create a new worktree (supports 'new' and 'existing' modes, upstream setup). - `removeWorktree(directory, input)`: Remove a worktree (optionally delete local branch). - `isLinkedWorktree(directory)`: Check if directory is a linked worktree (not primary). ### Commit and Remote Operations - `commit(directory, message, options)`: Create a commit from the current index. `options.stageFiles` may be provided with `options.files` by older callers to stage only selected unstaged rows before committing, but the shared Git panel now stages/unstages explicitly before commit. - `pull(directory, options)`: Pull changes from remote. - `push(directory, options)`: Push changes to remote (auto-sets upstream if needed). - `fetch(directory, options)`: Fetch changes from remote. - `removeRemote(directory, options)`: Remove a configured remote (except `origin`). - `deleteRemoteBranch(directory, options)`: Delete a remote branch. ### Log Operations - `getLog(directory, options)`: Get commit history with stats (supports maxCount, from, to, file filters). - `getCommitFiles(directory, commitHash)`: Get file changes for a specific commit. - `getCommitFileDiff(directory, hash, filePath, isBinary)`: Get before/after content for a specific file in a commit. Returns `{ original, modified, isBinary }`. Runs `git show ^:` and `git show :` in parallel; returns empty strings on failure (added/deleted/root-commit edge cases). ### Merge and Rebase Operations - `rebase(directory, options)`: Start a rebase onto a target branch. - `abortRebase(directory)`: Abort an in-progress rebase. - `continueRebase(directory)`: Continue a rebase after conflict resolution. - `merge(directory, options)`: Merge a branch into current branch. - `abortMerge(directory)`: Abort an in-progress merge. - `continueMerge(directory)`: Continue a merge after conflict resolution. - `getConflictDetails(directory)`: Get detailed conflict information including operation type, unmerged files, and diff. ### Stash Operations - `listStashes(directory)`: List stash entries with ref, message, relative time, and hash. - `countStashFiles(directory, refs)`: Batch-count changed files for stash refs with bounded concurrency. - `stashPush(directory, options)`: Stash changes, always including untracked files, with optional message. - `stashApply(directory, options)`: Apply a stash by ref without removing it. - `stashPop(directory, options)`: Apply a stash by ref and drop it only after a successful apply. - `stashDrop(directory, options)`: Drop a stash by ref. ## Internal Helpers The following functions are internal helpers used by exported functions: - `buildSshCommand(sshKeyPath)`: Build SSH command string for git config. - `buildGitEnv()`: Build Git environment with SSH_AUTH_SOCK resolution. - `createGit(directory)`: Create simple-git instance with environment. - `normalizeDirectoryPath(value)`: Normalize directory paths (supports ~ expansion). - `cleanBranchName(branch)`: Remove refs/heads/ or refs/ prefixes. - `parseWorktreePorcelain(raw)`: Parse `git worktree list --porcelain` output. - `resolveWorktreeProjectContext(directory)`: Resolve project context (projectID, primaryWorktree, worktreeRoot). - `resolveCandidateDirectory(...)`: Generate unique worktree directory candidates. - `resolveBranchForExistingMode(...)`: Resolve branch for existing-mode worktree creation. - `applyUpstreamConfiguration(...)`: Set upstream tracking for new branches. - And various other internal helpers for Git command execution and parsing. ## Response Contracts ### Status Response - `current`: Current branch name. - `tracking`: Upstream branch (e.g., 'origin/main'). - `ahead`: Number of commits ahead of upstream. - `behind`: Number of commits behind upstream. - `upstreamComparison`: Optional comparison against `upstream/`, with `{ remote, branch, ahead, behind }`. - `files`: Array of file objects with `path`, `index`, `working_dir` status codes. - `isClean`: Boolean indicating if working tree is clean. - `oversized`: Boolean. `true` when the change set exceeds the server-owned `GIT_STATUS_DIFF_STATS_MAX_FILES` threshold; `diffStats` are omitted in that case (same omission shape as light mode). Clients must derive deferred / load-on-demand rendering from this flag rather than from their own threshold, so the server can tune the limit without client changes. Light-mode polls do not set this flag. - `diffStats`: Object mapping file paths to `{ insertions, deletions }`. Omitted by light mode and by oversized change sets. - `mergeInProgress`: Object with `{ head, message }` if merge in progress. - `rebaseInProgress`: Object with `{ headName, onto }` if rebase in progress. ### Staged and unstaged change handling - `status.files` exposes both `index` and `working_dir` codes. Shared UI uses these as separate scopes: staged rows are derived from non-empty `index` statuses, while unstaged rows are derived from `working_dir` statuses and untracked files. - A file with both staged and unstaged changes can appear in both UI sections. Staged rows request diffs with `staged: true`; unstaged rows request normal working-tree diffs. - The shared Git panel exposes explicit staging actions. Unstaged rows use `stageFile`, staged rows use `unstageFile`, and commits operate on the current staged index. - `stageFiles` remains supported for callers that need to stage a selected unstaged subset as part of commit. In that mode the server temporarily unstages unrelated index entries, stages `stageFiles`, commits from the index, then restores temporarily unstaged entries. ### Worktree Create/Remove Response - `head`: HEAD commit SHA. - `name`: Worktree name. - `branch`: Local branch name. - `path`: Absolute path to worktree directory. - `directoryCreated`: Present when create returned after the target directory exists while background Git/bootstrap work continues. - `bootstrapStatus`: Background setup status, with `pending`, `ready`, or `failed`. - Fast-create background failures remove OpenCode sandbox metadata for directories that never became Git worktrees, and remove the pre-created directory only if it is still empty. User-created files are never recursively deleted by this cleanup. - `POST /api/git/worktrees` captures the queue service runtime key before Git creation and passes it as `{ runtimeKey }` in the second argument to queue activation. Lifecycle payloads contain only allowlisted operation fields. A queue activation failure after Git creates the worktree returns HTTP 503 with `code: "message_queue_activation_pending"`, the created worktree in `worktree`, and a `repair` request descriptor containing the create request `projectDirectory` and new worktree `directory`. - Worktree catalog enumeration failures return HTTP 503 with `{ code: "worktree_catalog_unavailable" }`, preserving the distinction between an unavailable catalog and an authoritative empty catalog. - Confirmed worktree additions and removals broadcast `openchamber:worktree-topology-changed` with `{ projectDirectory, directory, operation, occurredAt }`. Broadcast delivery failures leave Git mutation results unchanged. - `POST /api/git/worktrees/queue-activation` captures the queue service runtime key before reading the authoritative worktree catalog with `getWorktrees(projectDirectory)`, then acquires a lifecycle lock scoped by that key and normalized worktree path. The target must remain in that catalog after normalized path comparison. A persisted `deleting` lifecycle with a valid token rolls back through `rollbackWorktreeDeletion`; all other lifecycle states activate through `markWorktreeActive`. Lifecycle mutations receive `{ runtimeKey }` as their second argument, while `getWorktreeLifecycle(directory, { runtimeKey })` retains its read signature. Missing catalog targets and `scope_locked` or `not_found` lifecycle results return HTTP 409 with `code: "worktree_activation_stale"`. A concurrent delete or repair in the same runtime and worktree returns HTTP 409 with `code: "worktree_lifecycle_busy"`. Catalog and lifecycle failures return HTTP 503 with `code: "message_queue_activation_pending"` and a retryable `repair` descriptor. Success returns `{ directory, state: "active" }`. A disabled queue service returns HTTP 501 and invalid input returns HTTP 400. The descriptor is `{ method: "POST", path: "/api/git/worktrees/queue-activation", body: { projectDirectory, directory } }`. Runtime keys and lifecycle tokens remain internal to the server. Each repair request captures its current server runtime key. - `DELETE /api/git/worktrees` captures the queue service runtime key before queue-deletion preparation, uses that key with the normalized worktree path for its lifecycle lock, and passes it as `{ runtimeKey }` in the second argument to preparation, rollback, and commit. Lifecycle payloads contain only allowlisted operation fields. This serializes same-runtime same-worktree deletion and activation repair while allowing independent runtimes and worktrees to proceed. ### Log Response - `all`: Array of commit objects with hash, date, message, author info, stats. - `latest`: Latest commit object or null. - `total`: Total number of commits. ## Notes for Contributors ### Adding a New Git Operation 1. Add the function to `packages/web/server/lib/git/service.js`. 2. Export the function if it's part of the public API. 3. Use `createGit(directory)` to get a simple-git instance with the correct environment. 4. Use `runGitCommand(cwd, args)` for direct git command execution with better error handling. 5. Use `runGitCommandOrThrow(cwd, args, fallbackMessage)` for commands that must succeed. 6. Return consistent error messages; use `parseGitErrorText(error)` to extract meaningful git errors. 7. Update this file with the new function in the appropriate API section. ### SSH Key Handling - SSH keys are escaped and validated via `escapeSshKeyPath` to prevent command injection. - On Windows, paths are converted to MSYS format (`C:/path` → `/c/path`). - SSH_AUTH_SOCK is automatically resolved via `resolveSshAuthSock` (checks GPG agent, gpgconf). ### Worktree Naming - Worktree names are slugified via `slugWorktreeName`. - Random names use adjectives/nouns from `OPENCODE_ADJECTIVES` and `OPENCODE_NOUNS` lists. - Branches created for new worktrees use `openchamber/` pattern. ### Cross-Platform Considerations - Use `normalizeDirectoryPath` for all directory inputs to handle `~` and path separators. - Use `canonicalPath` for path comparisons to handle case-insensitive filesystems (Windows). - Windows Git commands use MSYS/MinGW paths; avoid direct Windows paths in git commands. ### Error Handling - All exported functions should throw errors with descriptive messages. - Use `console.error` for logging Git operation failures. - Return structured objects for operations that need partial success reporting (e.g., merge/rebase conflicts). ### Testing - Run `bun run type-check`, `bun run lint`, and `bun run build` before finalizing changes. - Consider edge cases: non-Git directories, missing remotes, conflict states, concurrent worktree operations.