Working with RDASApp submodules

The RDASApp includes many JEDI components through submodules. This is good for a recursive git clone and we can easily navigate to corresponding component repositories on the GitHub code page by clicking links. However, this poses a problem that each "git status" or "git add" command will recursively traverse all submodules to find new changes and it greatly slow the responses of git operations, leaving an unpleasant user experiences.

Per the RDASApp policy, code changes in submodules should be committed to its own repository directly and the RDASApp only needs to point to a correct commit hash. Hence ignore=all is added for all submodules (see issue #104 and PR#105) to speedup all git operations under the RDASApp repository.

Under this context, users will not be able to see the submodule changes when running git status in RDASApp, but users can still stage (git add) and commit if a submodule HEAD changes. Here are several quick useful commands/tips when dealing with RDASApp submodules:

1. check the submodule hashes in the submodule HEAD (e.g. the HEAD commit under sorc/ufo/ as if you run git status there):
   git submodule status sorc/ufo

2. check the submodule hashes in the current RDASApp HEAD (e.g: the recorded hash in the RDASApp for the submodule sorc/ufo)
   git ls-tree HEAD sorc/ufo

You may replace sorc/ufo with other submodules, such as sorc/mpas, sorc/saber, etc.

If hash1 and hash2 are different, it means the submodule has been checkout to a commit other than what is recorded in the RDASApp HEAD. Usually, git will display a "+" sign before the output from git submodule status to remind that submodules has been changed, e.g.:

[Jet|fe4 RDASApp]$ git ls-tree HEAD sorc/ufo
160000 commit 54b44b22291a90955c3eb5327ed24ea9e858d4f6  sorc/ufo

[Jet|fe4 RDASApp]$ git submodule status sorc/ufo
+b7acb2e6969db21d5ac07f68b10d451c88c8b2eb sorc/ufo (1.9.0-30-gb7acb2e6)

3. update a submodule hash (using sorc/ufo as an example):

cd sorc/ufo
git checkout my_target_hash #a branch, tag or commit
cd ../..
git add sorc/ufo
git commit -m "update sorc/ufo to hash XXXXX"
git push

4. check local submodule status and revert any submodule changes:

git submodule status

An example output:

+ea390a0c902f499ce68d0fc380c1def10962a14d sorc/MPAS-Model (hfip_2024-14-gea390a0c9)   
+0af95df93aaadccb7a1432fc87f3f3aa537d0069 sorc/MPASSIT (heads/master-rrfsx)           
 1bdd90ea66b52ba710bef3d8fadc74b4d65c22b9 sorc/RDASApp (heads/develop)                
+fb6a965a33be6aba21a1b612d26a93ead934542d sorc/UPP (upp_v10.2.0-223-gfb6a965a)        
 335c76a111f84503e8b963abaf273ea8053645bb sorc/WPS (v4.6.0)

So we know three submodules were changed in the local copy. We can run the following command to revert any changes:

git submodule update --recursive sorc/MPAS-MODEL
git submodule update --recursive sorc/UPP
git submodule update --recursive sorc/MPASSIT

If we get errors similar as follows:

fatal: transport 'file' not allowed        
fatal: Fetched in submodule path 'sorc/MPASSIT', but it did not contain a1859eb4948fe363b4db311a1d27af24a7b4e964. Direct fetching of that commit failed. 

It usually means that the remote URL for this submodule in the local copy is different from the current repository HEAD. The solution is to modify the file .git/modules/sorc/MPASSIT/config and update the URL in the [remote "origin"] section.
Another possibility is that the branch names, for example, in .git/modules/sorc/iodaconv/config, no longer exist in the given remote. Removing that part will help. For example, removing the following 3 lines solved a "failed" fetch error:

[branch "fix_bufr2ioda"]
        remote = gge
        merge = refs/heads/fix_bufr2ioda