Git 集成

大多数需要当前 git 分支的工具只需运行 git rev-parse --abbrev-ref HEAD。 Claude Code 故意不这样做。 生成子进程具有实际成本：进程启动延迟、阻塞 I/O 和权限影响。 核心原则是 直接读取git自己的文件系统状态 — git 本身写入的相同纯文本文件。

组成该系统的源文件有五个：

Git 的配置格式与 INI 类似，但具有 Claude Code 忠实实现的特定规则。 解析器在 gitConfigParser.ts 已根据 git 自己的进行验证 config.c source.

三级查找

每次致电 parseGitConfigValue 解析由三部分组成的地址： section, subsection， 和 key。 例如，获取远程 URL 意味着section = "remote"，小节 = "origin", 键 = "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

值解析：引号、转义符和内联注释

git config 中的值可以不加引号、部分加引号或完全加引号。 它们支持引号内的反斜杠转义序列和内联注释（# or ;) 外部引号。 解析器逐个字符地处理值 inQuote 布尔切换：

// 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：处理工作树和子模块

阅读任何内容之前的关键一步是解决实际问题 .git 目录。 在常规回购中， .git 是一个目录。 在 git 工作树或子模块中， .git 是纯文本 file 含有一个 gitdir: <path> pointer. resolveGitDir 透明地处理这两种情况：

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
}

结果是 按 cwd 路径记忆 在一个 Map<string, string | null>。 因为 .git 指针在会话期间不会改变，这是安全的，并且可以防止每个 git 查询上的冗余磁盘读取。

readGitHead：解析 HEAD

The .git/HEAD 文件恰好有两种格式。 解析器处理这两者并在返回之前验证所有输出：

solveRef：松散文件和打包引用

要将分支名称转换为提交 SHA， resolveRef 检查两个位置 - 按顺序：

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 是在内存中保存分支名称、HEAD SHA、远程 URL 和默认分支的单例 — 仅当底层文件实际更改时才重新计算。 它使用节点的 fs.watchFile （inotify/kqueue 支持，零子进程）而不是轮询每个查询。

观看哪些文件

缓存：脏位失效

每个缓存值是一个 CacheEntry<T> 与一个 dirty 旗帜。 这 get(key, compute) method 是整个公共接口：

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
}

公共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 松散的参考文件是纯文本 无需经过git自己的验证即可编写，可以篡改这些文件的攻击者可以将恶意内容注入到将分支名称插入 shell 命令的任何下游上下文中。 Claude Code 通过应用于读取的每个字符串的两个验证器来防御此问题 .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
}

允许名单涵盖所有合法的 git 分支名称（包括 feature/foo, release-1.2.3+build, dependabot/npm/@types/node-18）同时阻塞：

• 路径遍历 — .., 领先 /，空路径组件（foo//bar），单点分量（foo/./bar)
• 参数注入 — 领先 - （将成为 CLI 标志）
• 外壳元字符 — 换行符、反引号、 $, ;, |, &, (, ), <, >、空格、制表符、引号、反斜杠
• git 自己的禁止序列 — @{ 被阻止是因为 { 不在允许名单中

isValidGitSha

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

仅接受全长 SHA - SHA-1 为 40 个十六进制字符，SHA-256 为 64 个十六进制字符。 Git 从不将缩写 SHA 写入 HEAD 或参考文件。 控制分离的 HEAD 文件的攻击者可以嵌入 shell 元字符； 十六进制数字的白名单可以防止任何注入。

gitOperationTracking.ts 解决了一个不同的问题：在 Claude Code 运行 bash 命令后，它如何知道是否发生了 git 提交、推送成功或创建了 PR？ 它不会重新查询 git state — 它 解析命令文本和输出.

与 shell 无关的正则表达式匹配

正则表达式对原始命令文本进行操作，并且对于 Bash 和 PowerShell 的工作方式相同，因为两者都使用相同的 argv 语法将 git/gh/glab/curl 作为外部二进制文件调用。 关键助手处理 git 的全局选项：

// 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')

检测GitOperation：它返回什么

主要出口是 detectGitOperation(command, output) 它返回一个稀疏对象，仅包含实际触发的字段：

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 }
}

提交 SHA 是从 git 的输出行中提取的： [branch abc1234] message (or [branch (root-commit) abc1234]）。 推送分支是从 git 写入 stderr 的引用更新行解析的： abc..def branch -> branch。 通过检查输出来确认合并和变基 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 成功后，Claude Code 会执行一些额外操作：它从 stdout 中提取 GitHub PR URL，并将当前会话链接到该 PR。 这为会话历史记录 UI 中的 PR 上下文功能提供了支持。

// 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)
        }
      })
    })
  }
}

PR URL 正则表达式 (/https:\/\/github\.com\/([^/]+\/[^/]+)\/pull\/(\d+)/）提取存储库（owner/repo) 以及完整 URL 中的 PR 号。 这三个字段（编号、URL、存储库）存储在会话存储中。

ghAuthStatus.ts 检查是否 gh CLI 已安装并经过身份验证。 它通过仔细的两步来完成此操作，避免发出任何网络请求：

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'
}

的选择 gh auth token over gh auth status 是故意的。 auth status 发出实时请求 api.github.com 验证令牌。 auth token 仅读取本地密钥环或配置文件，如果令牌存在则退出为零。 这可以保持离线且快速的身份验证检查。

The gitignore.ts 模块处理一项特定任务：确保 Claude Code 自己的文件（例如对话日志、本地配置）不会意外提交到用户存储库。 它写到 全局 gitignore at ~/.config/git/ignore 而不是任何存储库的本地 .gitignore - 因此相同的排除适用于机器上的所有存储库，而不会污染它们。

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
}