GitHub/Changing Default Branch

There are many good reasons to rename the default branch for your repository. GitHub gives some of the reasons and provides guidance for the procedure.

However, if your repository has been in use for a while, everyone who has clones of the repository must update their clones to properly reflect the change. GitHub will add messages to the output of git commands to inform folks, but it is very easy to miss those. If the per-clone changes are not made, then the branch could accidentally be re-created with old contents. The procedure below provides a workaround, which can be enabled by a repository admin.

1. Rename the default branch, following GitHub's instructions.

2. Create a branch protection rule for the old branch name (instructions). Make sure the following checks are enabled:

• Require pull request reviews before merging - any number is fine
• Require status checks before merging
• Include administrators

3. Unfortunately, that branch protection rule doesn't apply until the 2nd commit to the old branch name. So make an unrelated first commit:

       mkdir /tmp/rename
       cd /tmp/rename
       touch do_not_use_this_branch_name
       echo "Do not use this branch name!" > README.md
       git init
       git add --all
       git commit -m "Block commits to this branch name on GitHub"
       git push git@github.com:$OWNER/$REPOSITORY HEAD:refs/heads/$OLD_BRANCH_NAME

4. Review any CI configurations that may refer to the old branch name, and update as needed.