Renaming Rayleigh's default branch to 'main'


As some of you already know we decided to rename Rayleigh’s default development branch from master to main and made this change during the Rayleigh hackathon this week. We explained all the reasons for this change and the procedure in the presentation that is available here: Renaming Rayleigh's main branch - Google Slides.

Because this change will require a small effort from every user who cloned Rayleigh from our Github repository, I would like to repeat the instructions for how to make this change as painless and simple for everyone here. Again, the full presentation slides including all background and instructions are available here: Renaming Rayleigh's main branch - Google Slides.

The renaming requires 2 changes from every user of an Rayleigh git repository:

  1. Renaming the ‘master’ branch into ‘main’ on your Github fork of Rayleigh: You will receive a popup notification on Github the next time you visit your repository with instructions for how to do this. Alternatively instructions are provided here: Renaming a branch - GitHub Docs.
  2. Performing the same change inside every local clone of Rayleigh. General instructions are available here: Renaming a branch - GitHub Docs. But specifically, execute the following commands inside your git repository (assuming master is the current name of your default branch, and origin is the remote locations you want to set as the default remote for this branch):
git branch -m master main
git fetch origin
git branch -u origin/main main
git remote set-head origin -a

That’s it, you successfully renamed the branch. In future git commands simply replace every reference to master with main and all commands should work as before. If you encounter problems or some of these instructions are not clear, check the presentation linked above, or leave us a comment in this forum thread and we will be happy to help you out.

Rene on behalf of all maintainers

PS: If you do not know what all the git commands above are or mean, or you only download Rayleigh releases then there is nothing you need to do. Things will work as before.

Hi @gassmoeller et al., this worked fine for my Mac and Pleiades, but somehow not on the local cluster on JILA that I occasionally use. I think this is because the local cluster runs an old version of git? (1.7.1). Basically what happened is I ran

git branch -m master main
git fetch origin
git branch -u origin/main main
git remote set-head origin -a

on the local cluster, however the 3rd command didn’t work because the “-u” shortcut apparently didn’t exist in that version of git. So I replaced “-u” with “–set-upstream” and that seemed to work. However, now the local clone is stuck in a weird state where it still thinks “origin/master” is a thing. If I try to update the local “main” branch I get a bunch of warnings like the following:

warning: refname ‘HEAD’ is ambiguous.
warning: refname ‘HEAD’ is ambiguous.
warning: refname ‘HEAD’ is ambiguous.
remote: Enumerating objects: 698, done.
remote: Counting objects: 100% (413/413), done.
remote: Compressing objects: 100% (44/44), done.
remote: Total 698 (delta 379), reused 393 (delta 367), pack-reused 285
Receiving objects: 100% (698/698), 256.79 KiB, done.
Resolving deltas: 100% (475/475), completed with 42 local objects.

  • branch main → FETCH_HEAD
    warning: refname ‘HEAD’ is ambiguous.
    warning: refname ‘HEAD’ is ambiguous.
    First, rewinding head to replay your work on top of it…
    Fast-forwarded main to 8eed305e516045b0dd84d2e44fbb3c9d530502bd.
    warning: refname ‘HEAD’ is ambiguous.
    (custom) ~/rayleigh/code$ git st
    warning: refname ‘HEAD’ is ambiguous.
    warning: refname ‘HEAD’ is ambiguous

Also, the update seemed to bring the “main” branch further away from the perceived “master” branch. git branch -vv gives

HEAD 5e0bf78 [origin/master: ahead 434] Merge pull request #307 from tukss/fix_sphinx
custom_magnetic_energy c8d516b [origin/custom_magnetic_energy: ahead 2, behind 147] do not install sphinx via apt
exec_extension ac9fa1e [origin/exec_extension] Changed configure script to allow specification of executable extension as EXT=“.ext” ./configure
gtraceback 7c7860d [origin/gtraceback] Added the -g -traceback options to the default opt_flags for intel compilers in the configure script

  • main 8eed305 [origin/master: ahead 434] Merge pull request #404 from gassmoeller/improve_support
    multi_domain_interp 655ba27 [origin/multi_domain_interp] Thought I fixed bug in how abterms were assigned, but it looks like no…
    noB_in_RZ f169a16 [origin/noB_in_RZ: ahead 4, behind 215] made transition to 0 not abrupt
    origin/main 6e7427a [main: behind 242] Merge pull request #351 from tukss/update-version
    perfcond d9e5220 [origin/perfcond] do not install sphinx via apt
    read_one_part 3f92aad [origin/read_one_part: behind 3] checkpoint; something is broken in generic slice plotting
    remove_Diagnostics_Energy_Flux bcb6db3 [origin/remove_Diagnostics_Energy_Flux] removed deprecated Diagnostics_Energy_Flux.F90 from src/Diagnostics
    use_extreme_true ba613e8 [origin/use_extreme_true] Updated Diagnostics/Diagnostics_Interface.F90 to write basic grid information to binary file ‘grid_info’ and added routine ‘GridInfo’ to post_processing/ to read it.

Not sure how to fix this? Any suggestions are appreciated!


Hi Loren, thanks for posting. Did you execute the fourth command (set-head) after modifying and executing the third?

I am not quite sure what happened, but could you check the following things:
Does git remote update resolve the issue?
Can you post the output of git branch -a? Can you post the output of git remote -v?

Hi @gassmoeller, thanks for the reply!

Basically, I copied and pasted all four commands to run in succession (I know, I probably shouldn’t do that; but it worked for the others!) The output of the third command (git branch -u origin/main main) was thus in error because of the unknown “-u” option. Everything else seemed to work though as I recall (I didn’t save the output though from that first time around, unfortunately).

Then when I realized it was wrong, I’ve run through the final three commands a few times now.

git fetch origin [no output]

git branch --set-upstream origin/main main
output: Branch origin/main set up to track local branch main by rebasing.

git remote set-head origin -a
output: origin/HEAD set to main

but git status still yields:

warning: refname ‘HEAD’ is ambiguous.

warning: refname ‘HEAD’ is ambiguous.

On branch main

Your branch is ahead of ‘origin/master’ by 434 commits.

nothing to commit (working directory clean)

I just tried

git remote update

seems to work. Output: Fetching origin

But git status still yields the detached HEAD state.

Output of git branch -a:


  • main
    remotes/origin/HEAD → origin/main

Output of git remote -v:

origin (fetch)
origin (push)

I need to go through and see if any of those local branches have work that I need; but if not, I can just remove the whole thing and clone from scratch (or save the broken repo somewhere else).

Hi Loren, sorry for the delay. I think there may be two unrelated problems here. First is that your git did not notice that origin/master no longer exists (I checked on your github it actually does not exist anymore). Your local git should notice that when you run a git remote update -p.
Second: It looks like you have a local branch that is called HEAD. This should not happen, HEAD is an internal marker that git sets to the default branch that is currently checked out. In newer versions of git it is impossible to create a branch of this name, but in older versions it was easy to create one by accident (e.g. running git checkout -b HEAD instead of git checkout HEAD could accidentally create one). This also looks to give exactly the warnings that you describe according to this stackoverflow discussion: Our git repository has a branch called HEAD - Stack Overflow.
Could you try running git branch -D HEAD and see if it removes the extra branch and the warnings?

Hi @gassmoeller, sorry it took me forever to respond! I went ahead and archived the old local repo and instead installed a new version. There were no branches on the local version I needed anyway. If I end up facing similar issues, I’ll be sure to bring them up again.