How to add missing origin/HEAD in git repo

Question

I have a working git repo. However, I miss the remotes/origin/HEAD -> origin/master when typing git branch -a. Why is the HEAD missing and how can I add the missing HEAD to my repo?

Answer 1

Original Answer:

The origin's HEAD is only fetched when you clone the repo. If you otherwise add the remote (e.g. by using git remote add or by renaming another existing remote), this ref will not exist, because there is not reason to have it.

Remote repos should be bare repos in most cases, and in bare repos HEAD merely points to the "default" branch. This is only relevant at one time: when cloning. Therefore, after cloning, any remote HEADs are no longer important to your clone and Git will not fetch that ref from any remote.

---

As user lesmana requested, I looked into this again to find some more information:

"How to remove origin/HEAD?"

You do not have to do this.

The ref has no influence on the way your repo operates, and a ref is literally just a small text file on your file system, so it takes up nearly no space (just a few bytes).

If you still want to remove it, you can use

git update-ref -d refs/remotes/origin/HEAD 

(if you want to remove a remote HEAD that is not on origin, use the respective remote's name instead).

"How to create origin/HEAD?"

As pointed out earlier, a remote HEAD ref is only used for cloning, and never required by Git at a later time. Unless you manually use it (which does not seem very useful, you can just use the branch it points to), there is no reason to manually create it.

Nevertheless, if you absolutely must, you can use

git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/master 

"Why is a remote HEAD not removed automatically by clone if it really is useless?"

There is no specific reason, from what I can tell, other than maybe inform the user explicitly of which branch is considered the default branch in the cloned remote repo. However, as I mentioned above, its existence causes no problems and uses up almost no space, so there is no real reason to remove it.

For more details, feel free to ask the Git devs directly at the Git mailing list :)

"What is the exact reason why clone needs it?"

None of the man pages explain directly that git clone always uses this, but it finds sidelong mentions in some places.

For example, man git clone says:

--branch <name>
-b <name>

Instead of pointing the newly created HEAD to the branch pointed to by the cloned repository’s HEAD, point to <name> branch instead. [...]

and

--[no-]single-branch

Clone only the history leading to the tip of a single branch, either specified by the --branch option or the primary branch remote’s HEAD points at. [...]

Furthermore, man gitrepository-layout says:

HEAD

[...] It does not mean much if the repository is not associated with any working tree (i.e. a bare repository), but a valid Git repository must have the HEAD file; some porcelains may use it to guess the designated "default" branch of the repository (usually master).

This means that

• a) the remote repo itself must have the HEAD ref (to be valid), even though it is not semantically important (other than to point out the default branch)
• b) git clone uses the remote repo's HEAD ref to determine where to point the local HEAD (unless you specify an override with --branch). To work with that ref, it must locally create it (therefore origin/HEAD). As mentioned above, it is then simply not deleted.