こんにちは、エンジニアのオオバです。
管理画面から Pull を押したら、git が作った「index.lock」が残ったまま止まりました。消せば先へ進めますが、同じことが別の端末でも起きます。
原因を追いかけたところ、管理画面の git 呼び出しが時間切れのときに git を殺していたことが分かりました。
時間切れで git を SIGKILL すると、git はロックを消せない。時間切れは SIGTERM から始め、残ったロックは git が動いていないと確かめてから消すようにした
先に結論を書きます。Python の subprocess.run(..., timeout=30) は、時間切れのとき子プロセスに SIGKILL を送ります。SIGKILL を受けた git は後片付けができず、ロックファイルが残ります。
→11万文字で徹底解説した「DOTweenの教科書」Unityアニメーションの超効率化ツールはこちら
「index.lock: File exists」で Pull が止まった
2026-10-23 の朝、ゲームのリポジトリのワークツリーの一つで Pull を押すと、次のエラーで止まりました(ワークツリー名は伏せています)。
error: Unable to create '.../.git/worktrees/<worktree>/index.lock': File exists.
Another git process seems to be running in this repository ... remove the file manually to continue.
error: could not detach HEAD
同じことが別の端末・別のワークツリーでも起きました。僕は手でロックを消しています。
「could not detach HEAD」は、rebase が HEAD を切り離そうとしてロックを取れなかったときの文言です。つまり Pull の途中、rebase の段階で止まっていました。
原因を調べた:生きている git はいなかった
ロックは前日 15:37:39 に作られていて、中身は 0 バイトでした。ps で見ても git のプロセスは一つもありません。
その時刻に、このワークツリーで動いていた AI セッションも記録上ありませんでした。pmset のログにもスリープや復帰はありません。
0 バイトのまま残るのは、git がロックファイルを作った直後に止められた形に近いです。ここで効いてくるのが、git のシグナルの扱いです。
git は SIGINT や SIGTERM を受けると、シグナルハンドラでロックファイルを消してから終わります。一方、SIGKILL は捕まえられないシグナルなので、後片付けの処理は一切走りません。
どのツールが git を止めたのかは、記録が無いので特定できませんでした。Fork などの外部ツールが候補になりますが、確かめられてはいません。
原因の候補:Python の subprocess タイムアウト
リポジトリの中を見ると、管理画面(Python)の git 呼び出しは subprocess.run(["git", ...], timeout=30) の形でした。
Python の subprocess.run は時間切れになると、子プロセスに kill() を送ります。kill() は SIGKILL です。時間切れで止めたかった git が、ロックを消せない殺され方をしていたわけです。
しかも Pull は「stash push --include-untracked → rebase → stash apply」という流れで、この3つも既定の 30 秒上限で動いていました。Unity プロジェクトは未追跡ファイルや LFS の素材が多いので、30 秒を超えても不思議ではありません。
この欠陥が 10/23 の犯人だと断定はできません。ただ、ロックを残し得る止められ方のひとつが、ここにあるのは確かです。
「表示用の status が重いのでは」とも疑いました。ところが普段の git status は 0.06 秒で終わります(19,194 ファイル)。status が長く止まっている可能性は低いと判断しました。
再現:遅い clean フィルタで git を止める
本物の git で再現できるか試しました。clean フィルタにわざと 5 秒待つ処理を入れて、git add がロックを持ったまま止まり続けるようにします。
git config filter.slow.clean "sleep 5; cat"
echo "*.txt filter=slow" > .gitattributes
echo hello > a.txt
git add a.txt
結果は次のとおりです。
subprocess.run(["git", "add", "a.txt"], timeout=1)は TimeoutExpired の後も index.lock が残りました。今回の置き去りと同じ形です。Popenとcommunicate(timeout=...)で、時間切れのときに SIGTERM をプロセスグループへ送ると、index.lock は消えていました。
実際に流した様子です。まずは subprocess.run の timeout で止めた場合。0 バイトの index.lock が残り、次の git add が「File exists」で止まりました。

同じ条件で、SIGTERM をプロセスグループへ送って止めた場合です。git が自分でロックを消してから終わりました。

解決:SIGTERM → 5秒待つ → SIGKILL の順にする
時間切れでいきなり SIGKILL しない形に変えました。start_new_session=True で git を別のプロセスグループに入れて、時間切れのときはグループごと SIGTERM を送ります。5 秒待っても終わらないときだけ SIGKILL です。グループごと送るので、git が起こした git-lfs や ssh もまとめて止まります。
要点だけを抜き出すと、次のような形になります。
import os
import signal
import subprocess
def run_git(args, cwd, timeout):
proc = subprocess.Popen(
["git", *args], cwd=cwd, start_new_session=True,
stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True,
)
try:
out, err = proc.communicate(timeout=timeout)
except subprocess.TimeoutExpired:
os.killpg(proc.pid, signal.SIGTERM) # 先に SIGTERM。git がロックを消せる
try:
proc.communicate(timeout=5)
except subprocess.TimeoutExpired:
os.killpg(proc.pid, signal.SIGKILL)
proc.communicate()
raise
return proc.returncode, out, err
時間の上限も二つに分けました。
- 書き込み系(stash -u / rebase / add / commit / restore / clean)は上限を 300 秒に延ばしました。
- 読み取り系は 30 秒のままです。
- 表示用の status は
git --no-optional-locks statusにしました。status はふだん index を書き戻すためにロックを取るので、このオプションでロック自体を取らないようにしています。
残ったロックの片付け
ロックが残ったときは、次の条件を全部満たすときだけ消します。
- 60 秒より古い
- このワークツリーで git が動いていない
git が動いているかは、pgrep -x git で pid を集めて、各プロセスの cwd を lsof -a -p PID -d cwd -Fn で見ています。ワークツリーの中で動いている git だけを数えるのがポイントです。
以前は全体の pgrep で見ていたので、別リポジトリの git が動いているだけで消せませんでした。
作ったばかりのロックは、5 秒だけ消えるのを待ちます。ほかのツールの status が一瞬ロックを取ることがあるので、その一瞬で失敗させないためです。
Claude Code には .git の中を rm させないようにしていて、削除はプロジェクトの専用スクリプト経由にしています。
確認したこと
- ワークツリーに2分前の index.lock を置いて Pull の API を叩くと、ロックが消えてから先へ進みました。
- 作ったばかりのロックでは、「別の git が動いています(index.lock ができて 5 秒)」と出て止まり、ロックは残りました。
- テストは新規 15 件です。本物の git で SIGTERM と SIGKILL の違いを確かめ、偽の git(trap TERM するシェルスクリプトを PATH の先頭に置く)で SIGTERM が先に来ること、SIGKILL に切り替わることも確かめました。
補足・注意点
subprocess.run(timeout=...) は「時間で止める」だけでなく「SIGKILL で殺す」と覚えておくと安全です。ロックや一時ファイルを持つ子プロセス(git、npm、Unity など)には、そのまま使わない方が良いです。
時間の上限を延ばすだけでは根本対策になりません。殺し方と上限の両方を直す必要があります。
通常の Pull と Push の最初でも、この片付けを呼ぶようにしました。前は「AIで解決」の側にしかなかった処理です。消せなかったときは、生のエラーを出さずに「別の git が動いています」と表示するようにしました。
Pull 周りの別の詰みは @mySimpleLink:admin-pull-push-deadlock-ai-fix でも書いています。
まとめ
index.lock が残る理由は、git が後片付けできない止められ方をしていたことです。Python の timeout は SIGKILL を送るので、子プロセスがロックを持っていると消えません。
時間切れは SIGTERM から始めて、ロックの片付けは git が動いていないと確かめてから行う。同じところで止まった方の参考になれば。

この記事が気に入ったらフォローしよう


