git branch -M main

Question

One of the things github now recommends is changing the branch to main instead of master.

The code given on the github site is:

git branch -M main

That never works for me, so I thought I would mention it here. I have a hard time believing this problem only occurs with me.

error: refname refs/heads/master not found
fatal: Branch rename failed

Answer 1

You mention in your own answer that git branch -m main (or the same with -M) only works once you have an initial commit.

Alternatively, before creating any commits, use git checkout -b main to switch the name of the unborn branch to main.

There is no functional difference between creating the initial commit, then renaming the branch, vs changing the unborn branch name, then making the initial commit. Commits do not remember which branch was the current branch when they were made,¹ so you're free to change branch names at any time. (Other people remember branch names, in their brains, and may have saved some branch names in clones, so it's best to do all these name changes before anyone else gets hold of these names. But that's outside your own Git.)

---

¹The git merge command does, however, generate a default merge message:

merge branch X [into Y]

and git pull generates a default merge message:

merge branch X of 'url' [into Y]

where X is the argument you gave to git merge—with a URL added when using git pull to run git merge—and Y is present, and is the name of the current branch, if the current branch is not the designated "special" branch. This was hardcoded as master in the past, but is becoming configurable. The end result of all of this is that you tend to get messages of the form merge branch feature when merging features into master/main, and messages of the form merge branch feature into develop when merging features into other branches.

Note that these autogenerated messages convey relatively little useful information, especially if you delete the feature branch after merging it. To take a particular example, suppose you reserve the name hotfix for a temporary branch on which hot-fixes are made. Then your repository will have the occasional "merge branch hotfix" commit, but each of these messages is for a different hotfix. The information being conveyed here is nearly useless—you need the date of the merge, not just the message, to find the right "hot bug". At worst, it may be worse than useless since it might send you looking at the wrong "hot bug". If you manually replace this with "merge fix for critical customer bug #1234", you get a useful message.

(If your branch names include the bug-reference-number, then these messages are useful. The "into branch Y" part, which uses the current branch, still seems quite marginal to me, though.)