Gitで「fatal: ref HEAD is not a symbolic ref」エラーが出たときの解決策

2025.09.22

Git を使って開発をしていると、初回コミットや空のリポジトリに対して操作を行ったときに次のようなエラーが出ることがあります。

fatal: ref HEAD is not a symbolic ref

初めて見ると驚くメッセージですが、これは HEAD が有効なブランチを指していない ことが原因です。つまり「今どのブランチにいるか Git が認識できない」状態です。

本記事では、このエラーの原因と解決策、再現例、CI/CD 環境での注意点まで詳しく解説します。

目次

1. エラーが発生する背景と原因

Git は現在の作業ブランチを HEAD という参照で管理しています。通常、HEAD は refs/heads/main や refs/heads/master を指す symbolic ref になっています。しかし、まだブランチが存在しない空リポジトリでは、HEAD が「どのブランチを指すか」を決められないため、エラーが発生します。

特に以下の状況で起きやすいです。

  • git init 直後でコミットが一度もない
  • .git/HEAD ファイルが壊れている
  • 手動で .git ディレクトリをコピーして中途半端な状態になった
  • CI 環境で shallow clone（–depth 1）した際に HEAD が detached になっている

2. 再現例とエラーメッセージ

空のリポジトリで以下を実行するとエラーを確認できます。

mkdir sample-repo && cd sample-repo
git init
git log
# => fatal: your current branch 'master' does not have any commits yet
git rev-parse --abbrev-ref HEAD
# => fatal: ref HEAD is not a symbolic ref

この時点では HEAD はシンボリックリンクではなく単なるハッシュ値ファイルなので、ブランチ情報がありません。

3. 対処法1: 正しい初回コミットを行う

最も基本的な解決策は、まずコミットを作成して HEAD がブランチを指すようにすることです。

git checkout -b main
echo "# 初回コミット" > README.md
git add README.md
git commit -m "Initial commit"

この操作で .git/HEAD は ref: refs/heads/main を指すようになり、エラーが解消されます。

4. 対処法2: HEAD を手動で修正する

もし .git/HEAD が壊れている場合は、手動で修正可能です。

echo "ref: refs/heads/main" > .git/HEAD

その後、既存ブランチを確認し、必要なら新規作成します。

git branch
git checkout -b main

この方法は CI/CD 環境で HEAD が detached になったときの回避策としても使えます。

5. CI/CD 環境での注意点

GitHub Actions や GitLab CI で shallow clone した場合、HEAD がコミット ID を直接指すことがあります。これにより一部の Git コマンド（git describe や git merge-base）が失敗します。対策としては次の方法が有効です。

  • actions/checkout の fetch-depth: 0 を設定して全履歴を取得
  • 手動でブランチ名を設定 git checkout -B main
  • GIT_COMMIT_REF_NAME のような CI 環境変数を明示的に参照

6. まとめ

「fatal: ref HEAD is not a symbolic ref」エラーは、HEAD が正しいブランチを指していない状態で発生します。初回コミットを作成するか、HEAD を正しい参照に修正すれば解決できます。特に CI/CD 環境では shallow clone や detached HEAD 状態が原因になることが多いため、ブランチを明示的にチェックアウトする設定を追加しておくと安心です。

参考

タイトルとURLをコピーしました