Synchronizing your branch with main

Save your work first

Before you can get the latest fixes and features that are in the main branches, you must put aside your uncommitted work. You can either commit your changes to your branch, or you can stash them. Note that untracked files are not a problem and do not have to be committed or stashed.

Do this in all the repositories with uncommitted work, superproject and/or submodule(s).

Fetch the remotes

We first fetch submodules and superproject updates from all accounted forks. This is done from within the ec-earth4 superproject:

cd ecearth4
git submodule foreach --recursive git fetch --all
git fetch --all

Then we bring either our main superproject branch, or the branch we were developing if any, up to date with the stable upstream/main:

git checkout main  # or: git checkout MyBranch
git rebase upstream/main

Finish by bringing all submodules to their latest expected states:

git submodule update --recursive

Troubleshooting

If you forgot to commit or stash your work before the last command, you may get an error like:

Submodule path 'sources/nemo-4.2': checked out '6b79e5caef1558b25d1ee9d8d96aaf3b6e407974'
error: Your local changes to the following files would be overwritten by checkout:
    src/ifs/setup/su0phy.F90
Please commit your changes or stash them before you switch branches.
Aborting
Unable to checkout '83d99b6953c44783dd58aa8e2f7dda67cdd6c784' in submodule path 'sources/oifs-43r3v2'

You can see that NEMO was correctly updated, but not OpenIFS because I did not save my changes in the src/ifs/setup/su0phy.F90 file.

To resolve this problem, just navigate to the OpenIFS code and stash your work (or add and commit to your branch):

cd sources/oifs-43r3v2
git stash push -m "Work in progress"

You have then two possibilities. You can bring your branch up to date with its upstream/main right away (see next section), or you can bring OpenIFS to a clean state. For the latter, just return to the ec-earth4 superproject, and update again the submodules:

cd -
git submodule update --recursive

Resuming your development work

Let say you were developing a new feature in your MyBranch branch in OpenIFS, which started from upstream/main. You can simply checkout the branch:

cd  sources/oifs-43r3v2
git checkout MyBranch

The output of the last command will indicate if there are updates to get from upstream/main:

Previous HEAD position was 83d99b6 Fix A_Evap_Ice bug (wrong multiplication by ice frac)
Switched to branch 'MyBranch'
Your branch is behind 'upstream/main' by 2 commits, and can be fast-forwarded.
(use "git pull" to update your local branch)

If there is any (2 in this example), you should bring them into your branch:

git rebase upstream/main
#
# or if you share your branch with others:
#
git merge upstream/main

If you have stashed some changes, you can get them back into your work copy with (assuming the last stash is the correct one):

git stash pop stash@{0}

You need to check out your development branch and/or apply your stashed work in all the superproject and/or submodules that you modify.