# KiCad → git submodule + Gitea mirror — migration record & runbook

**Date:** 2026-08-27 · **Status:** local side DONE, pushes pending (need network + credentials)

---

## 1. What was done

`03-Architecture-Hardware/kicad` is no longer tracked file-by-file in
`project-drogheda`. It is now a **standalone git repository**, referenced from the
parent as a submodule.

| Item | Value |
|---|---|
| Submodule path | `03-Architecture-Hardware/kicad` |
| Submodule name | `kicad` |
| Canonical remote (`origin`) | `git@github.com:lrodriguez15/hbox-kicad.git` |
| Mirror remote (`helgen`) | `ssh://git@git.helgen.online:222/Helgen-Services/HBox_PCB.git` |
| Submodule branch | `main`, **72 commits**, HEAD `4bf41c6` |
| Parent commit | `5bb2e12` — "kicad → submodule (hbox-kicad)" |
| Rollback tag (parent) | `pre-kicad-submodule-2026-08-26` → `daafd5c` |

**History was preserved.** The 71 board commits were extracted with
`git subtree split --prefix=03-Architecture-Hardware/kicad`, so blame and bisect
still work on the schematic and PCB. Commit **hashes differ** from the parent's
(subtree split rewrites them); messages, authors and dates are identical.

Verified: every file that existed under `kicad/` at `daafd5c` is byte-identical
in the submodule (blob-hash comparison, 309/309 files). `git fsck
--connectivity-only` on the new repo is clean.

### Deliberate content changes (1 commit on top of the split)

- **added** `.gitignore` — KiCad `.kicad_prl`, `*.lck`, `*.T*bak` agent scratch
  backups, `.history/`, `.mcp-backups/`, `_to_delete/`, `*_drc_violations.json`,
  `*.log`, `snapshots/`, Office lock files
- **added** `README.md` — layout, remotes, history note
- **untracked** `hbox-watchdog-v3.kicad_prl` (per-user KiCad UI state)
- **untracked** `~hbox-watchdog-v5.kicad_pro.lck` (KiCad session lock, already
  deleted on disk)

### Not done, on purpose

- **Parent history was not rewritten.** Its `.git` stays ~239 MB because the old
  kicad blobs are still in it. Nothing force-pushed, no clone broken. The parent
  simply stops growing from here on. If you ever want it slim, that is a separate
  `git filter-repo` + force-push job.
- Branch `kicad-split` still exists in the parent as the split's output. Delete it
  once the push succeeds: `git branch -D kicad-split`.

---

## 2. What you still have to do

### Step 1 — create the GitHub repo and push the submodule

```bash
cd ~/Documents/Claude/Projects/Drogheda/03-Architecture-Hardware/kicad

# create it (private) — or make it in the web UI as lrodriguez15/hbox-kicad
gh repo create lrodriguez15/hbox-kicad --private

git push -u origin main
```

~240 MB on the first push, mostly the STL/STEP mechanical exports. Expect a few
minutes.

### Step 2 — push the parent

```bash
cd ~/Documents/Claude/Projects/Drogheda
git push origin main
git push origin pre-kicad-submodule-2026-08-26   # rollback tag
git branch -D kicad-split                        # split scaffolding, no longer needed
```

Push the submodule **first**. A parent commit whose gitlink points at a commit
nobody can fetch will break every clone.

### Step 3 — set up the Gitea pull mirror

Gitea can only make a repo a *pull* mirror **at migration time** — it cannot be
switched on for a repo that already exists. `Helgen-Services/HBox_PCB` is
currently empty, so:

1. Gitea → `Helgen-Services/HBox_PCB` → **Settings → Danger Zone → Delete**.
2. **+ → New Migration → GitHub**.
   - Clone URL: `https://github.com/lrodriguez15/hbox-kicad.git`
   - Auth: your GitHub username + a **classic PAT with `repo` scope**
     (required — the GitHub repo is private)
   - Owner: `Helgen-Services` · Repository name: `HBox_PCB`
   - ✅ **This repository will be a mirror**
3. After migration: **Settings → Mirror Settings** → set the interval (default is
   `8h`; `1h` is reasonable) and use **Synchronize Now** to test.

You push only to GitHub; Gitea follows on its own. **This needs no SSH key** —
the mirror pulls over HTTPS with the PAT, which is why it is the low-friction
option while your SSH credentials are still pending.

If you would rather keep the existing `HBox_PCB` repo as-is, the fallback is a
local dual push instead of a server-side mirror:

```bash
cd .../kicad
git remote set-url --add --push origin git@github.com:lrodriguez15/hbox-kicad.git
git remote set-url --add --push origin ssh://git@git.helgen.online:222/Helgen-Services/HBox_PCB.git
# now `git push origin main` hits both — but both must be reachable, every time
```

### Step 4 — SSH to Gitea (only if you want to push there directly)

```bash
ssh-keygen -t ed25519 -C "leo@helgen.tech" -f ~/.ssh/id_ed25519_helgen
pbcopy < ~/.ssh/id_ed25519_helgen.pub    # paste into Gitea → Settings → SSH/GPG Keys

cat >> ~/.ssh/config <<'EOF'
Host git.helgen.online
  HostName git.helgen.online
  Port 222
  User git
  IdentityFile ~/.ssh/id_ed25519_helgen
EOF

ssh -T git@git.helgen.online -p 222     # expect a Gitea greeting
```

The `helgen` remote is already configured in the submodule, so after this
`git push helgen main` works. **Do not** push to Gitea if you set it up as a pull
mirror in Step 3 — a mirror is read-only and force-overwrites local pushes on the
next sync.

---

## 3. Day-to-day workflow from now on

Board work is committed **inside** the submodule, then the parent is told which
commit to point at:

```bash
cd .../Drogheda/03-Architecture-Hardware/kicad
git add hbox-watchdog-v6.kicad_sch hbox-watchdog-v6.kicad_pcb
git commit -m "v6 T5: LTC4040 errata + U7 delete"
git push                                   # → GitHub, Gitea follows

cd ../..                                   # parent repo
git add 03-Architecture-Hardware/kicad     # stages the new gitlink
git commit -m "kicad: v6 T5"
git push
```

Forgetting the second half is the classic submodule trap: the board work is safe
on GitHub, but the parent still points at the old commit.

### Cloning fresh

```bash
git clone --recurse-submodules git@github.com:lrodriguez15/project-drogheda.git
# already cloned without it:
git submodule update --init --recursive
```

Anyone who only has Gitea access can redirect the submodule locally without
editing `.gitmodules`:

```bash
git config --global url."ssh://git@git.helgen.online:222/Helgen-Services/HBox_PCB.git".insteadOf \
  "git@github.com:lrodriguez15/hbox-kicad.git"
```

For a fast, board-files-only checkout: `git clone --filter=blob:none` skips the
historical STL/STEP blobs until something actually needs them.

---

## 4. Open items / observations

- **`~hbox-watchdog-v6.kicad_pro` was modified while this ran** — KiCad is (or
  was) open on the v6 project. `hbox-watchdog-v6.kicad_pro` shows as modified in
  the submodule; commit or discard it as you see fit.
- **Your other three submodules point at `ssh://git.helgen.dev:6611/…`**
  (`hbox-firmware`, `htracker`, `hbox-log-tools`) and are currently uninitialised.
  If `.dev:6611` has been superseded by `git.helgen.online:222`, those URLs need
  updating too — say the word and I'll do it in one pass.
- **This VM has no network access**, which is why every push above is left for
  you to run. Everything that could be done offline is done.
- `_to_delete/` folders under `03-Architecture-Hardware/` and `kicad/` hold git
  lock/temp files that the sandbox was not permitted to unlink. Safe to delete.