detached HEAD とは？

detached HEAD とは、HEAD がブランチではなくコミットを直接指している状態で、新しいコミットがどのブランチにも紐づかない状態です。

detached HEAD の警告は初心者を不安にさせることが多いですが、理解すれば無害です。単に、ブランチではなく特定のコミット、タグ、あるいはリモート ref をチェックアウトしたという意味です。自由に見て回れますが、作成した新しいコミットを保持するにはブランチが必要です。

どのように発生するか

コミットハッシュ、タグ、あるいはリモート追跡ブランチを直接チェックアウトすると HEAD が detached になります。これらはいずれも移動できるローカルブランチではないからです。HEAD はそのコミット自体を指すようになります。ここで作成したコミットはどのブランチにも属さないため、Git が警告します。

detached HEAD への出入り

古いコミットを調べてから、ブランチに戻る、あるいは新しいブランチに作業を保存できます。

Working in and out of detached HEAD

git checkout a1b2c3d
# look around, maybe commit
git switch -c rescue-branch
git switch main

注意すべきリスク

detached HEAD で作成したコミットはどのブランチからも参照されないため、切り替えて離れるとガベージコレクションされて失われる可能性があります。対処法は簡単で、離れる前に今いる場所からブランチを作成すれば、作業は安全に固定されます。

なぜ CI は detached HEAD を使うのか

CI ランナーはテスト対象の正確なコミットをチェックアウトすることが多く、それによりジョブが意図的に detached HEAD 状態になります。パイプラインはその特定のスナップショットをビルドするだけでよく、ブランチを進める必要はないため、workflow run 内では detached HEAD は正常で想定内であり、修正すべき問題ではありません。

detached HEAD で安全に保つ

作業を保持したい場合はコミットする前にブランチを作成します。
detached HEAD はデフォルトで読み取り専用の探索として扱います。
CI は意図的にこの状態で実行されることに注意します。
git switch - を使って直前のブランチに戻ります。

重要なポイント

detached HEAD はブランチではなくコミットを指します。
そこで作成したコミットは、ブランチを作らない限り失われる可能性があります。
CI のチェックアウトは、特定のコミットをビルドするために意図的に detached HEAD を使います。