こんにちは、エンジニアのオオバです。

お悩みさん
お悩みさん
  • Pullすると「index.lock: File exists」で止まる
  • ロックを消せば直るのに何度も残る
  • Pythonのタイムアウトが原因なのか
  • オオバ
    オオバ
    本記事ではこれらの悩みを解決します。

    管理画面から 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 の timeout で止めた場合。0 バイトの index.lock が残り、次の git add が「File exists」で止まりました。

    subprocess.run(timeout=1) で止めると、0バイトの index.lock が残り次の git add が止まる(検証用の空のリポジトリで再現。パスとユーザー名は伏せ字)

    subprocess.run の timeout で git add を止めると index.lock が残る

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

    SIGTERM で止めると git が index.lock を消してから終わる(同じ検証用のリポジトリ)

    SIGTERM をプロセスグループへ送ると index.lock は残らない

    解決: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  
    

    時間の上限も二つに分けました。

    残ったロックの片付け

    ロックが残ったときは、次の条件を全部満たすときだけ消します。

    git が動いているかは、pgrep -x git で pid を集めて、各プロセスの cwd を lsof -a -p PID -d cwd -Fn で見ています。ワークツリーの中で動いている git だけを数えるのがポイントです。

    以前は全体の pgrep で見ていたので、別リポジトリの git が動いているだけで消せませんでした。

    作ったばかりのロックは、5 秒だけ消えるのを待ちます。ほかのツールの status が一瞬ロックを取ることがあるので、その一瞬で失敗させないためです。

    Claude Code には .git の中を rm させないようにしていて、削除はプロジェクトの専用スクリプト経由にしています。

    確認したこと

    補足・注意点

    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 が動いていないと確かめてから行う。同じところで止まった方の参考になれば。

    オススメ記事