リモートリポジトリの HEAD の確認と、有効な参照を設定する手順

無料のバージョン管理ソフト Git のクライアントソフト TortoiseGit を用いて、リモートリポジトリをクローンした際に表示された警告「warning: remote HEAD refers to nonexistent ref, unable to checkout」の対処例を紹介します。
リモートリポジトリの HEAD の参照の確認と、有効な参照を設定する手順も紹介します。

※ TortoiseGit-2.17.0.2-64bit を使用します。

作成・Push したリモートリポジトリをクローンした際の警告

TortoiseGit を用いてリモートリポジトリを作成して、ローカルリポジトリからコミットを main ブランチに Push した後に、空のフォルダにクローンを作成した際に、以下の警告が表示されました。

warning: remote HEAD refers to nonexistent ref, unable to checkout

警告: リモート HEAD が存在しない参照を参照しているため、チェックアウトできません

下図は、その際のクローンのダイアログの設定です。

クローンの実行時のログに先ほどの warning が表示されています。

git.exe clone --progress -v -- "G:\Dev\remotes\godot\SakuraCrowdGodotLib" "G:\Dev\Godot4GD\SakuraCrowd\tmp\SakuraCrowdGodotLib"
Cloning into 'G:\Dev\Godot4GD\SakuraCrowd\tmp\SakuraCrowdGodotLib'...
done.
warning: remote HEAD refers to nonexistent ref, unable to checkout

成功 (766 ms @ 2025/08/04 16:12:21)

この警告の意味

warning: remote HEAD refers to nonexistent ref, unable to checkout

警告: リモート HEAD が存在しない参照を参照しているため、チェックアウトできません

上記の警告は、リモートリポジトリの HEAD が無効な参照のため、チェックアウトは行わなかったことを意味します。
しかし、リモートリポジトリから複製された .git フォルダの作成は成功しています。

The warning: remote HEAD refers to nonexistent ref, unable to checkout. means that the remote (bare) repository contains branch reference in the file called HEAD with a value that does not match any published branch in the same repository. In practice, that file defines which branch should be checked out by default after cloning the repository.

Note that the warning only means that git didn’t do checkout. The cloned repository is otherwise just fine. Just do git branch -a to see possible branches and git checkout the-branch-you-want to workaround the issue.

警告: リモート HEAD は存在しない参照を参照しているため、チェックアウトできません。これは、リモート (ベア) リポジトリに、同じリポジトリ内のどの公開ブランチにも一致しない値を持つ HEAD というファイル内のブランチ参照が含まれていることを意味します。実際には、そのファイルは、リポジトリのクローン作成後にデフォルトでどのブランチをチェックアウトする必要があるかを定義します。

この警告は、git がチェックアウトを実行しなかったことを意味するだけであることに注意してください。それ以外の点では、複製されたリポジトリは問題ありません。 git Branch -a を実行して考えられるブランチを確認し、問題を回避するために必要なブランチを git checkout するだけです。

git – warning: remote HEAD refers to nonexistent ref, unable to checkout – Stack Overflow と Google 翻訳

リモートリポジトリの HEAD を確認

リモートリポジトリのあるディレクトリに移動して、コマンドプロンプトで、無効な HEAD の内容を確認してみましょう。

git branch コマンドを使うと、プッシュした際に指定した main ブランチだけがリモートブランチに存在しています。

G:\Dev\remotes\godot\SakuraCrowdGodotLib>git branch
  main

If --list is given, or if there are no non-option arguments, existing branches are listed; the current branch will be highlighted in green and marked with an asterisk. Any branches checked out in linked worktrees will be highlighted in cyan and marked with a plus sign. Option -r causes the remote-tracking branches to be listed, and option -a shows both local and remote branches.

–list が指定されている場合、またはオプション以外の引数がない場合は、既存のブランチがリストされます。現在のブランチは緑色で強調表示され、アスタリスクが付けられます。リンクされたワークツリーでチェックアウトされたブランチはシアンで強調表示され、プラス記号が付けられます。オプション -r を指定すると、リモート追跡ブランチがリストされ、オプション -a を指定すると、ローカル ブランチとリモート ブランチの両方が表示されます。

Git – git-branch Documentation と Google 翻訳

git symbolic-ref HEAD コマンドを実行すると、HEAD の内容を確認できます。
その結果、refs/heads/master という main とは異なる存在しないブランチの参照が設定されています。

G:\Dev\remotes\godot\SakuraCrowdGodotLib>git symbolic-ref HEAD
refs/heads/master

Given one argument, reads which branch head the given symbolic ref refers to and outputs its path, relative to the .git/ directory. Typically you would give HEAD as the <name> argument to see which branch your working tree is on.

1 つの引数を指定すると、指定されたシンボリック ref が参照するブランチ ヘッドを読み取り、.git/ ディレクトリを基準としたそのパスを出力します。通常、作業ツリーがどのブランチにあるかを確認するには、 引数として HEAD を指定します。

Git – git-symbolic-ref Documentation と Google 翻訳

git symbolic-ref HEAD のかわりに、 HEAD ファイルをテキストエディタで開いたり、コマンドプロンプトで type HEAD と入力することで HEAD の設定を確認できます。

G:\Dev\remotes\godot\SakuraCrowdGodotLib>type HEAD
ref: refs/heads/master

リモートリポジトリの HEAD を設定

git symbolic-ref HEAD のあとに設定するブランチを指定することで、 HEAD の設定を変更できます。

git symbolic-ref HEAD refs/heads/main

上記のコマンドで、存在しない master ブランチのかわりに main ブランチの参照を設定しました。

その後、確認すると HEAD の参照が refs/heads/master から refs/heads/main に変更されています。

G:\Dev\remotes\godot\SakuraCrowdGodotLib>git symbolic-ref HEAD refs/heads/main

G:\Dev\remotes\godot\SakuraCrowdGodotLib>git symbolic-ref HEAD
refs/heads/main

G:\Dev\remotes\godot\SakuraCrowdGodotLib>type HEAD
ref: refs/heads/main

外部から設定する場合

リモートリポジトリを外部のローカルリポジトリから設定する場合は、以下のコマンドのように git remote set-head を用いるようです。
※ origin は、リモートリポジトリの URL を指すリモートの設定名の例です。

git remote set-head origin -a

Manage the set of repositories (“remotes”) whose branches you track.

ブランチを追跡するリポジトリ (「リモート」) のセットを管理します。

set-head

Sets or deletes the default branch (i.e. the target of the symbolic-ref refs/remotes/<name>/HEAD) for the named remote. Having a default branch for a remote is not required, but allows the name of the remote to be specified in lieu of a specific branch. For example, if the default branch for origin is set to master, then origin may be specified wherever you would normally specify origin/master.

指定されたリモートのデフォルトのブランチ (つまり、symbolic-ref refs/remotes//HEAD のターゲット) を設定または削除します。リモートのデフォルト ブランチを持つことは必須ではありませんが、特定のブランチの代わりにリモートの名前を指定できます。たとえば、origin のデフォルト ブランチが master に設定されている場合、通常はorigin/master を指定する場所に、origin を指定できます。

With -a or –auto, the remote is queried to determine its HEAD, then the symbolic-ref refs/remotes//HEAD is set to the same branch. e.g., if the remote HEAD is pointed at next, git remote set-head origin -a will set the symbolic-ref refs/remotes/origin/HEAD to refs/remotes/origin/next. This will only work if refs/remotes/origin/next already exists; if not it must be fetched first.

-a または –auto を使用すると、リモートにクエリが実行されて HEAD が決定され、symbolic-ref refs/remotes//HEAD が同じブランチに設定されます。たとえば、リモート HEAD が next を指している場合、 git Remote set-headorigin -a は、symbolic-ref refs/remotes/origin/HEAD を refs/remotes/origin/next に設定します。これは、refs/remotes/origin/next がすでに存在する場合にのみ機能します。そうでない場合は、最初に取得する必要があります。

Git – git-remote Documentation と Google 翻訳

再びクローンを行い警告が出ないことを確認

空のフォルダを新規作成して、HEAD の有効な参照を設定したリモートリポジトリをクローンして、先ほどの警告が出ないことを確認します。

作成した空のフォルダをエクスプローラで開いて、右クリックして表示されるメニュー「Git クローン（複製）…」を選択します。

URL の欄にリモートリポジトリの URL を指定して、ディレクトリの欄にクローンを作成するフォルダパスを指定して OK ボタンを押します。

git clone の実行のログに warning（警告）が表示されなくなりました。

git.exe clone --progress -v -- "G:\Dev\remotes\godot\SakuraCrowdGodotLib" "G:\Dev\Godot4GD\SakuraCrowd\tmp\1\SakuraCrowdGodotLib"
Cloning into 'G:\Dev\Godot4GD\SakuraCrowd\tmp\1\SakuraCrowdGodotLib'...
done.

成功 (344 ms @ 2025/08/07 11:53:42)

注意：シンボリックリンクはファイルとして作成されました

クローンの際に警告は表示されず、チェックアウトも自動的に行われました。
しかし、管理者権限のない TortoiseGit で、 core.symlinks の設定が false だったため、シンボリックリンクとして管理されている gut は、ファイルとして作成されてしまいました。

これについては、前回のチェックアウトの記事を参照してください。

Git for Windows リモートリポジトリのシンボリックリンクを取得

無料のバージョン管理ソフトGitで、リモートリポジトリのシンボリックリンクを Windows でチェックアウトしてただのファイルとして作成された場合の対処例を紹介します。リモートリポジトリのブランチの管理している項目がシンボリックリンクであることの確認、ローカルリポジトリでシンボリックリンクを扱う設定も紹介します。

compota-soft.work

2025.10.26

G:\Dev\Godot4GD\SakuraCrowd\tmp\1\SakuraCrowdGodotLib\addons>dir
 ドライブ G のボリューム ラベルは ボリューム です
 ボリューム シリアル番号は 9691-AE5E です

 G:\Dev\Godot4GD\SakuraCrowd\tmp\1\SakuraCrowdGodotLib\addons のディレクトリ

2025/08/07  11:53    <DIR>          .
2025/08/07  11:53    <DIR>          ..
2025/08/07  11:53                29 gut
               1 個のファイル                  29 バイト
               2 個のディレクトリ  2,423,411,396,608 バイトの空き領域

リモートリポジトリのログメッセージを確認

HEAD に有効な参照 (main ブランチ) を設定したことで、以前は存在しない master ブランチの空のコミット履歴を表示してたログメッセージウィンドウを起動すると、ブランチを指定しなくても main ブランチのコミット履歴のログメッセージが表示されるようになりました。

まとめ

今回は、無料のバージョン管理ソフト Git のクライアントソフト TortoiseGit を用いて、リモートリポジトリをクローンした際に表示された警告「warning: remote HEAD refers to nonexistent ref, unable to checkout」の対処例を紹介しました。
リモートリポジトリの HEAD の参照の確認と、有効な参照を設定する手順も紹介しました。

参照サイト Thank You!

• Git
• TortoiseGit – Windows Shell Interface to Git
• git – warning: remote HEAD refers to nonexistent ref, unable to checkout – Stack Overflow
• Git – git-symbolic-ref Documentation
• Git – git-remote Documentation

記事一覧 → Compota-Soft-Press