Uncategorized

Git管理のファイルを汚さずにローカル開発を快適にする「–skip-worktree」と「.git/info/exclude」の使い分け

Yamaori Ritsuki
Yamaori Ritsuki ・ Backend

背景

ローカル環境での開発を進める中で、以下のような2つの課題が発生していました。

  1. Cursorのワークスペース設定（.code-workspace）が変更を検知してしまう
    自分好みのエディタ設定や拡張機能の設定を含めたワークスペースファイルを作ったが、これは自分専用のもの。チーム共通の .gitignore に追跡対象外として勝手に追加するわけにはいかず、かといって毎回 git status に表示されるのがノイズになっていた。
  2. ローカル検証のために、外部連携のコードをコメントアウトしたファイルがコミット対象に入ってしまう
    外部APIやステージング環境との連携を一時的に無効化したコードでローカル開発を行いたいが、そのファイル自体はリポジトリで追跡されている重要ファイル。うっかりそのまま git commit や git push をしてしまいそうになるリスクがあった。

これらはどちらも「Gitの変更検知から外したい」という要望ですが、対象のファイルが Gitに追跡されているかどうか でアプローチを変える必要があります。

対策

結論として、今回のケースは以下の2つの機能を使い分けることで綺麗に解決できました。

  • Cursorの .code-workspace（未追跡ファイル）
    .git/info/exclude を使用して、自分専用の無視リストに登録する。
    一言で言えば「自分専用・ローカル専用の .gitignore」です。
  • 外部連携をコメントアウトしたファイル（追跡中ファイル）
    git update-index –skip-worktree を使用して、ローカルの変更をGitに無視させる。

2つのアプローチの違い

機能対象ファイルの状態今回のユースケース
.git/info/exclude未追跡（Untracked）自分専用のエディタ設定ファイル（.code-workspace）の除外
–skip-worktree追跡中（Tracked）外部連携をコメントアウトした共通ファイルの変更無視

どちらも設定は自分のローカル環境（.git ディレクトリ内など）にのみ閉じているため、リモートリポジトリや他のメンバーの環境を汚すことはありません。

具体的な設定手順

1. Cursorの設定ファイルを隠す（.git/info/exclude）

.git/info/exclude は、リポジトリにコミットされない「自分専用の .gitignore」です。

.git/info/exclude ファイルをエディタで開き、最下部に以下の行を追加します。

*.code-workspace

これで、共通の .gitignore を編集することなく、自分だけの環境でワークスペースファイルが git status に表示されなくなります。

2. 追跡中ファイルのローカル変更を一時的に無視する（–skip-worktree）

git update-index コマンドを使用します。

外部連携をコメントアウトした対象ファイルに対して、以下のコマンドを実行します。

git update-index --skip-worktree {ファイル名}

これで、ローカルでどれだけコードを書き換えても、Gitは変更がないものとして扱ってくれます。

設定を戻したい時、確認したい時

開発が終わり、元の状態（Gitの追跡対象）に戻したい場合は –no-skip-worktree を指定します。

# 設定の解除
git update-index --no-skip-worktree {ファイル名}

# 現在 skip-worktree しているファイルの一覧確認
git ls-files -v | grep '^S'

※ git ls-files -v を実行した際、頭に S（Skip-worktreeの略）がついているファイルが、現在無視されているファイルです。

リモートで変更があった時の挙動

–skip-worktree を設定しているファイルに対して、他のメンバーが変更を加えてリモートリポジトリに push し、それを自分が pull しようとした場合、Gitがコンフリクトを検知し、以下のようなエラーを出してマージ処理を安全にストップしてくれます。

error: Your local changes to the following files would be overwritten by merge:
          path/to/file.ts
  Please commit your changes or stash them before you merge.
  Aborting

このエラーが出た場合、複雑な git stash を使うよりも、「一度設定を解除して変更を破棄し、pullした後に再度変更する」 のが一番シンプルで手戻りがありません。

具体的には、以下の4ステップでサクッと解決できます。

# 1. 一度 skip-worktree の設定を解除する
git update-index --no-skip-worktree {ファイル名}

# 2. ローカルの変更（コメントアウトなど）を破棄してリモートの状態に戻す
git checkout -- {ファイル名}
# 私はCursorからGUIで変更を破棄してます

# 3. リモートの最新コードを pull する
git pull origin main
# 私はCursorからGUIでpullしてます

# 4. 再度ファイルに変更を加え、skip-worktree を再設定する
# （ファイルを編集後、以下を実行）
git update-index --skip-worktree {ファイル名}

まとめ

今回は、自分専用の未追跡ファイルを隠す .git/info/exclude と、追跡中ファイルのローカル変更を無視する –skip-worktree の具体的な活用例を紹介しました。

これらを駆使することで、「うっかり不要なファイルをコミットしてしまう恐怖」や「git status が汚れるストレス」から解放され、より安全で快適なローカル開発環境を作ることができます。ぜひ試してみてください。

おすすめ記事

Recommend