.. _sync-with-main:

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:

.. code-block:: bash

   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``:

.. code-block:: bash

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

Finish by bringing all submodules to their latest expected states:

.. code-block:: bash

   git submodule update --recursive

   
Troubleshooting
---------------

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

.. code-block:: bash

   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):

.. code-block:: bash

   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:

.. code-block:: bash

   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:

.. code-block:: bash

   cd  sources/oifs-43r3v2
   git checkout MyBranch

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

.. code-block:: bash

   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:
     
.. code-block:: bash

   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):

.. code-block:: bash

   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.