189 lines
7.2 KiB
Markdown
189 lines
7.2 KiB
Markdown
# 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.
|