マージ中の git checkout HEAD -- <path> は無関係なファイルまで巻き戻す

症状

git merge がコンフリクトで停止している間（まだ merge commit を作っていない間）は、HEAD は依然としてマージ前の自分のコミットを指す（マージ相手は MERGE_HEAD）。

この状態で、無関係なファイルの挙動を切り分けようとして

git checkout <相手ブランチ> -- <path>   # 相手側の内容を一時的に見る
# ... 確認 ...
git checkout HEAD -- <path>             # 元に戻したつもり

を打つと、<path> は「マージ前の自分の版」に強制的に戻る。そのファイルを自分のブランチが一度も変更していなくても、3-way merge が無競合で自動的に取り込んでいた相手側の変更ごと消える。

コンフリクトマーカーが無いファイル（＝自動マージが成功したファイル）は一見「触っていない」ように見えるため、この巻き戻りは目視レビューでは気づきにくい。CI（あるいは相手側の変更を前提にした後続のテスト）で初めて発覚する。

実際に起きたこと

大きなコンフリクト（別ファイル）を解消する過程で、無関係な1ファイルのテスト失敗を切り分けるために上記のパターンを実行し、そのまま merge commit して push した。結果、相手ブランチ側が既に入れていた修正（子プロセス起動に windowsHide: true を付ける、という全ファイル横断の lint 的テストで担保されていた規約）が巻き戻った状態で main にマージされた。CI の当該テストが検出するまで気づかなかった。

Why

マージ処理中は「HEAD ＝ 今の作業内容」という直感が成立しない。conflict 解消中に何かを一時的に見比べたい／退避したい、と思った瞬間が罠になる。

回避策

• マージ・リベース進行中に特定パスを一時的に見比べたい／退避したい時は、HEAD ではなく具体的なコミットSHAかブランチ名を使う。
  • ファイル内容だけ確認したいなら git show <ref>:<path> を別ファイルに書き出して diff する（作業ツリーは触らない）。
  • どうしても checkout したいなら git checkout <具体的なref> -- <path>（HEAD ではなく実際の SHA / ブランチ名）。
• マージ完了（commit）後は、そのマージが自動解決したファイルも含めて、CI・関連テストを一通り流す。「コンフリクトマーカーが消えた＝正しい」ではない。
• 迷ったら git merge --abort でやり直す方が、誤った状態で commit するより安全。
• 複数の作業を同じ working directory で並行させない（マージ作業は git worktree add で専用の作業ディレクトリを切ると、この種の取り違えごと起きにくくなる）。

適用範囲

git を使う開発全般。GitHub / GitLab / 自前 git サーバ、言語・フレームワーク問わず、コンフリクト解消の途中で「一時的にファイルを退避・復元したい」場面全てに当てはまる。