From 200bd46923f0c069dc09a3e46e5e73ced4991e5d Mon Sep 17 00:00:00 2001
From: Joshua Henderson <hendjoshsr71@gmail.com>
Date: Tue, 16 Jan 2024 01:12:10 -0500
Subject: [PATCH 1/2] Tools :  completion add submoduleclean &
 submodule_force_clean

---
 Tools/completion/bash/_waf | 2 ++
 Tools/completion/zsh/_waf  | 4 +++-
 2 files changed, 5 insertions(+), 1 deletion(-)

diff --git a/Tools/completion/bash/_waf b/Tools/completion/bash/_waf
index 5eb71bd2e76cd..a62a4a12510c6 100755
--- a/Tools/completion/bash/_waf
+++ b/Tools/completion/bash/_waf
@@ -31,6 +31,8 @@ _waf()
     opts+=" configure"
     opts+=" clean"
     opts+=" distclean"
+    opts+=" submodule_force_clean"
+    opts+=" submodulesync"
 
     # Prevent word reuse TODO: add -vvv case
     lim=$((COMP_CWORD - 1))
diff --git a/Tools/completion/zsh/_waf b/Tools/completion/zsh/_waf
index e2d0ce6d632cb..4b70537d005ba 100644
--- a/Tools/completion/zsh/_waf
+++ b/Tools/completion/zsh/_waf
@@ -89,7 +89,9 @@ _waf_cmds() {
     'build:executes the build' \
     'configure:configures the project' \
     'clean:cleans the project' \
-    'distclean:removes build folders and data'
+    'distclean:removes build folders and data' \
+    'submodule_force_clean:removes all submodules, then checkouts all current submodules and synchronizes them' \
+    'submodulesync:checkouts all current submodules and synchronizes them'
   )
   _describe -t commands 'command' commands "$@" && ret=0
 }

From c5b421b6ff1a9779d7eb9221ccd90e41c3d9e627 Mon Sep 17 00:00:00 2001
From: Joshua Henderson <hendjoshsr71@gmail.com>
Date: Tue, 16 Jan 2024 01:17:00 -0500
Subject: [PATCH 2/2] waf : wscript add submoduleclean & submodule_force_clean

---
 BUILD.md |  5 +++++
 wscript  | 23 +++++++++++++++++++++++
 2 files changed, 28 insertions(+)

diff --git a/BUILD.md b/BUILD.md
index ae32c0a9107e7..5e11d2c83808e 100644
--- a/BUILD.md
+++ b/BUILD.md
@@ -102,6 +102,11 @@ list some basic and more used commands as example.
     Cleaning the build is very often not necessary and discouraged. We do
     incremental builds reducing the build time by orders of magnitude.
 
+    If submodules are failing to be synchronized, `submodulesync` may be used
+    to resync the submodules. This is usually necessary when shifting development
+    between stable releases or a stable release and the master branch.
+
+    In some some cases `submodule_force_clean` may be necessary. This removes all submodules and then performs a `submodulesync`. (Note whitelisted modules like esp_idf is not removed.)
 
 * **Upload or install**
 
diff --git a/wscript b/wscript
index 8d2c2a68b2b29..c21a031e52f92 100644
--- a/wscript
+++ b/wscript
@@ -86,6 +86,29 @@ def _set_build_context_variant(board):
             continue
         c.variant = board
 
+# Remove all submodules and then sync
+@conf
+def submodule_force_clean(ctx):
+    whitelist = {
+                            'COLCON_IGNORE',
+                            'esp_idf',
+                          }
+
+    # Get all items in the modules folder
+    module_list = os.scandir('modules')
+
+    # Delete all directories except those in the whitelist
+    for module in module_list:
+        if (module.is_dir()) and (module.name not in whitelist):
+            shutil.rmtree(module)
+
+    submodulesync(ctx)
+
+# run Tools/gittools/submodule-sync.sh to sync submodules
+@conf
+def submodulesync(ctx):
+    subprocess.call(['Tools/gittools/submodule-sync.sh'])
+
 def init(ctx):
     # Generate Task List, so that VS Code extension can keep track
     # of changes to possible build targets