Introduction

Changing a remote repository's HEAD matters because it affects which branch clients see as the default when they clone or inspect the remote. The confusing part is that there are two related but different operations: changing the actual default branch on the remote server, and updating your local understanding of what the remote HEAD points to. If you separate those two cases, the commands become much easier to reason about.

Understand What Remote HEAD Represents

On a bare remote repository, HEAD is a symbolic reference to the branch that should act as the default branch. Historically that was often master, but many repositories now use main or another branch name.

You can inspect a remote's advertised HEAD like this:

git ls-remote --symref origin HEAD

Typical output will show something like refs/heads/main or refs/heads/master. That tells you what branch the remote considers default for new clones and for symbolic resolution of origin/HEAD.

Change the Actual Remote Repository HEAD

If you control the bare repository on the server, change its HEAD directly there. This is the authoritative change.

On the server:

cd /srv/git/project.git
git symbolic-ref HEAD refs/heads/main

That updates the bare repository so HEAD now points to main instead of master.

This command does not rename branches. It only changes which existing branch is considered the default symbolic reference. Make sure the target branch already exists on the remote before doing this.

Update Hosting-Platform Default Branch Settings

If the remote is hosted on GitHub, GitLab, Bitbucket, or another managed service, the correct place to change the default branch is usually the platform settings page. Those systems often manage the server-side HEAD for you when you change the repository default branch in the UI.

That means the right answer depends on where the repository lives:

1. Bare repository you administer directly: use git symbolic-ref.
2. Hosted repository on a platform: change the default branch in the platform settings.

Trying to run a local Git command against a hosted remote usually cannot override the hosting provider's repository settings.

Update Your Local View of origin/HEAD

Even after the remote default branch changes, your local repository may still have stale knowledge of origin/HEAD. Update it with:

git remote set-head origin -a

The -a flag asks Git to query the remote and set origin/HEAD to whatever the server currently advertises. You can inspect the result with:

git symbolic-ref refs/remotes/origin/HEAD

If you already know the desired branch, you can set it explicitly in the local clone:

git remote set-head origin main

That only updates the local remote-tracking symbolic ref. It does not change the remote server itself.

Know the Difference Between Renaming and Repointing

Developers often conflate these actions:

1. Rename master to main.
2. Push the new branch.
3. Change the remote default branch.
4. Update local clones to track the new default.

They are related, but they are not the same operation. If you only repoint HEAD without creating the branch, the remote becomes invalid. If you rename the branch but never update the remote default, new clones may still point to the old branch.

A common migration flow looks like this:

1git branch -m master main
2git push origin main
3git push origin --delete master
4git remote set-head origin -a

In practice, the hosted-service default-branch update usually sits between the push and the cleanup.

Verify the Result from a Fresh Perspective

After changing the remote, verify from outside your current branch assumptions:

1. Run git ls-remote --symref origin HEAD.
2. Clone the repository into a temporary directory.
3. Check which branch the fresh clone checks out by default.

That is the easiest way to prove the change affected the actual remote behavior and not just one local clone's metadata.

Common Pitfalls

• Changing origin/HEAD locally and assuming that changed the actual remote server default branch.
• Running git symbolic-ref HEAD ... in a normal local clone instead of on the bare remote repository.
• Pointing remote HEAD at a branch that does not exist on the server.
• Renaming branches during a migration but forgetting to update the hosting platform's default branch setting.
• Verifying only in one local clone whose cached origin/HEAD may be stale.

Summary

• The real remote HEAD lives on the server and defines the remote's default branch.
• Use git symbolic-ref HEAD refs/heads/branch-name only on the bare repository you control directly.
• On hosted platforms, change the default branch through repository settings.
• Use git remote set-head origin -a to refresh your local clone's view of origin/HEAD.
• Distinguish clearly between renaming a branch and repointing the remote default branch.