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

```bash
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.

---

## atomic-swap-dapp bootstrap remote

`atomic-swap-dapp` was scaffolded first as a standalone local repository and then mounted into the parent as a submodule. Its current `.gitmodules` URL may point at a local bare repository during bootstrap.

That is acceptable for initial local development, but before other operators rely on the parent repo for cloning, replace the local URL with the canonical hosted remote and then commit the updated `.gitmodules` plus submodule pointer.

See [ATOMIC_SWAP_DAPP_SUBMODULE.md](../03-deployment/ATOMIC_SWAP_DAPP_SUBMODULE.md) for the submodule purpose and manifest-sync workflow.

---

## 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](../../AGENTS.md)** — quick pointers including submodule discipline  
- **[CONTRIBUTOR_GUIDELINES.md](CONTRIBUTOR_GUIDELINES.md)** — submodule section for contributors  
- **[ADDRESS_MATRIX_AND_STATUS.md](../11-references/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