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
- Contributors will see a helpful popup the next time they visit the repository.
JuliaRegistrator will work seamlessly after the rename. (In fact, you can trigger
@JuliaRegistrator on any commit, regardless of its branch.)
TagBot will work seamlessly after the rename.
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.
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
Feel free to reply or contact me personally if I missed something in the list!
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.
If you’re like me, and you prefer not to use the
git command line, here are the instructions for GitHub Desktop users:
- click Fetch,
- check out the
main branch (you might need to search), bring over your changes if any
- restart github desktop for the default branch to get corrected
master branch will still exist locally, you can clean it up like so:
- check out the
- Go to Branch > Delete Branch > Cannot be undone – yes I am sure.
Again, you can also just delete the folder and clone again.
Can you please explain why one would do this?
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.
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
It already has been! I made some new github repos recently and they all used
main by default.
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).
Thanks, I knew about the master/slave issue, but wasn’t aware that master in itself is controversial.