Note

KiCad projects in Git: what to commit and what to ignore

By the Open-Hardware.org Team4 min read

Short answer

Commit the .kicad_pro, .kicad_sch and .kicad_pcb files plus any project library tables and libraries, and ignore .kicad_prl, fp-info-cache, lock files and the automatic backup folder, because those only describe your own machine.

The first time you put a KiCad project in Git, the status output fills up with files you never knew existed. Some of them are your design. Some of them are caches, lock files and window positions. Committing the second group causes noisy diffs and merge conflicts over nothing. Leaving out part of the first group causes a repository that nobody else can open.

This note sorts the files into those two groups. It uses the file names from KiCad 6 and later.

Which KiCad files are the actual design?

The project file (.kicad_pro), the schematic sheets (.kicad_sch) and the board file (.kicad_pcb) are the design, and all of them belong in Git.

File What it holds Commit?
.kicad_pro Project settings shared by schematic and board, such as net classes and design rules Yes
.kicad_sch Each schematic sheet: symbols and connections Yes, every sheet
.kicad_pcb The board: footprints, tracks, zones, layers Yes
sym-lib-table, fp-lib-table (in the project folder) Project symbol and footprint library lists Yes
Project libraries (.kicad_sym, .pretty folders, 3D models) Parts the design depends on Yes
.kicad_wks Custom drawing sheet, if you use one Yes

All of these are text files, so Git can store and diff them. The diffs won't read like code, but you can still see that a footprint moved or a value changed from 10k to 4.7k.

A common mistake is to leave out hierarchical sheets. A project with a root sheet and five sub-sheets has six .kicad_sch files, and the root sheet is useless without the others.

Which files should you ignore?

Ignore anything that describes your own machine or session: .kicad_prl, fp-info-cache, lock files, the backup folder and auto-save files.

The KiCad documentation describes .kicad_prl as local settings such as layer visibility and the selection filter, and says it does not need to be put under version control. If you commit it, every time someone toggles a layer, the repository changes.

The fp-info-cache file only speeds up footprint loading. KiCad rebuilds it.

KiCad can also archive the project to ZIP files on save. Those archives go in a backups subfolder of the project, usually named after the project with a -backups suffix. Your Git history already does that job, so the folder should stay out of the repository.

What does a starter .gitignore look like?

A short .gitignore that covers local settings, caches, backups and generated output is enough for most projects.

# KiCad local state
*.kicad_prl
fp-info-cache
*.lck
\#auto_saved_files#
_autosave-*
*-backups/

# Older KiCad leftovers
*.bak
*-bak

# Generated output (attach these to releases instead)
/production/
/gerbers/
*.zip

Adjust the last block to your folder names. If you keep a fabrication/ folder that a script regenerates, ignore it. If you keep hand-written assembly notes in that folder, don't.

Run git status after adding the file and check what remains. Anything you still don't recognize, look up before you commit it.

How do you make the repository open on someone else's computer?

Copy every library item the design uses into the repository and reference it through project library tables, never through a personal global library.

This is the step that breaks the most open hardware releases. KiCad looks for symbols and footprints through library tables. If a footprint comes from a library that only exists in your home folder, the board opens fine for you and shows missing parts for everyone else.

  1. Create a project library for symbols and one for footprints.
  2. Copy the custom parts you used into them.
  3. Add both to the project's sym-lib-table and fp-lib-table, using the ${KIPRJMOD} path variable so the path is relative to the project folder.
  4. Put 3D models in the repository too, and point to them with ${KIPRJMOD} as well.
  5. Clone the repository into a fresh folder and open it. Fix whatever is missing.

Step 5 is the same fresh-clone test from our release checklist for hardware repositories. It catches problems that look fine on your own machine.

Should production files live in Git?

Keep generated files out of everyday commits and publish them with each tagged release.

Gerbers, drill files, pick-and-place files and BOM exports are generated from the design. If they sit in the repository next to the sources, someone will eventually edit the board and forget to regenerate them. Then the repository contains two versions of the truth.

Attaching a ZIP of production files to a tagged release avoids that, and the person ordering boards still gets files they can upload to a fab without installing KiCad. Our guide to publishing an open hardware project covers the rest of the repository layout, from the README to the bill of materials.

How do you keep diffs and merges sane?

Keep commits small, write messages that say what changed on the board, and assume a merged layout needs checking in KiCad.

Git can't understand a board. A text merge of two layout changes may produce a file that loads but has overlapping tracks or a broken zone. A few habits help:

  • Agree on who edits the layout at any given time. Schematic changes conflict less often.
  • Commit after each logical change, such as "swap U3 to SOT-23-5 package," instead of after a day of work.
  • Run the electrical rules check and the design rules check before committing, so the history doesn't contain half-finished states.
  • Tag a release only from a commit where both checks pass.

For licensing the repository itself, add a LICENSE file at the top and state which license covers the hardware files, the documentation and the firmware. The license chooser can suggest a hardware license if you haven't picked one.

FAQ

Should I commit Gerber files to the repository?

Most projects keep them out of day-to-day commits and attach them to tagged releases instead. That keeps history small and makes sure the production files match a known version of the design.

Can Git merge two people's changes to the same board file?

Text merges sometimes work, but a merged board file can be syntactically valid and still wrong. Coordinate who edits the layout, keep branches short, and open the result in KiCad before you trust it.

Why does my board open with missing footprints on another computer?

The footprints probably live in a personal library that is listed in your global library table. Copy them into a project library, add a project fp-lib-table, and repoint the footprints.

Do the same rules apply to older KiCad versions?

Projects from before KiCad 6 used different extensions, such as .pro and .sch. The idea is the same, but this note uses the file names from KiCad 6 and later.