I’ve started moving projects over from using
master as the main
main as the main branch. As usual, the territory has
detail not represented in the map – here I hope to fill in some
detail, while I’m going through the process.
Changing the branch for your own git repository
Here’s good advice on changing your default git
main. I’ll summarise the command-line bit in this section
below, but there’s more detail in that post.
The following changes the name of
master branch to
preserving commit history and the reflog (the log of changes to refs,
like renaming a branch; since refs are mutable, this is often
consulted to recover old states).
It is very important to pull from origin before changing the name; if
you’re like me, you’ll frequently end up on a PR branch which is
merged at GitHub but not locally. Changing the name of the branch
then pushing that does not have any safeguards against
non-fast-forwards, so you can end up losing merges. If you do
accidentally do it, you’ll need to chase down the head of master and
git merge --ff-only it into
main at the least; if you already
deleted the branch at origin, you may need to chase down merge
Pushing to the origin with
-u creates the branch in the upstream
repository (e.g., on gitHub), while also setting that as the upstream
for the branch, so
git push without arguments works.
$ # just in case you're not already there $ git switch master $ git pull origin master $ git branch -m master main $ git push -u origin main
Changing the default branch for a project in GitHub
GitHub has a setting for the “default branch”, which for instance is made the target of PRs by default.
You can set this default branch via the
Settings tab for a
Branches item. You could also update branch protection
rules if you have them, while you’re there.
At present, you can’t make a default for the default branch in new repositories, in GitHub; you’ll have to go back after creating a new repo and change that setting (ideally before it gets cloned anywhere). There are details of further changes GitHub is working on at github/renaming.
You should probably also delete the
master branch from the GitHub
project, which will help prevent people from unwittingly using it as
an upstream. You do this through the
Branches item in the
view (not via
Settings, but beware that you will have to go through
and retarget any pull requests that point at
master. This is
probably going to be easier to accomplish when GitHub have made some
of those changes they’re talking about.
After deleting it, I added a branch protection rule for
requiring PRs (and linear history, and including admins) so that
pushing to master would not work easily. It’s not possible to just
disallow a branch, but this will stop accidental pushes to
Changing the default branch for git init
As of git 2.28, you can set the initial branch when creating a new git repo:
git init --initial-branch main
and better still, you can give a default for this in git config:
git config --global init.defaultBranch main
Getting other people to change the branch
Also from the post linked at the top: every person that has a local clone of the git repository should do the
git branch -m master main
bit, to rename their local branch, and can change default git config as above.
They will then need to rename the branch and its upstream, otherwise they’ll end up fetching uselessly from the old branch. This is a bit different to the first instance of renaming and pushing the main branch:
$ # After the rename above $ git switch main $ git fetch $ git branch --unset-ustream $ git branch -u origin/main $ git pull --ff-only origin main
If you’ve set the default branch for the remote (so you can
git push origin rather than
git push origin master), you can update that
$ git remote set-head origin main
(In the post linked at the top, it uses
git symbolic-ref to do this;
I believe the command immediately above is equivalent, and it’s more
obvious what it does.)
Another place that the git branch comes up is continuous integration,
since there is often some kind of gating or dispatch based on the git
branch. I found references to
master branch in these three, which I
use for various projects:
You will likely have
master mentioned in the
on: stanza of
workflows, and you may have it mentioned as the version of actions
themselves (in a
use: field). For the former, it’s a
straight-forward change to
main. For actions, the name may or may
not be under your control – either way, consider using a version tag
instead of referring to a branch. Here’s a commit with
both kinds of change.
It’s also possible you have
master branch explicitly mentioned in a
.circleci/config.yaml file, though less likely since the triggers
tend to work by excluding things. But, as for
kubeyaml, you might have ad-hoc tests in
snippets of script that determine whether to do something or not.
You may have a branch mentioned in a trigger clause, as I do for
[amqplib][amqp-travisci]; and, similarly,
master could be mentioned
in snippets of script.
Changing release artifacts
Some projects name release artifacts for the branch – for Flux we tag
prerelease container images as
master-<sha1>, for example. You’ll
need some co-ordination with people who use the artifacts, to let them
know to update any automated systems.