Git skip-worktree で追跡ファイルの変更を無視する方法

TL;DR

既にコミット済みのファイルの変更を無視したい場合は git update-index --skip-worktree を使う。.gitignore や .git/info/exclude は未追跡ファイルにしか効かない。

問題: .git/info/exclude では追跡ファイルの変更を無視できない

プロジェクトごとにローカル環境だけでファイルを無視したい時、.git/info/exclude を使えばいいと思うかもしれない。しかしこれには落とし穴がある。

.git/info/exclude も .gitignore も、未追跡のファイルをignoreするためのもの。既にコミット済み（追跡されている）ファイルには効果がない。

つまり、既にリポジトリに含まれている設定ファイルをローカルでカスタマイズして、その変更を無視したい場合には使えない。

解決策: --skip-worktree を使う

既に追跡されているファイルのローカルでの変更を無視するには、git update-index --skip-worktree を使う:

# ローカルの変更を無視する
git update-index --skip-worktree path/to/file

# 元に戻す
git update-index --no-skip-worktree path/to/file

--skip-worktree とは

これは「このファイルはローカルで変更するけど、その変更は追跡しない」という設定。設定ファイルのローカルカスタマイズなど、意図的に変更を無視したい場合に使う。

よくある使用例

• 開発環境の設定ファイル（config/local.py, .env.local など）のカスタマイズ
• IDEの設定ファイルの個人向け調整
• ローカル専用のデバッグ用設定

設定されているファイルの一覧を確認する

# --skip-worktree が設定されているファイルの一覧
git ls-files -v | grep '^S'

# パス名だけ欲しい場合
git ls-files -v | grep '^S' | cut -c 3-

git ls-files -v の出力の意味

• S = skip-worktree が設定されている
• H = 通常の追跡ファイル
• h = assume-unchanged が設定されている

エイリアスを作っておくと便利

git config --global alias.skipped "ls-files -v | grep '^S'"

# 使う時
git skipped

--skip-worktree vs --assume-unchanged

Git には似たようなオプションとして --assume-unchanged もあるが、用途が異なる:

推奨: ローカルの変更を意図的に無視したい場合は --skip-worktree を使う方が確実。

注意点

リモートの更新とのコンフリクト

リモートで同じファイルが更新されて git pull しようとするとコンフリクトする可能性がある。その場合は:

# 一旦 skip-worktree を解除
git update-index --no-skip-worktree path/to/file

# ローカルの変更を退避
git stash

# リモートから取得
git pull

# 必要に応じて変更を戻す
git stash pop

# 再度 skip-worktree を設定
git update-index --skip-worktree path/to/file

チーム開発での注意

--skip-worktree はローカル設定なので、チーム全体で無視したいファイルには .gitignore を使うべき。

まとめ

• 未追跡ファイルを無視: .gitignore または .git/info/exclude
• 追跡ファイルの変更を無視: git update-index --skip-worktree
• 設定の確認: git ls-files -v | grep '^S'

ローカル環境固有の設定変更を気にせず開発できるようになる、地味だけど便利なテクニックだ。