proxmox/docs/00-meta/SUBMODULE_HYGIENE.md

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

1. cd <submodule> → git checkout main (or the project default)
2. Make changes → git commit → git push <remote> <branch>
3. 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.

Surgical artifact cleanup (generated files only)

Some submodules historically tracked build output (TypeScript .js next to .ts under packages/*/src, Foundry artifacts/, root metamask-integration/dist/ from tsc, or miracles_in_motion/api/deploy-package/ copies of api/dist). That noise is removed with gitignore + git rm --cached, not by discarding real source edits.

• Repeatable helper (idempotent): bash scripts/maintenance/surgical-clean-submodule-artifacts.sh [--dry-run]
• After it reports changes, commit inside the submodule, then bump the parent submodule pointer.

---

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.

---

Related

• 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