Pros and cons of using a VCS (git etc.) with KiCad

Many people use a version control system with KiCad successfully. Git is almost a de facto standard especially in Open Source world, but any VCS should work, and actually a simpler system may be better for KiCad. This article uses git nomenclature.

KiCad file formats are text based and work well with VCS

First we have to say that because KiCad file formats are text based – even human readable – by design, they are well fitting for a VCS. Actually the developers have put extra effort to make the file formats behave so that they can easily be handled by a VCS.

In version 5.1 there are still inconveniences, but version 6 shouldn’t make unnecessary changes to files when saving. User specific files are also separated from design files and can be ignored by a VCS.

Version history works

A VCS can be very beneficial with KiCad. The pros are:

  • Linear version history works perfectly. It can even work as permanent limitless undo feature if small commits are made regularly. Nothing is ever lost by accident.
  • Linear versions can be created using tags, it’s not necessary to create archive copies of the project for each version.
  • Branching works, if you want to for example try something, throw it away and then continue with the main design.
  • It’s very easy to push to a central repository and pull from there. Therefore sharing a project is easy, or changing between locations and machines while doing one design.
  • Central or other repository works as an extra backup if it’s in an external machine or service.

Permanent version history, ease of sharing (even sharing between several machines for one person) and having a backup are good enough reasons to use a VCS.

Merging and distributed team collaboration doesn’t work

However, due to the nature of CAD data – not just KiCad – the features of modern VCS which can be used with KiCad are very limited. What does work is mentioned above. What doesn’t work are the main points of modern complex VCS, especially of git etc.: distributed development and ease of merging. In general, merging within one file doesn’t work at all if there are conflicts. The reasons are explained in Tools for cooperation?.

More specifically, these features don’t work:

  • Textual diffing is mostly meaningless for normal work.
  • Merging withing one file can’t be expected to work.
  • Cherry-picking or other data exchange between branches doesn’t work, so parallel development of several flavors or variants doesn’t work.
  • Several people working on one design file simultaneously doesn’t work.

Not being able to use most of the features of a VCS isn’t of course a con per se, but there is one big danger related to that. Because merging after distributed development isn’t possible, it’s too easy to create conflicts which can be solved only by rejecting one of the change sets. Two people can’t work simultaneously on one schematic file or on one PCB layout. Also, if you do design on one machine, push, go to another machine, forget to pull, continue working, try to push – you will loose one or the other change set. All development must be sequential, pulling before each session and pushing after the session.

In reality merging inside one file may work, but for practical work it’s as good as random success.

Merging and collaboration work if changes are isolated to different files

Merging is possible if “theirs” and “ours” are in different files. In that case there can’t be conflicts. Changes can still of course affect each other, but they happen at the normal design level, just like when you change something in a schematic and must update the PCB afterwards.

Similarly changes in components in libraries are isolated. Each footprint is in its own file, and even though there can be several symbols in one symbol library file, changes in one symbol shouldn’t affect other symbols and are limited to one area in the file.

Hierarchical sheets are stored in their own files, so schematic design is fitting for collaboration if different people work on different sheets.

For centralized collaboration you may want to consider a VCS with locking feature, like SVN.