From 2e12cd9ef3a9a005f2055ac1717f3351d40f236b Mon Sep 17 00:00:00 2001 From: Colby McHenry Date: Tue, 17 Nov 2026 15:47:52 -0600 Subject: [PATCH] fix(sync): change detection no longer takes git's index lock Change detection runs `git status --porcelain --no-renames -z -uall` with git's optional locks on. In that mode git writes the stat info it refreshed back to the index, so it takes .git/index.lock right after the refresh and holds it through the diff and the whole untracked scan. Every sync runs it twice (the watcher's and codegraph sync), codegraph status and the MCP freshness checks once each, and the watcher wakes exactly when a commit, a checkout or a pre-commit hook churns files. A git write that started inside that window failed at once with "index.lock: File exists". The status call, and the commit-range diff beside it, now run with GIT_OPTIONAL_LOCKS=0. That skips only the write-back: the output is the same, and the user's next git command refreshes the index itself. It is an environment variable rather than --no-optional-locks, which a git older than 2.15 rejects. The other git calls change detection makes (ls-files, rev-parse, cat-file, config) never write the index. Validation: - New git-status-optional-locks tests (2): getGitChangedFiles, a sync and a status check leave .git/index byte-identical. Both fail on main, where the index is rewritten, and pass with the fix. Each first checks that a plain git status in the same state does rewrite it. - A repo with 10,000 tracked and 10,000 untracked files, polling for .git/index.lock while the CLI runs: main's build took it in 12 of 12 syncs and 8 of 8 status runs, the fix in 0 of 12 and 0 of 8. - Published 1.6.3 on the same repo, with a git write loop running beside each sync: 3 of 176 writes failed with "index.lock: File exists", 0 of 175 with no sync running, and 0 of 178 with GIT_OPTIONAL_LOCKS=0 set. - Neighbouring suites (git-changed-untracked-dir, git-index-currency, git-status-subdir-project, git-ignored-dirs-scope, cli-sync): 37 passed. Fixes #3295 Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 1 + __tests__/git-status-optional-locks.test.ts | 105 ++++++++++++++++++++ src/extraction/index.ts | 23 ++++- 3 files changed, 128 insertions(+), 1 deletion(-) create mode 100644 __tests__/git-status-optional-locks.test.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index f48bee415..150975120 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,7 @@ and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - In Python, `import time` no longer links the importing file to a project function that happens to be named `time`, so such a function stops listing every file that imports the standard library module among its callers and in its impact. The same goes for `json`, `copy`, `random`, `logging` and any other module, and for a fallback variable like `brotli = None` beside a guarded `import brotli`. Thanks @inth3shadows for the report. (#3239) - In Rust, a call through a module that a glob `use` brings in, like `gzip::write()` in a test module with `use super::*`, or that a `use` inside the function names, now links to that module's function again. Thanks @Egrn for the report and @mohitdixit02. (#3253) +- CodeGraph no longer takes git's index lock while it checks your repository for changes, so a `git add` in a pre-commit hook, a commit or a checkout that runs while CodeGraph syncs no longer fails with "index.lock: File exists". Thanks @iamclaudia-ai for the report. (#3295) ## [1.6.3] - 2026-11-17 diff --git a/__tests__/git-status-optional-locks.test.ts b/__tests__/git-status-optional-locks.test.ts new file mode 100644 index 000000000..bcc4349be --- /dev/null +++ b/__tests__/git-status-optional-locks.test.ts @@ -0,0 +1,105 @@ +/** + * Change detection reads git without taking `.git/index.lock` (#3295). + * + * With git's optional locks on, `git status` writes the stat info it refreshed + * back to the index, and holds `index.lock` from that refresh through the whole + * untracked scan. A `git add` in a pre-commit hook or a `git checkout` that + * started inside that window failed at once with "index.lock: File exists", + * and the watcher syncs exactly when such a command churns files. + * + * The observable difference is the index file: a status run that took the lock + * rewrites `.git/index` with the refreshed stat info, one that didn't leaves it + * byte for byte. Each case first checks that a plain `git status` in the same + * state does rewrite it, so the assertion can't pass vacuously. + */ +import { afterEach, beforeEach, describe, expect, it } from 'vitest'; +import { execFileSync } from 'child_process'; +import * as fs from 'fs'; +import * as os from 'os'; +import * as path from 'path'; +import CodeGraph from '../src/index'; +import { getGitChangedFiles } from '../src/extraction/index'; + +function git(cwd: string, args: string[], env: NodeJS.ProcessEnv = process.env): string { + return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], env }); +} + +/** Give a tracked file new stat info with the same content, so status has an entry to refresh. */ +function staleStatInfo(file: string, offsetSec: number): void { + const when = new Date(Date.now() - offsetSec * 1000); + fs.utimesSync(file, when, when); +} + +describe('change detection never takes the git index lock (#3295)', () => { + let root: string; + let savedOptionalLocks: string | undefined; + + beforeEach(() => { + // The env a user's shell might set would hide the bug: test git's default. + savedOptionalLocks = process.env.GIT_OPTIONAL_LOCKS; + delete process.env.GIT_OPTIONAL_LOCKS; + root = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-git-optional-locks-')); + fs.mkdirSync(path.join(root, 'src')); + fs.writeFileSync(path.join(root, 'src', 'a.ts'), 'export function a(): number { return b(); }\nexport function b(): number { return 1; }\n'); + fs.writeFileSync(path.join(root, 'src', 'c.ts'), "import { a } from './a';\nexport const c = (): number => a();\n"); + git(root, ['init', '-q']); + git(root, ['add', '-A']); + git(root, ['-c', 'user.email=t@t', '-c', 'user.name=t', 'commit', '-qm', 'init']); + // Untracked files too: the scan git holds the lock through. + fs.mkdirSync(path.join(root, 'notes')); + for (let i = 0; i < 20; i++) fs.writeFileSync(path.join(root, 'notes', `n${i}.txt`), `${i}\n`); + }); + + afterEach(() => { + if (savedOptionalLocks === undefined) delete process.env.GIT_OPTIONAL_LOCKS; + else process.env.GIT_OPTIONAL_LOCKS = savedOptionalLocks; + fs.rmSync(root, { recursive: true, force: true }); + }); + + const indexBytes = (): Buffer => fs.readFileSync(path.join(root, '.git', 'index')); + + /** A plain `git status` in this state rewrites the index: the setup can see a write. */ + function expectPlainStatusWritesIndex(file: string, offsetSec: number): void { + staleStatInfo(file, offsetSec); + const before = indexBytes(); + git(root, ['status', '--porcelain']); + expect(indexBytes().equals(before)).toBe(false); + } + + it('getGitChangedFiles leaves .git/index untouched', () => { + const file = path.join(root, 'src', 'a.ts'); + expectPlainStatusWritesIndex(file, 3600); + + staleStatInfo(file, 7200); + const before = indexBytes(); + const changes = getGitChangedFiles(root); + expect(changes).not.toBeNull(); + // Same answer as ever: nothing tracked changed, only untracked non-source files. + expect(changes!.modified).toEqual([]); + expect(indexBytes().equals(before)).toBe(true); + expect(fs.existsSync(path.join(root, '.git', 'index.lock'))).toBe(false); + }); + + it('a sync and a status check leave .git/index untouched', async () => { + const cg = await CodeGraph.init(root); + try { + await cg.indexAll(); + const file = path.join(root, 'src', 'c.ts'); + expectPlainStatusWritesIndex(file, 3600); + + // `codegraph sync` and the watcher's syncs. + staleStatInfo(file, 7200); + let before = indexBytes(); + await cg.sync(); + expect(indexBytes().equals(before)).toBe(true); + + // `codegraph status` and the MCP freshness checks. + staleStatInfo(file, 10800); + before = indexBytes(); + cg.getChangedFiles(); + expect(indexBytes().equals(before)).toBe(true); + } finally { + cg.close(); + } + }); +}); diff --git a/src/extraction/index.ts b/src/extraction/index.ts index e382dc674..d5b7023fd 100644 --- a/src/extraction/index.ts +++ b/src/extraction/index.ts @@ -1685,6 +1685,25 @@ export function getGitHeadSha(rootDir: string): string | null { } } +/** + * The environment for the git commands change detection runs, which only read. + * + * With git's "optional locks" on, `git status` writes the stat info it + * refreshed back to the index, and to do that it takes `.git/index.lock` right + * after the refresh and holds it through the diff and the whole untracked scan. + * Change detection runs on every sync — the watcher's, `codegraph sync` and + * `codegraph status`, and the MCP tools' freshness checks — and the watcher + * wakes exactly when a commit, a checkout or a hook churns files, so the user's + * `git add` or `git checkout` started inside that window failed at once with + * "index.lock: File exists" (#3295). `GIT_OPTIONAL_LOCKS=0` skips only that + * write-back: the output is the same, and the user's next git command refreshes + * the index itself. An environment variable rather than `--no-optional-locks`, + * which a git older than 2.15 would reject. + */ +function readOnlyGitEnv(): NodeJS.ProcessEnv { + return { ...process.env, GIT_OPTIONAL_LOCKS: '0' }; +} + /** * NUL-delimited status/path pairs for every path committed * between `sinceCommit` and HEAD. Empty when the stamp IS HEAD, which is the @@ -1695,6 +1714,7 @@ function gitCommittedChangesSince(repoDir: string, sinceCommit: string): string[ // Let command failures reach getGitChangedFiles: [] would falsely mean clean. const out = execFileSync('git', ['diff', '--relative', '--name-status', '--no-renames', '-z', sinceCommit, 'HEAD', '--', '.'], { cwd: repoDir, encoding: 'utf-8', timeout: 10000, maxBuffer: 50 * 1024 * 1024, stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true, + env: readOnlyGitEnv(), }); return out.split('\0'); } @@ -1751,7 +1771,8 @@ function collectGitStatus(repoDir: string, prefix: string, out: GitChanges, isSo repoPrefix ? ['status', '--porcelain', '--no-renames', '-z', '-uall', '--', '.'] : ['status', '--porcelain', '--no-renames', '-z', '-uall'], - { cwd: repoDir, encoding: 'utf-8', timeout: 10000, maxBuffer: 50 * 1024 * 1024, stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true } + // Read-only: never take `.git/index.lock` from under the user's git (#3295). + { cwd: repoDir, encoding: 'utf-8', timeout: 10000, maxBuffer: 50 * 1024 * 1024, stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true, env: readOnlyGitEnv() } ); // This repo's own ignore rules — built-in defaults (#407) plus its .gitignore.