Merge pull request CactuseSecurity#4219 from NilsPur/develop

Githooks for automated submodule synching

Author: tpurschke

.githooks/post-checkout

@@ -0,0 +1,2 @@
+#!/usr/bin/env bash
+"$(dirname "$0")/submodule-sync"

.githooks/post-merge

@@ -0,0 +1,2 @@
+#!/usr/bin/env bash
+"$(dirname "$0")/submodule-sync"

.githooks/post-rewrite

@@ -0,0 +1,2 @@
+#!/usr/bin/env bash
+"$(dirname "$0")/submodule-sync"

.githooks/submodule-sync

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Sync submodules quietly after common Git operations.
+
+# Resolve repository root; bail out if not inside a Git repo.
+repo_root="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+if [[ -z "${repo_root}" ]]; then
+  exit 0
+fi
+
+cd "${repo_root}"
+
+# No submodules configured.
+if [[ ! -f .gitmodules ]]; then
+  exit 0
+fi
+
+# No submodule paths registered in .gitmodules.
+if ! git config --file .gitmodules --get-regexp '^submodule\..*\.path$' >/dev/null 2>&1; then
+  exit 0
+fi
+
+# Disable prompts and keep this hook silent for users without repo access.
+export GIT_TERMINAL_PROMPT=0
+export GIT_ASKPASS=/bin/true
+export GIT_SSH_COMMAND="ssh -o BatchMode=yes"
+
+run_quiet() {
+  # Ignore failures to avoid blocking normal Git operations.
+  "$@" >/dev/null 2>&1 || true
+}
+
+# Initialize submodules first so each path exists.
+run_quiet git submodule update --init --recursive
+
+# Iterate configured submodules to ensure we are on a branch (not detached).
+while read -r key path; do
+  # Convert `submodule.<name>.path` -> `<name>`.
+  name="${key#submodule.}"
+  name="${name%.path}"
+
+  # Skip if the submodule path is missing or not initialized.
+  if [[ ! -d "${path}" ]]; then
+    continue
+  fi
+
+  # Skip if the path is not a Git repo.
+  if ! git -C "${path}" rev-parse --git-dir >/dev/null 2>&1; then
+    continue
+  fi
+
+  # Prefer repo-local submodule.<name>.branch, fallback to .gitmodules.
+  branch="$(git config --get "submodule.${name}.branch" || true)"
+  if [[ -z "${branch}" ]]; then
+    branch="$(git config --file .gitmodules --get "submodule.${name}.branch" || true)"
+  fi
+
+  if [[ -n "${branch}" ]]; then
+    # Try to checkout the branch if it already exists locally.
+    run_quiet git -C "${path}" checkout -q "${branch}"
+
+    # If still detached, create/reset the branch from origin.
+    if ! git -C "${path}" symbolic-ref -q HEAD >/dev/null 2>&1; then
+      run_quiet git -C "${path}" checkout -q -B "${branch}" "origin/${branch}"
+    fi
+  fi
+done < <(git config --file .gitmodules --get-regexp '^submodule\..*\.path$')
+
+# Move submodules to the newest commit on their tracking branch, merging instead of detaching.
+run_quiet git submodule update --remote --merge --recursive

.gitmodules

@@ -1,3 +1,4 @@
 [submodule "agents"]
 	path = agents
 	url = https://github.com/CactuseSecurity/firewall-orchestrator-agents
+	branch = main

documentation/developer-docs/git-howto.md

@@ -117,29 +117,41 @@ How to merge fork tpurschke/master into CactuseSecurity/master
 
         git push -u origin auth_frontend
 
-## Update submodules
+## Submodules
+IMPORTANT: Always commit to the submodule first, then commit to the FWO repo (superproject). This avoids the problem that the FWO repo does not point to the newest commit of the submodule (it cant - since it does not exist yet). An addtional commit to the FWO-repo will be necessary to fix this.
 
-### Initial update
-Update submodules to the commits recorded in the superproject (safe, reproducible). Initializes them if necessary.
-Execute this command after the initial clone of the fwo repo in the fwo repo root directory:
+### Automatic submodule sync via repo hooks
+Enable the repo-managed hooks once (per clone) to keep submodules up to date automatically:
+```shell
+git config core.hooksPath .githooks
+```
+The hooks run after `git pull`, `git checkout`, and `git rebase` and execute:
 ```shell
 git submodule update --init --recursive
+git submodule update --remote --merge --recursive
 ```
+Notes:
+- The hook is quiet if you do not have access to a submodule repository (no error output).
+- The hook checks out the configured submodule branch from `.gitmodules` before updating, to avoid detached HEAD.
+- This intentionally moves submodules to the newest commit on their configured branch, even if the superproject has not updated the pointer yet. Expect the submodule to appear "modified" in `git status`.
 
-## Update agents repo --> might be moved to githook later
+### Manual submodule operations
+If you like to manually execute the submodule setup, see the sections below. Otherwise, please refer to the section above.
 
-This updates the agents repo manually. Update submodules to the latest commit on their configured remote tracking branch. Execute this command to get the newest version of all submodules from their respective repositories.
+#### Initial update
+Update submodules to the commits recorded in the superproject (safe, reproducible). Initializes them if necessary.
+Execute this command after the initial clone of the fwo repo in the fwo repo root directory:
 ```shell
-git submodule update --remote --recursive
+git submodule update --init --recursive
 ```
-NB: This overwrites the agents repo data again with the one from the firewall-orchestrator repo! 
 
-## Configure to always pull recursively
-Permanent configuration change: make `git pull` recurse into submodules
+#### Update agents repo manually
+This updates the agents repo manually. Update submodules to the latest commit on their configured remote tracking branch. Execute this command to get the newest version of all submodules from their respective repositories.
 ```shell
-git config submodule.recurse true
+git submodule update --remote --merge --recursive
 ```
-## Check correct file state
+
+### Check correct file state
 ```shell
 tim@acantha24:~/dev/tim/fwo$ git ls-tree HEAD agents
 160000 commit 73cfbb4efad58dd569c0c0ab4d7ecebc63d23ddd  agents