【Git】「remote HEAD refers to nonexistent ref」警告の原因と対処法｜4パターン診断と根本対処完全ガイド

$ git clone https://github.com/user/repo.git
Cloning into 'repo'...
warning: remote HEAD refers to nonexistent ref, unable to checkout.

# リモート側HEADの情報（git protocol）
git ls-remote --symref origin HEAD
# 出力例:
# ref: refs/heads/main	HEAD   ← mainを指す
# abc1234...	HEAD

# クライアント側HEADの設定
cat .git/refs/remotes/origin/HEAD
# または
git symbolic-ref refs/remotes/origin/HEAD

# リモートで存在するブランチ一覧
git ls-remote --heads origin

# リモートのHEADが指す先を確認
git ls-remote --symref origin HEAD
# → ref: refs/heads/XXX   ← このXXXが実在するかが鍵

# ブランチ一覧（HEAD候補）
git ls-remote --heads origin

# cloneしたあとの状態確認
cd repo
git branch -a
# → 存在するリモート追跡ブランチ一覧

# 現在HEADの状況
git status
# → "HEAD detached" 等の表示がヒントになる

# サーバーにSSHでログイン
ssh git@your-server.example.com
cd /path/to/repo.git

# 現在のHEAD設定を確認
cat HEAD
# 例: ref: refs/heads/master

# 実在ブランチを指すよう書き換え
git symbolic-ref HEAD refs/heads/main

# 確認
cat HEAD
# ref: refs/heads/main

# リモートに問い合わせて実在のdefault branchを自動検出＋設定
git remote set-head origin --auto
# 出力例: origin/HEAD set to main

# 明示的に指定する
git remote set-head origin main

# いったん解除（稀）
git remote set-head origin --delete

# 確認
git symbolic-ref refs/remotes/origin/HEAD
# → refs/remotes/origin/main

# cloneしたがカレントに作業ツリーが無い状態
cd repo
ls
# → 空っぽ

# 実在ブランチを一覧
git branch -r
#   origin/main
#   origin/develop

# ローカルブランチを作って切り替え
git switch main
# Git 2.23+ なら自動でリモート追跡を設定

# 旧コマンドでの対応
git checkout -b main origin/main

# 実在ブランチを確認
git ls-remote --heads origin | grep -E "master|main"

# クライアントのHEAD追跡を更新
git remote set-head origin --auto

# ローカルがmasterを指していた場合の移行
git switch main    # Git 2.23+で自動トラック

# 古い master ローカルブランチを削除（不要）
git branch -d master

# 管理権限があるなら GitHub UIで
# Settings → General → Default branch → 別ブランチに切替

# その後、削除されたブランチをreflogから復元
git clone https://github.com/user/repo.git
cd repo
git reflog --all | grep "deleted-branch-name"
# 見つかったSHAで復元（権限があれば）

cd repo

# Gitのデフォルトブランチ名設定（任意）
git config --global init.defaultBranch main

# 空リポなので git initの代わりに branch を切る
git switch -c main

# 最初のcommit
echo "# My Project" > README.md
git add README.md
git commit -m "feat: initial commit"

git push -u origin main

ssh git@server
cd /var/git/repo.git

# 現状
cat HEAD
# ref: refs/heads/nonexistent-branch

# 実在ブランチを確認
ls refs/heads/
# main develop

# HEADを実在ブランチに向ける
git symbolic-ref HEAD refs/heads/main

#!/bin/bash
# safe-clone.sh
REPO_URL=$1
git clone "$REPO_URL"
cd "$(basename "$REPO_URL" .git)"

# HEADがない場合の自動修復
if ! git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null; then
  git remote set-head origin --auto
fi

# 作業ツリーが空だったら実在ブランチに切替
if [ -z "$(ls -A)" ] || [ "$(ls -A | wc -l)" -eq 1 ]; then
  git switch "$(git remote show origin | grep "HEAD branch" | awk '{print $NF}')"
fi

git clone https://github.com/user/repo.git
# warning: remote HEAD refers to nonexistent ref

cd repo
ls
# → 空

# 応急対処：実在ブランチを確認してcheckout
git branch -r
git switch main    # 実在するブランチ名

# 本対処：管理者に伝えてdefault branch設定の更新を依頼

# STEP 1: ローカルを改名
git branch -m master main

# STEP 2: 新ブランチをpush（upstreamも設定）
git push -u origin main

# STEP 3: GitHub UIでdefault branchをmainに変更（先に！）

# STEP 4: 旧masterを削除
git push origin --delete master

# STEP 5: クライアントのHEAD追跡を更新
git remote set-head origin --auto

git clone https://github.com/user/empty-repo.git
# warning: you appear to have cloned an empty repository.

cd empty-repo

# デフォルトブランチ名の設定
git config --global init.defaultBranch main
git switch -c main

# 初期ファイル
cat > README.md << "EOF"
# My Project
EOF

git add README.md
git commit -m "feat: initial commit"
git push -u origin main