Claude Code / Git 报 Unable to create .git/index.lock File exists：先查进程再删锁（含 2.1.314）

Git 或 Claude Code 里突然出现 fatal: Unable to create '.../.git/index.lock': File exists.。不要一上来就删锁文件。先分清两层：普通的 git 锁，以及 Claude Code 2.1.314 修好的后台 diff 刷新短暂占用 index lock。

我看到了：在临时仓库 /tmp/gitlockdemo 里放了一个空的 .git/index.lock，再跑 git status，完整报错和官方提示原文如下（后文有摘录）。本机 Claude Code 仍是 2.1.312，后台 diff 那条修复需要升到 2.1.314。

这句报错在说什么

Git 用 .git/index.lock 保证同一时间只有一个进程改索引。锁还在，新的 git 命令就会拒绝创建，并提示：可能有另一个 git（例如正在跑的 commit）还没结束；若进程已经崩溃，再手动删锁。

一般性说明可以并进 Claude Code 报错速查 的 FAQ；这篇专门写 Claude Code 相关的那一层，以及「先查进程再删锁」的安全步骤。

我们复现了什么

在空目录初始化仓库、做一次提交后，手动创建空锁文件：

touch .git/index.lock
git status

我看到了的输出（节选）：

fatal: Unable to create '/tmp/gitlockdemo/.git/index.lock': File exists.

Another git process seems to be running in this repository, e.g.
an editor opened by 'git commit'. Please make sure all processes
are terminated then try again. If it still fails, a git process
may have crashed in this repository earlier:
remove the file manually to continue.

确认没有正在写仓库的 git 进程后，才删掉锁文件；删完 git status 恢复正常。演示仓库只用于复现，没有动任何真实项目。

两层原因

1. 普通 git 锁（任何工具都可能遇到）

另一个 git commit / git merge / IDE 自带的 git 还在跑，或者上次崩溃留下了锁。处理顺序：

1. 看有没有 git 相关进程（例如 ps 里搜 git，或活动监视器 / 任务管理器）。

2. 等正常操作结束；不要并行再开一个会写索引的命令。

3. 确认没有写入进程后，再删除 .git/index.lock。

不要在不确定是否有 git 正在写的时候盲目 rm .git/index.lock，可能损坏索引。

2. Claude Code 后台 diff 刷新（2.1.314 已修）

官方 CHANGELOG 2.1.314 写明：后台 diff 刷新会短暂占用仓库的 index lock，同一时刻跑的 git 命令可能报 Unable to create '.git/index.lock': File exists。修复后不应再因这条路径反复卡住。

我推测：若你主要在 Claude Code 会话里并行跑 git，且版本 < 2.1.314，优先升级；升级后若仍出现，再按第 1 层当普通锁排查。

本机版本检查：

claude --version
# 2.1.312 (Claude Code)

推荐步骤

1. 读完整报错，确认路径就是当前仓库的 .git/index.lock。

2. 查是否有正在运行的 git / 编辑器 git 操作。

3. 没有写入进程 → 删除该锁文件 → 再试原来的命令。

4. 若锁在 Claude Code 使用中反复出现 → 升级到 ≥ 2.1.314。

5. 其他 Claude Code 报错对照 报错速查；和 effort 400 无关的见 Invalid effort level。

常见问题

可以直接 rm .git/index.lock 吗？

只有在确认没有 git 进程正在写这个仓库时才可以。Git 自己的提示也是先确认进程结束。我们演示里是先查进程、再删的。

和「working directory no longer exists」是一回事吗？

不是。工作目录被挪走或删掉是另一类问题；index.lock 是索引锁。权限 / 工作目录写入限制见 Claude Code /permissions 与工作目录（若该文已发布）。

通用「git index.lock file exists」搜到这篇？

通用 FAQ 建议并入报错总页；需要 Claude Code 后台 diff 说明时再进这篇专文。总页：Claude Code 报错速查。