Claude DesktopのworktreeでLFSがポインタのまま — Windowsの原因と直し方

Windows版のClaude Desktopでセッションごとにworktreeを作ると、Git LFSで管理しているファイルが実体ではなくポインタファイルのまま残ることがあります。Unreal EngineのプロジェクトでテストマップがLFSの実体を持たず、読み込む側のテストがタイムアウトした、という報告が出ています。直し方は短く、worktreeの中で git lfs checkout か git lfs pull を実行すれば足ります。

どんな症状か — ファイルが小さく、LFS一覧に「-」が並ぶ

報告された症状は、アプリが作ったworktreeの全LFSファイルがポインタになるというものです。git lfs ls-files を実行すると、各行のOIDの後ろが *(実体あり)ではなく -(ポインタ)で表示されます。この記号の意味は git lfs ls-files の説明にある、アスタリスクが完全なオブジェクト、マイナスがLFSポインタという区別です。

読み込む側のツールは、壊れたデータを渡されたまま動くので、エラーの出方が不自然になります。報告では、129バイトのポインタになったマップファイルが原因で、マップを開くテストがタイムアウトしていました。LFSの話だと気づくまでに時間がかかる型の不具合です。

まず手元のworktreeで、症状が当てはまるかを調べます。

# worktreeのフォルダで実行する
git lfs ls-files

全行が - なら、このページの症状です。* が付いている行は実体が展開済みです。

原因 — アプリがgit-lfsを見つけられずフィルタを切っている

GitHubのissue #103485(2026年10月19日起票、open)は、原因をgit-lfsの検出失敗と見ています。報告者の環境は次のとおりです。

• Claude Desktop 2.42304.0.0(Microsoft Store版・MSIX)、Claude Code 2.1.299
• Windows 11 Pro、Git for Windows 2.56.0.windows.1、git-lfs 3.8.0
• C:\Program Files\Git\cmd がマシンのPATHに入っている
• LFSフィルタはGit for Windowsの導入時にシステムのgitconfigへ設定済み

アプリのログ(%LOCALAPPDATA%\Claude\logs\main.log)には、worktreeを作るたびに次の2行が出ていました。

[info] git-lfs unavailable (not on PATH, or git could not run it) — disabling LFS filter for git operations (pointer files only)
[info] [lfsHydrate] <repo>\.claude\worktrees\<name>: skipped (no_git_lfs) — 0/0 restored from the local store, ...

1行目でアプリが「git-lfsが使えない」と判断し、LFSフィルタを無効にしてチェックアウトします。2行目で、ローカルのLFSストアから実体を戻す自前の処理(lfsHydrate)も no_git_lfs で飛ばされます。成功時に出るはずの Git LFS found at ... の行は、ログに一度も出ていません。報告者のログでは、この2行が少なくとも2026年9月25日以降、worktreeを作るたびに繰り返されていました。

奇妙なのは、同じユーザー・同じPATHのセッションからは git lfs version が通ることです。報告者は、システム一時フォルダからの実行、GIT_CONFIG_NOSYSTEM=1 の指定、存在しない GIT_DIR の指定、PATHを C:\Windows\System32 だけにした最小環境のどれでも、終了コード0でバージョンが表示されたと書いています。where git-lfs も2つの実行ファイルを返しています。

つまりgit-lfsは入っていて動くのに、アプリ側の検出だけが失敗している、という構図です。issueの本文には、この検出がなぜ落ちるかの特定までは書かれていません。

ログで切り分ける — 別の原因もある

ポインタのままになる原因は、これだけではありません。Claude Codeのworktree説明には、別の経路が載っています。git lfs install --local でLFSフィルタをリポジトリ自身の .git/config に書いている場合、Claude Codeが作るworktreeはポインタになります。リポジトリ内の設定が定義するフィルタドライバは、シェルコマンドなので実行されないためです。v2.1.247より前は、worktreeの作成時にこのドライバが実行されていました。--local なしの git lfs install はグローバル設定に書くので、この経路は当たりません。この節の後ろに載せた git config --local --get-regexp で filter.lfs.* の行が返るかどうかが目安です。

どちらの経路かは、ログの有無でおおよそ分けられます。

リポジトリ自身の設定が絡む場合は、ポインタが残るだけでなく、worktreeそのものが作られないこともあります。Claude Codeのworktree説明には、メッセージ別の対処が載っています。たとえば .git/config に includeIf があるときは、その設定を .git/config に直接書いて includeIf を外します。Git was not run: the repository's own git config sets <key> と出たときは、lfs.customtransfer.<name>.path のようなキーを自分のグローバル設定へ移します。心当たりのないキーなら、信頼できないツールやチェックアウトが書いた可能性があるので、リポジトリの設定から消します。

ログを検索するコマンドと、リポジトリ自身の設定を調べるコマンドは次のとおりです。

Select-String -Path "$env:LOCALAPPDATA\Claude\logs\main.log" `
  -Pattern "git-lfs|lfsHydrate"
 
# リポジトリ自身の .git/config だけを対象にフィルタ設定を探す
git config --local --get-regexp "^filter\."

直し方 — 実体がローカルにあるならcheckout、無いならpull

回復コマンドは2つあり、使い分けは「LFSの実体がすでにローカルにあるか」です。

git lfs checkout の説明では、ダウンロードは行わず、ローカルに実体があるときだけ、欠けているファイルかポインタ内容のファイルを実体に置き換えます。変更済みのファイルは上書きされません。git lfs pull は git lfs fetch と git lfs checkout を続けて実行するのと同等、と説明されています。

worktreeは親リポジトリの .git を共有するので、メインのチェックアウトで一度でもLFSの実体を取得していれば、その実体が共有のストアに入っています。報告者はこれを使い、新しいworktreeで git lfs checkout を実行しました。共有の .git/lfs/objects から49ファイル・54MBが0.6秒で埋まり、ネットワークは使わず、git status もクリーンのままだったそうです。

# worktreeのフォルダで実行する
git lfs checkout
git lfs ls-files   # 行の記号が * に変われば成功

実体がローカルに無い場合や、git lfs checkout で全行が埋まらない場合は、git lfs pull を使います。Claude Codeのworktree説明も、フィルタが実行されなかったworktreeには git lfs pull を案内しています。

git lfs pull

Git 2.42.0以降では、git lfs checkout と git lfs pull は既定で、インデックスにあり、.gitattributes のLFS指定に合致するファイルだけを対象にします。部分クローンやスパースチェックアウトのリポジトリでは、先にHEADの .gitattributes を取り出しておくか、環境変数 GIT_ATTR_SOURCE を HEAD にすると対象が揃います。

毎回の手間を減らす — 事前確認の置き方

worktreeを作るたびに手で直すのは面倒なので、症状が出たリポジトリでは確認の手順を決めておくと迷いません。

1. メインのチェックアウトで git lfs ls-files を実行し、すべて * になっていることを確かめる。実体がメイン側に無ければ、worktreeに回復する材料も無い
2. セッションを始めたら、worktreeの中で git lfs ls-files を実行して - の行が無いかを見る
3. - が出ていたら git lfs checkout、足りなければ git lfs pull

LFSファイルを読む処理(ゲームエンジンのテスト、画像・モデルの読み込み)をClaudeに実行させる前に、手順2の確認を1回挟むのが安全です。ポインタを読ませたまま進めると、前述のようにタイムアウトなどの別の症状として現れ、原因の見当がつきにくくなります。

CLAUDE.mdに「LFSファイルを扱う前に git lfs ls-files で - が無いことを確かめる」と書いておけば、毎回の指示も省けます。

似た症状との見分け方

Windows版のworktreeには、LFSのポインタとは別の不具合報告もあります。issueの末尾には、dev\null という名前のフックのディレクトリが残る症状が別件として挙がっており(#69453、#74033、#79923、#81812)、今回の件とは症状が異なります。

LFSそのものが入っていないときは、アプリが「Git LFS is required by this repository but is not installed」と表示します。この場合は、git-lfs.comから導入して git lfs install を実行し、アプリを再起動します。詳しくはClaude DesktopのWindowsセットアップ手順にまとめています。今回の症状は、git-lfsが入っていてもポインタが残る点で区別できます。

worktreeの仕組みと共有されるものの全体像は、Claude Code Worktree実践ガイドが扱っています。Windowsでコマンド実行まわりのPATHが崩れる不具合には、Git BashでPATHが壊れる原因の記事があります。

まとめ

Windows版Claude Desktopのworktreeでは、アプリがgit-lfsを見つけられずLFSフィルタを切ると、全LFSファイルがポインタのまま残ります。issueはopenのままで、修正版の情報はまだありません。当面は git lfs ls-files で状態を確かめ、メイン側に実体があるなら git lfs checkout、無ければ git lfs pull で埋めるのが、通信量も時間も最小の回復です。