KiCad git tests

KiCad-git-tests

A scratch project for learning how to use git with KiCad. The board itself is throwaway; the point is the workflow around it.

Everything below was worked out while setting this repo up, including the mistakes — those are recorded at the bottom so they don't get repeated.

1. What belongs in git, and what doesn't

KiCad's real design files are text s-expressions, which git handles well. KiCad also scatters caches, locks and binary backups through the project directory, which git handles badly. The whole discipline is keeping the second group out.

Tracked

Ignored (see .gitignore)

The rule of thumb: if KiCad can regenerate it, don't commit it. The exception worth considering is fabrication output for a revision you actually ordered — some people commit those deliberately, tagged, as a record of what was built.

.gitattributes marks the KiCad formats as text with LF endings so git never misdetects one as binary and refuses to diff it, and marks zips and STEP files as genuinely binary.

Enforced, not just ignored

.gitignore only stops an accidental git add .. A git add -f or a Git GUI can still commit these files, so there are two checks on top of it. Both use the same rules, in .github/scripts/check-repo-files.sh:

• On pull requests into main, .github/workflows/repo-hygiene.yml runs the Repo file check. It fails if the PR adds a blocked file. For fabrication output it passes, but posts a PR comment asking the reviewer to confirm the files were committed on purpose. Deleting a bad file never trips the check.

• Locally, .githooks/pre-commit refuses the commit for blocked files and prints a warning for fab output. Turn it on once per clone:

  git config core.hooksPath .githooks

  To skip it once, on purpose: git commit --no-verify.

If a blocked file does get in, remove it from git and keep your local copy with git rm --cached -- <file>, then commit.

One-time GitHub setup: in Settings → Rules → Rulesets (or Settings → Branches), require pull requests for main and add Repo file check as a required status check. Without that, a PR with a failing check can still be merged, and direct pushes to main skip the check entirely.

2. Three habits specific to KiCad

Close KiCad — or at least save — before committing

KiCad holds edits in memory and writes on save. Committing mid-edit captures a half-state that doesn't match what's on your screen. Closing also clears the lock file.

Commit the schematic and the layout together

.kicad_sch and .kicad_pcb share net and footprint identity. A commit with a schematic change but no corresponding layout update is a broken state you cannot cleanly return to. One logical change = one commit spanning both files.

Do not expect merges to work on .kicad_pcb

This is the big one, and it surprises anyone arriving from software git.

Because the files are text, git will happily merge two divergent layouts — and can produce a syntactically valid file with nonsense geometry: overlapping footprints, traces to nowhere, silently dropped zones. That is strictly worse than a conflict, because nothing warns you.

So:

• Branch freely for schematic experiments.
• Keep layout work linear — one person, one branch at a time.
• If layout diverges, redo it rather than merging it.

Version control here is excellent for history, review and rollback. It is not reliable for parallel layout editing.

3. Everyday workflow

# after saving and closing KiCad
git status                 # confirm only design files changed
git diff                   # review — kicad files are readable text
git add -A
git commit -m "Add 3V3 regulator and decoupling"
git push

Tag revisions you actually send to fabrication:

git tag -a rev-a -m "Sent to JLCPCB 2026-09-12"
git push --tags

A tag is what makes "which files did we build?" answerable a year later.

4. How this repo was set up

cd ~/KiCad/projects/KiCad-git-tests
git init
git branch -m master main                      # match GitHub's default
# ... create .gitignore and .gitattributes ...
git add .
git commit -m "Initial commit"
git remote add origin git@github.com:Alex-Hermeling/KiCad-git-tests.git
git push -u origin main

5. Automated previews and visual diffs (GitHub Actions + KiBot)

Each open PR gets its own page at https://alex-hermeling.github.io/KiCad-git-tests/pr-<number>/. The sites are stored on the pr-diffs branch and removed automatically when the PR is closed. The site root lists the open PRs.

KiBot settings live in .kibot/config.yml (previews) and .kibot/config_diff.yml (diff).

Latest render of main

The images below come from the previews branch, which the export workflow overwrites on every run. They appear after the first run.

Schematic (PDF)

PCB

Top	Bottom