Why use "HEAD:master" instead of just "master" in a "git push origin"

Question

I am synching multiple git repositories. It's challenging; I can sync just the diffs easily, but if I want to sync changes I need to do pulls and pushes, and (sometimes) resolve the conflicts locally.

Sometimes, when I do a git push, git tells me to use:

git push origin HEAD:<name-of-remote-branch>

which usually becomes:

git push origin HEAD:master

However, this also works:

git push origin master

So what's the difference? Why do I need the HEAD: ?

Answer 1

When you run

git push origin X:Y

What happens is that you push something locally named X to the remote name Y. HEAD is an alias for whatever is currently checked out. If you currently have master checked out, then this is equivalent to

git push origin master:master

If you have a different branch checked out, you get different behavior. You do not need HEAD and I would avoid using it when pushing.

If you omit :master and just run:

git push origin master

It will use master as the default branch name on the remote, unless you have configured it differently.