何が起きたか
リポジトリをクローンしようとしたとき、またはブランチを切り替えようとしたとき、Git が以下のエラーで中断しました：
error: unable to create file some/very/deeply/nested/path/component/filename.tsx: Filename too long
fatal: unable to checkout working tree
ワーキングツリーが不完全な状態になっています。ファイルはインデックスには存在しているのに、ディスク上には存在しません。git status を実行すると、実際には存在しない大量の削除が表示されます。
これは Windows 固有の問題です。Linux と macOS ではパス長を最大約 4096 文字まで許可しています。一方 Windows はデフォルトでファイルパスを 260 文字に制限しており、これは DOS から引き継がれた MAX_PATH と呼ばれる制限です。リポジトリに深くネストされたフォルダ（モノレポ、自動生成コード、Java Maven のレイアウト、深くネストされた React コンポーネントツリーなど）が含まれていると、パスがこの制限を超えて Git がファイルを書き込めなくなります。
パス長が原因かどうかの確認
修正を適用する前に、パーミッションの問題やファイルシステムの問題ではなく、これが実際の原因であることを確認してください。
問題のパスが実際にどれくらい長いか確認します。エラーメッセージからパスをコピーして次を実行してください：
# PowerShell にて
$path = "C:\Users\yourname\projects\some\very\deeply\nested\path\component\filename.tsx"
$path.Length
数値が 260 を超えていれば、問題が確認できました。現在の Git の設定も確認できます：
git config --global core.longpaths
何も返ってこないか false が返ってくる場合、長いパスのサポートが無効になっています — これが原因です。
修正方法 1：Git で longpaths を有効にする（簡単な修正、たいていこれで十分）
Git for Windows には、Windows の拡張パス構文（\\?\ プレフィックス）を内部的に使用するよう指示する設定フラグがあります。すべてのリポジトリに適用されるようグローバルで有効にします：
git config --global core.longpaths true
その後、クローンまたはチェックアウトを再試行します：
# 新規にクローンする場合
git clone https://github.com/org/repo.git
# すでにクローン済みでワーキングツリーが壊れている場合
git checkout HEAD -- .
ほとんどのリポジトリではこれだけで十分です。Git が Windows API 呼び出しを拡張パスプレフィックスでラップし、260 文字の制限を自動的に回避します。
修正方法 2：Windows レベルで長いパスのサポートを有効にする（場合によっては必須）
ワークフロー内のエディタ、ビルドスクリプト、npm、パッケージマネージャーなどのツールも同じ制限に引っかかることがあります。Git の修正だけでは不十分な場合、またはマシン上のすべてのツールに対して恒久的な解決策が必要な場合は、Windows 自体で長いパスを有効にします。
オプション A：グループポリシー（Windows 10 Pro / Enterprise / Windows 11）
Win + Rを押し、gpedit.mscと入力して Enter を押します。- 次のパスに移動します：ローカルコンピューターポリシー → コンピューターの構成 → 管理用テンプレート → システム → ファイルシステム
- 「Win32 の長いパスを有効にする」 をダブルクリックし、有効 に設定します。
- OK をクリックして再起動するか、管理者ターミナルから
gpupdate /forceを実行します。
オプション B：レジストリの編集（すべての Windows エディションで動作）
# PowerShell を管理者として実行
Set-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1
この変更後に再起動してください。
オプション C：reg.exe を使ったワンライナー（管理者ターミナル）
reg add "HKLM\SYSTEM\CurrentControlSet\Control\FileSystem" /v LongPathsEnabled /t REG_DWORD /d 1 /f
修正方法 3：より短いベースパスにクローンする
システム設定を変更できない場合（例：管理者権限のない会社のマシン）、実用的な回避策としてルートに近い短いパスに直接クローンする方法があります：
# 深くネストされたフォルダにクローンする代わりに：
git clone https://github.com/org/repo.git C:\r\repo
# またはドライブのルートを使用
mkdir D:\dev
git clone https://github.com/org/repo.git D:\dev\repo
リポジトリのルートを C:\Users\yourname\Documents\projects\work\2024\... のような深いパスから C:\dev\repo のような短いパスに移動するだけで、すべてのパスから 50〜80 文字削減でき、260 文字の上限をクリアするのに十分なことが多いです。
修正が機能したかどうかの確認
状況に合った修正を適用した後：
# Git の設定が有効になっているか確認
git config --global core.longpaths
# true と出力されるはず
# チェックアウトを再試行してエラーが出ないか確認
git checkout main
# ファイルが不足していないか確認
git status
# 「nothing to commit, working tree clean」と表示されるはず
# チェックアウトされたファイル数とインデックスが期待するファイル数を比較
git ls-files | wc -l
git ls-files --deleted | wc -l
# 2つ目のコマンドは 0 と出力されるはず
git ls-files --deleted がまだファイルを表示している場合は、git checkout HEAD -- . を実行して修正を適用した状態でワーキングツリーを強制的に復元してください。
チーム全体での予防策について
チームが Windows を使用していてリポジトリのネストが深い場合は、README やオンボーディングドキュメントに、セットアップ時に git config --global core.longpaths true を実行するよう記載しておきましょう。自動的に適用するセットアップスクリプトを同梱することもできます：
# setup.sh / setup.ps1 のオンボーディング手順
git config --global core.longpaths true
echo "Git longpaths enabled."
Windows 上で動作する CI システム（GitHub Actions の windows-latest、Azure Pipelines）でも同様の対応が必要な場合があります。チェックアウトアクションの前にステップとして追加してください：
# GitHub Actions
- name: Enable long paths
run: git config --global core.longpaths true
shell: bash
- uses: actions/checkout@v4
学んだこと
Windows の 260 文字パス制限は古くからあり、今も多くの人を悩ませています。これは Git のバグではありません — Git は単なる伝達者です。本当の修正は、Git に Windows の拡張パス API を使用するよう指示すること（core.longpaths true）か、システム全体で有効にすることです。Git の設定変更は数秒で完了し、95% のケースに対応できます。それでも解決しない場合は、クローンパスを短くしてください — システム設定を変更できないときの最速の逃げ道です。