Renaming master to main -- Julia-specific experience

For package maintainers considering renaming their default branch from master to main: I did it last month (Pluto.jl and PlutoUI.jl), and here are my Julia-specific experiences!

The main takeaway for me was: the rename was very easy, I was more worried about it than necessary!

GitHub already has multiple tools to make the transition easier, which is really helpful! I recommend renaming your branch using the github.com web interface.

GitHub in general

The full list of github features to support the rename is here, my highlights are:

  • Open pull requests will automatically get ‘redirected’ into main.
  • Contributors will see a helpful popup the next time they visit the repository.

Julia-specific experiences

  • :purple_heart: JuliaRegistrator will work seamlessly after the rename. (In fact, you can trigger @JuliaRegistrator on any commit, regardless of its branch.)

  • :purple_heart: TagBot will work seamlessly after the rename.

  • :purple_heart: Test actions will work seamlessly after the rename, unless the branch name master is ‘hardcoded’ in your .github/workflows/Test.yml file, simply edit the file to fix it.

  • :purple_heart: Old registered versions will continue to be available.

  • 🙋 Links inside code – I recommend searching your codebase for yourname/Package.jl/tree/master to find any links in comments or documentation that might need to be changed.

If you are using mybinder.org, then

Feel free to reply or contact me personally if I missed something in the list!

18 Likes

Updating your local clone

After renaming the default branch on github.com, you have to update your local clone to match these changes.

GitHub will give you the commands to type to do so, which look something like:

# don't copy me, get the instructions provided by github for your own repository
git branch -m master main
git fetch origin
git branch -u origin/main main

But as an even simpler solution, I recommend simply deleting the folder from your computer (after committing all your changes!), and then cloning again.

GitHub Desktop

If you’re like me, and you prefer not to use the git command line, here are the instructions for GitHub Desktop users:

  1. click Fetch,
  2. check out the main branch (you might need to search), bring over your changes if any
  3. restart github desktop for the default branch to get corrected

The master branch will still exist locally, you can clean it up like so:

  1. check out the master branch
  2. Go to Branch > Delete Branch > Cannot be undone – yes I am sure.

Again, you can also just delete the folder and clone again.

2 Likes

Can you please explain why one would do this?

1 Like

The word is overloaded with history, especially when it comes from a tradition of master/slave terminology. To me, I also find main to be a better word in the first place given how we use git.

5 Likes

I believe it will eventually be replaced as the default branch name on all new repositories. (I could be making that up though, can’t quite remember)

So could make sense to backport the change so that default branch is always main

It already has been! I made some new github repos recently and they all used main by default.

1 Like

Same for Gitlab and Bitbucket. Also many big tech companies are moving away from using master as the default branch name. It’s probably going to be an industry-wide change.

It seems likely that at some point the Julia project will have to consider this issue as well.

One thing related to this that recently bit me was when I wanted to use the latest version of DataFrames, and out of habit/muscle memory did add DataFrames#master, which worked, but installed an old version as the master branch was still around from before the switch.

Not sure whether this is always the best course of action but removing the master branch entirely would prevent this (in the DataFrames case I think there was a specific reason to keep that branch, so this might not always be possible).

5 Likes

Thanks, I knew about the master/slave issue, but wasn’t aware that master in itself is controversial.