Change default branch name from master to main

Summary

We have decided in the developer meeting 2022 to switch the default branch name from master to main, but only if the effort is reasonable. This issue collects the necessary steps and procedures to do such a transition.

We are in no rush and thus can prepare and discuss this transition before taking any steps.

Reasons for Renaming?

The default branch name in GitLab and GitHub has changed to main.
Whenever you create a new project, the instructions tell you to create a main branch.
The online Git introductions start to change to main.
In teaching we are using main as the default branch.
Git has started to make main the new default branch.
The name master branch might be deprecated/removed as default branch name from git in the future.
Some projects already use main and thus we have mixed names, resulting in some complications, e.g., with dunecontrol git checkout master.
The original reasoning can be summarized, see, e.g., Why-GitHub-renamed-its-master-branch-to-main or Software freedom conservancy

Note, a project is not required to make this change. It is a project-wise decision. We might do this change for all core/staging/extensions modules at once. The steps illustrated below should be provided as scripts. With a little effort, we can make this process (nearly) completely automatic.

How to rename `master` branch to `main`?

Each repository has to do the following steps:

git checkout master (checkout the current master, maybe followed by git pull to be up-to-date)
git branch -m master main (create a new main branch locally, taking the history of master)
git push -u origin main (push the new local main branch to the remote repo)
git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/main (switch the current HEAD to the main branch)
In GitLab -> Project Settings -> Repository -> Default branch, choose main
In GitLab -> Project Settings -> Repository -> Protected branches, protect the new main branch similar to the old master branch
unprotect the master branch
git push origin --delete master (delete the master branch on the remote)

What does the user need to do?

In order to update local repositories, all users need to do the following steps:

git checkout master (Switch to the master branch)
git branch -m master main (create a new main branch locally, taking the history of master)
git fetch (Get the latest commits (and branches!) from the remote)
git branch --unset-upstream (Remove the existing tracking connection with origin/master)
git branch -u origin/main (Create a new tracking connection with the new origin/main branch)
git config --global init.defaultBranch main

What else need to be updated?

All merge-requests with target branch master need to be set to main
In .gitlab-ci.yml includes of other projects .yml files with branch reference must be updated
Any reference to a specific master branch, e.g., in installation instructions and other git howto's must be updated.
Maybe external repository mirrors? This could be fine.

I think, step 1 can be scripted using the Gitlab-API, tested already in an example repo. If all .gitlab-ci.yml files are written in a similar style, the second step could also be scripted. Alternatively, we do not delete the master branch in the config-ci repository right away, to allow a slow transition. For step 3 we need to inspect our docs. Not sure how many of such references exist.

Possible issues?

If local git installation is older than 2.28 one cannot easily set a default branch for new projects, because master is somewhere hard coded in the templates. There are workaround, see e.g. superuser.com
Hard coded references to files in the master branch git directory are hard to spot. Maybe a grep over all repositories can help
I'm not sure whether it is a good idea to have for a transition period both, master and main. But maybe it is possible, at least for the download. We should search for a way to have the master branch be synchronized with the main in this case.

Edited Mar 05, 2022 by Simon Praetorius