Submodule and explorer remote hygiene

Last Updated: 2026-03-27
Purpose: Operational notes for the many git submodules under the proxmox parent repo: detached HEAD, remotes, pushes, and non-secret JSON env snapshots.

Detached HEAD is normal

The parent records each submodule at a specific commit. After git submodule update --init --recursive, many submodules show HEAD (no branch). That is expected for read-only use.

If you develop inside a submodule: check out a named branch first (for example main or master), commit, push that submodule’s remote, then in the parent repo commit the updated submodule pointer and push the parent.

Workflow (short):

cd <submodule> → git checkout main (or the project default)
Make changes → git commit → git push <remote> <branch>
cd .. (parent root) → git add <submodule-path> → git commit → git push

Verify clean submodule trees

From repo root:

bash scripts/verify/submodules-clean.sh

Stricter than git status -sb (fails on any porcelain output). Use after large merges or before release tagging.

explorer-monorepo: Gitea primary, GitHub optional mirror

Parent .gitmodules URL: https://gitea.d-bis.org/d-bis/explorer-monorepo.git (primary clone and integration source).
Primary pushes should go to Gitea (origin or gitea remote → https://gitea.d-bis.org/d-bis/explorer-monorepo.git).
GitHub is optional as a mirror only when that repository exists and your team still needs it.

If git push to a GitHub mirror returns repository not found, treat that as a mirror problem, not the primary integration path. Continue using Gitea as the source of truth until a valid GitHub mirror URL is confirmed.

Do not store credentials in remote URLs. Use SSH (git@github.com:...) or HTTPS with a credential helper. If you see a remote whose name or URL embeds a token, remove it and re-add a clean remote:

cd explorer-monorepo
git remote -v
# git remote remove '<bad-remote-name>'
git remote add origin https://gitea.d-bis.org/d-bis/explorer-monorepo.git

Rotate any token that was ever embedded in a saved URL.

gru-docs branch

gru-docs may track docs-review-fixes (not main) while documentation review is open. The parent submodule pointer is intentional until upstream merges to main and the pointer is updated.

metamask-integration upstream

This clone may show main...gitea/main when Gitea is the configured origin or tracking remote. Confirm with your team whether GitHub (see .gitmodules) or Gitea is canonical for pushes; align branch.<name>.remote if both exist.

JSON reference files (dotenv cleanup)

In smom-dbis-138/config/ and explorer-monorepo/config/, files such as address-inventory*.json and runtime-env*.json are non-secret reference snapshots. They are not a substitute for .env for secrets. When on-chain or deployment addresses change, update the canonical docs (docs/11-references/ADDRESS_MATRIX_AND_STATUS.md, etc.) and refresh these JSON files if you rely on them for scripts.

See each submodule’s config/README.md for a short in-tree note.

AGENTS.md — quick pointers including submodule discipline
CONTRIBUTOR_GUIDELINES.md — submodule section for contributors
ADDRESS_MATRIX_AND_STATUS.md — contract address source of truth
.cursor/rules/chain138-tokens-and-pmm.mdc — agent overlay; must stay aligned with the address matrix

3.6 KiB Raw Blame History Unescape Escape