Revisions & change control
Git and KiCad: What to Put in the Repository
Commit sources, generate everything else — plus the release exception, what Git genuinely gives hardware, what it cannot do, and where the boundary falls.
KiCad stores its schematics and boards as text. Git versions text well. So putting a KiCad project in Git is a sensible thing to do, and plenty of teams do it successfully.
The question worth spending time on is not whether to use Git. It is what to put in it, because the difference between a repository that helps and one that becomes a 4 GB liability is almost entirely a decision about contents.
What belongs in the repository
The rule is the same one that governs any build system: commit sources, generate everything else.
| Commit | Why |
|---|---|
*.kicad_sch, *.kicad_pcb, *.kicad_pro | The design. Text, diffable, irreplaceable |
*.kicad_sym, *.kicad_mod — project libraries | The design depends on them |
*.kicad_dru, design rules | Part of the design intent |
fp-lib-table, sym-lib-table | Without them the project opens wrong |
| Scripts that produce outputs | The build process is part of the source |
| README, design notes, decisions | Text, small, and the most valuable file in there |
| Do not commit | Why |
|---|---|
*-backups/, *.kicad_prl, *.bak | Local state and autosaves |
*.net | Generated from the schematic |
| Fabrication outputs, in day-to-day work | Generated; large; churn on every export |
| 3D model libraries | Large binaries that rarely change |
| Anything from a vendor you can download again | Size without benefit |
A matching .gitignore is five minutes of work and prevents the single most common complaint about ECAD in Git, which is repository size.
The release exception
The table above says not to commit fabrication outputs. There is one important exception.
A release is different from day-to-day work. What went to the fabricator is evidence, and evidence that can be regenerated is not evidence — regeneration depends on tool versions, library state and settings that may all have moved.
So: do not commit outputs on every export, but do commit, or otherwise archive, the exact package you released, tagged with the release. Git tags handle the marking well. Whether the files themselves live in the repository or beside it is a storage decision; what matters is that they are frozen and identifiable.
What Git genuinely gives you
History that survives people. Every state, with an author, a date and a message. This alone is more than most hardware projects have.
Branches for exploration. Try an alternative layout without endangering the main design. For schematic-level work this is comfortable; for layout work less so, for reasons below.
Tags for releases. v1.0-rev-c is a permanent, retrievable label on an exact state of the whole project.
Honest text diffs of the schematic. Not always easy to read, but a changed net or a changed value is visible, and that is far better than comparing two PDFs by eye.
A reason to write a sentence about every change. The commit message is the cheapest change record in existence.
What Git does not do for hardware
None of these are defects in Git; they are consequences of it being a general-purpose file versioning system rather than a hardware tool.
Layout diffs are not readable. The file is text, so Git will show you a diff, but a few hundred lines of changed coordinates do not tell a human what moved. You need a geometric comparison, which lives outside Git.
Merging layouts is risky. Two people editing the same board and merging is not a reliable operation. In practice teams lock the board — one editor at a time — which works, but it is a convention Git does not enforce.
No concept of a part. Git versions files. It does not know that C12 is an instance of a capacitor that is also used on four other boards, so "where else do we use this part?" is a text search, not a query.
No approval state. A commit is not an approval, and a tag is not a signature. Who reviewed this, and against what, is a question Git cannot answer.
No link to the physical world. Git has no opinion about which commit corresponds to the boards in the drawer. That mapping has to be maintained by you, in the tag names and the release notes.
Binaries are a weak point. Datasheets, 3D models, exported PDFs: Git stores each version in full. This is what turns repositories into monsters. Large-file extensions exist and work, at the cost of extra setup.
A layout that works
/hardware
/orion-mcb
orion-mcb.kicad_pro
orion-mcb.kicad_sch
orion-mcb.kicad_pcb
/lib project symbols and footprints
/docs design notes, decisions, rationale
/scripts export scripts
.gitignore
/releases
/orion-mcb-rev-c frozen outputs, taggedTwo conventions make this work in practice. One board per directory, so that a board's history is readable in isolation. And a commit message convention that says what changed in engineering terms — "R33 10k→4k7, fixes ADC reference droop" beats "update schematic" by a distance that only becomes obvious two years later.
Where the boundary falls
Git is strong on the design source: schematic, layout, libraries, scripts, notes. That is its natural territory and it is good at it.
It is weak on everything that is about parts and configurations rather than files — which component is used where, which revision was released, who approved it, what a given board is made of. Those questions are not file questions, and a file versioning system answers them awkwardly or not at all.
Most working setups therefore use both: Git for the design source, and something else for the component and configuration data. The mistake is expecting either one to cover the whole span.
XKEMA sits on the second side of that boundary. It does not store native ECAD design files and is not a replacement for Git: your .kicad_sch and .kicad_pcb belong in version control, and Git does that job well.
What XKEMA holds is the component, BOM and configuration side — shared component records, versioned BOMs and boards, and the released documentation and manufacturing outputs that go with them.
Hardware revision control How to release a KiCad PCB for manufacturing Hardware revision control: a practical guide Git vs PDM vs PLM: choosing by model