Git Integration: Zero-Subprocess, Filesystem-First

Most tools that need the current git branch just run git rev-parse --abbrev-ref HEAD. Claude Code deliberately does not. Spawning a subprocess has real costs: process startup latency, blocking I/O, and permission implications. The core principle is to read git's own filesystem state directly — the same plain-text files git itself writes.

There are five source files that make up this system:

Git's config format is INI-like but has specific rules Claude Code implements faithfully. The parser in gitConfigParser.ts is verified against git's own config.c source.

The three-level lookup

Every call to parseGitConfigValue resolves a three-part address: section, subsection, and key. For example, fetching the remote URL means section = "remote", subsection = "origin", key = "url".

// Public API — reads .git/config on disk
export async function parseGitConfigValue(
  gitDir: string,
  section: string,       // e.g. "remote"    — case-insensitive
  subsection: string | null, // e.g. "origin"    — case-sensitive
  key: string,            // e.g. "url"       — case-insensitive
): Promise<string | null>

// In-memory variant — exported for testing
export function parseConfigString(
  config: string,
  section: string,
  subsection: string | null,
  key: string,
): string | null

Value parsing: quotes, escapes, and inline comments

Values in git config can be unquoted, partially quoted, or fully quoted. They support backslash escape sequences inside quotes and inline comments (# or ;) outside quotes. The parser processes values character-by-character with an inQuote boolean toggle:

// Inside quotes: recognized escape sequences
"hello\nworld"  →  "hello\nworld"   // \n, \t, \b, \\, \" recognized
"foo\xbar"      →  "foobar"         // unknown escapes: backslash silently dropped

// Inline comments outside quotes end the value
url = git@github.com:foo/bar.git # this is a comment
→ url = "git@github.com:foo/bar.git"

// Simple section — no subsection
[core]              → section="core", subsection=null

// Section with subsection
[remote "origin"]   → section="remote", subsection="origin"
[branch "main"]     → section="branch",  subsection="main"

// Case rules
[Remote "ORIGIN"]   → section matches "remote" (lowercased)
                      subsection is "ORIGIN" (case-sensitive, won't match "origin")

resolveGitDir: handling worktrees and submodules

A critical step before reading anything is resolving the actual .git directory. In a regular repo, .git is a directory. In a git worktree or submodule, .git is a plain text file containing a gitdir: <path> pointer. resolveGitDir handles both cases transparently:

async function resolveGitDir(startPath?: string): Promise<string | null> {
  const root = findGitRoot(cwd)           // walk up looking for .git
  const gitPath = join(root, '.git')
  const st = await stat(gitPath)

  if (st.isFile()) {
    // Worktree/submodule: .git is a pointer file
    const content = (await readFile(gitPath, 'utf-8')).trim()
    if (content.startsWith('gitdir:')) {
      const rawDir = content.slice('gitdir:'.length).trim()
      return resolve(root, rawDir)   // may be relative path
    }
  }
  return gitPath  // regular repo: .git is a directory
}

Results are memoized per cwd path in a Map<string, string | null>. Because .git pointers don't change during a session, this is safe and prevents redundant disk reads on every git query.

readGitHead: parsing HEAD

The .git/HEAD file has exactly two formats. The parser handles both and validates all output before returning:

resolveRef: loose files and packed-refs

To convert a branch name into a commit SHA, resolveRef checks two locations — in order:

export async function getCommonDir(gitDir: string): Promise<string | null> {
  const content = (await readFile(join(gitDir, 'commondir'), 'utf-8')).trim()
  return resolve(gitDir, content)  // may be relative
}

GitFileWatcher is the singleton that keeps branch name, HEAD SHA, remote URL, and default branch in memory — recomputing only when the underlying files actually change. It uses Node's fs.watchFile (inotify/kqueue-backed, zero-subprocess) rather than polling on every query.

What files are watched

The cache: dirty-bit invalidation

Each cached value is a CacheEntry<T> with a dirty flag. The get(key, compute) method is the entire public interface:

async get<T>(key: string, compute: () => Promise<T>): Promise<T> {
  await this.ensureStarted()
  const existing = this.cache.get(key)
  if (existing && !existing.dirty) return existing.value as T

  // Clear dirty BEFORE async compute — if the file changes again
  // during compute, invalidate() re-sets dirty so we re-read next call
  if (existing) existing.dirty = false

  const value = await compute()

  // Only write back if no new invalidation arrived during compute
  const entry = this.cache.get(key)
  if (entry && !entry.dirty) entry.value = value
  if (!entry) this.cache.set(key, { value, dirty: false, compute })

  return value
}

Public API

// All four return Promises backed by the watcher cache
getCachedBranch()        // → "main" | "HEAD" (detached)
getCachedHead()          // → "a1b2c3..." | "" (no commits yet)
getCachedRemoteUrl()     // → "git@github.com:org/repo.git" | null
getCachedDefaultBranch() // → "main" | "master" (from remote symref)

Because .git/HEAD and loose ref files are plain text that can be written without going through git's own validation, an attacker who can tamper with those files could inject malicious content into any downstream context that interpolates branch names into shell commands. Claude Code defends against this with two validators applied to every string read from .git/.

isSafeRefName

export function isSafeRefName(name: string): boolean {
  if (!name || name.startsWith('-') || name.startsWith('/')) return false
  if (name.includes('..')) return false      // path traversal
  if (name.split('/').some(c => c === '.' || c === '')) return false
  return /^[a-zA-Z0-9/._+@-]+$/.test(name) // strict allowlist
}

The allowlist covers all legitimate git branch names (including feature/foo, release-1.2.3+build, dependabot/npm/@types/node-18) while blocking:

• Path traversal — .., leading /, empty path components (foo//bar), single dot components (foo/./bar)
• Argument injection — leading - (would become a CLI flag)
• Shell metacharacters — newlines, backticks, $, ;, |, &, (, ), <, >, spaces, tabs, quotes, backslash
• git's own forbidden sequences — @{ is blocked because { is not in the allowlist

isValidGitSha

export function isValidGitSha(s: string): boolean {
  return /^[0-9a-f]{40}$/.test(s) || /^[0-9a-f]{64}$/.test(s)
}

Only full-length SHAs are accepted — 40 hex chars for SHA-1, 64 for SHA-256. Git never writes abbreviated SHAs to HEAD or ref files. An attacker controlling a detached HEAD file could embed shell metacharacters; the allowlist of hex digits prevents any injection.

gitOperationTracking.ts solves a different problem: after Claude Code runs a bash command, how does it know if a git commit happened, a push succeeded, or a PR was created? It doesn't re-query git state — it parses the command text and output.

Shell-agnostic regex matching

The regexes operate on raw command text and work identically for Bash and PowerShell, because both invoke git/gh/glab/curl as external binaries with the same argv syntax. The key helper handles git's global options:

// Builds a regex tolerant of git global flags between "git" and the subcmd
// e.g. "git -c commit.gpgsign=false commit -m 'msg'" still matches "commit"
function gitCmdRe(subcmd: string, suffix = ''): RegExp {
  return new RegExp(
    `\\bgit(?:\\s+-[cC]\\s+\\S+|\\s+--\\S+=\\S+)*\\s+${subcmd}\\b${suffix}`
  )
}

const GIT_COMMIT_RE   = gitCmdRe('commit')
const GIT_PUSH_RE     = gitCmdRe('push')
const GIT_MERGE_RE    = gitCmdRe('merge', '(?!-)')  // excludes "merge-base" etc.
const GIT_REBASE_RE   = gitCmdRe('rebase')
const GIT_CHERRY_PICK = gitCmdRe('cherry-pick')

detectGitOperation: what it returns

The main export is detectGitOperation(command, output) which returns a sparse object with only the fields that actually fired:

type DetectedOp = {
  commit?: { sha: string; kind: 'committed' | 'amended' | 'cherry-picked' }
  push?:   { branch: string }
  branch?: { ref: string; action: 'merged' | 'rebased' }
  pr?:     { number: number; url?: string; action: PrAction }
}

Commit SHA is extracted from git's output line: [branch abc1234] message (or [branch (root-commit) abc1234]). Push branch is parsed from the ref update line git writes to stderr: abc..def branch -> branch. Merge and rebase are confirmed by checking the output for Fast-forward / Merge made by or Successfully rebased.

// gh pr create  → PrAction 'created'
// gh pr edit    → PrAction 'edited'
// gh pr merge   → PrAction 'merged'
// gh pr comment → PrAction 'commented'
// gh pr close   → PrAction 'closed'
// gh pr ready   → PrAction 'ready'

// POST indicator (any one of):
/-X\s*POST\b/i | /--request\s*=?\s*POST\b/i | /\s-d\s/

// PR endpoint — matches /pulls, /pull-requests, /merge-requests
// but NOT /pulls/123/comments (sub-resource exclusion)
/https?:\/\/[^\s'"]*\/(pulls|pull-requests|merge[-_]requests)(?!\/\d)/i

When gh pr create succeeds, Claude Code does something extra: it extracts the GitHub PR URL from stdout and links the current session to that PR. This powers the PR-context feature in the session history UI.

// Inside trackGitOperations, when prHit.action === 'created':
if (stdout) {
  const prInfo = findPrInStdout(stdout)
  if (prInfo) {
    // Dynamic import avoids circular dependency
    void import('../../utils/sessionStorage.js').then(({ linkSessionToPR }) => {
      void import('../../bootstrap/state.js').then(({ getSessionId }) => {
        const sessionId = getSessionId()
        if (sessionId) {
          void linkSessionToPR(sessionId, prInfo.prNumber, prInfo.prUrl, prInfo.prRepository)
        }
      })
    })
  }
}

The PR URL regex (/https:\/\/github\.com\/([^/]+\/[^/]+)\/pull\/(\d+)/) extracts both the repository (owner/repo) and the PR number from the full URL. These three fields — number, URL, repository — are stored in session storage.

ghAuthStatus.ts checks whether the gh CLI is installed and authenticated. It does this with a careful two-step that avoids making any network request:

export async function getGhAuthStatus(): Promise<GhAuthStatus> {
  const ghPath = await which('gh')   // Bun.which — no subprocess
  if (!ghPath) return 'not_installed'

  const { exitCode } = await execa('gh', ['auth', 'token'], {
    stdout: 'ignore',  // token NEVER enters this process
    stderr: 'ignore',
    timeout: 5000,
    reject: false,
  })
  return exitCode === 0 ? 'authenticated' : 'not_authenticated'
}

The choice of gh auth token over gh auth status is deliberate. auth status makes a live request to api.github.com to verify the token. auth token only reads the local keyring or config file and exits zero if a token exists. This keeps auth checking offline and fast.

The gitignore.ts module handles one specific task: ensuring Claude Code's own files (e.g. conversation logs, local config) don't accidentally get committed to user repos. It writes to the global gitignore at ~/.config/git/ignore rather than any repo's local .gitignore — so the same exclusion applies to all repos on the machine without polluting them.

export async function addFileGlobRuleToGitignore(
  filename: string,
  cwd: string = getCwd(),
): Promise<void> {
  if (!(await dirIsInGitRepo(cwd))) return   // no-op outside git repos

  const gitignoreEntry = `**/${filename}`
  const testPath = filename.endsWith('/')
    ? `${filename}sample-file.txt`      // directory pattern check
    : filename

  // Check if already ignored by any .gitignore (local, nested, or global)
  if (await isPathGitignored(testPath, cwd)) return

  // Write to global gitignore, creating it if necessary
  const globalPath = getGlobalGitignorePath()  // ~/.config/git/ignore
  await mkdir(dirname(globalPath), { recursive: true })
  // Append only — checks for existing entry to avoid duplication
}