Skip to content

GitHub Branch Renaming

Jump to bottom
E. Lynette Rayle edited this page Apr 1, 2022 · 1 revision

Overview

Similar to other community efforts, we are exploring the impact of renaming master branches to main. This addresses one aspect of the use terms that may present barriers to participation. We want to create a welcoming environment that unholds the value of all community members.

This documentation builds on work done by the Samvera Community in the Samvera Branch Renaming Working Group to identify challenges and approaches for the renaming process.

Renaming Process

References:

Considerations before renaming:

You will want to contact all contributors to notify them that the change will occur. There are steps they will need to take to update their local clones (required) or forks (optional).

At this writing, there isn't a good way to prevent users from recreating the master branch. GitHub suggested a workaround that involved creating a master branch with no history or files, but doing so prevented the auto-forwarding of URLs with master branch as the path to the same URL with main branch as the path. This can break links in Issues, PRs, wikis, and documentation. It is recommended that the master branch not be re-used to allow the auto-forwarding to work. If you have a lot of contributors, you may want to consider whether this will pose a risk to your repo. A request has been made to GitHub to support blocking of branch names using branch rules. The request is pending at the time of this writing.

Change the name in GitHub:

  • navigate to the repo being renamed in GitHub
  • click branches dropdown and select View all branches at the bottom of the dropdown
  • click pencil icon beside master branch
  • set name to main

Update localhost clones:

git branch -m master main
git fetch origin
git branch -u origin/main main

Impact on forks:

  • When visiting the fork repo in GitHub, a message is displayed that indicates the master branch in the fork is up to date with the main branch in the source repo. This branch is even with _SOURCE_REPO_:main.
  • When a PR is created in the fork, the master branch in the fork will automatically be set to merge into the main branch in the source repo. The user would have to take action to change this.
  • Forks can rename their master branch to main following the same procedure.
  • You may want to notify fork developer of the rename so they understand the change has occurred and the impact on their work.
Clone this wiki locally