How do you do PCB version control with KiCad?

[rhodges]

I am just getting started with KiCad (and love it.) Before I start bad habits, I am interested in how others handle project version control.

I use git for all my code, and am comfortable with it. Would git work well for KiCad? Or would it be better to just copy a project into a new folder and resume? (Or copy the files into an archive folder?) Other options?

Thanks!

[SiliconWizard]

git or any VCS works fine for KiCad. If you're already comfortable with it, you can use it for KiCad, absolutely.
Just be careful about any kind of auto-merging - KiCad files are text files and thus depending on how you use git, you may find yourself in situations where it will merge files and it may lead to really unexpected results. Other than that, no problem.

Alternatively you can of course manually version your KiCad projects and archive them for each version. KiCad has a "Archive Project..." menu option which does that for you in a zip file.
No need to copy files around manually.

[Doctorandus_P]

Git does work quite well for archiving KiCad files, but KiCad still moves some things around in their files, so diffs are bigger then they could have been, and autmatically merging from git does not work. (Although some work has been done to improve this).

It is also possible to review diffs with a visual comparison. There are a lot of side projects around KiCad (could well be 100+) and I once saw a project that created bitmap pictures of different versions the schematic or PCB and then did a colored overlay to see the differences.

A quick search:
https://duckduckgo.com/?t=h_&q=KiCad+visual+diff&ia=web

Shows (among other results):
https://hackaday.com/2018/09/19/visual-schematic-diffs-in-kicad-help-find-changes/

[rhodges]

Just be careful about any kind of auto-merging

I would not consider the idea. My modest board has more than 12K lines in the PCB file and over 3K in the schematic. No way could I manually merge anything. I would treat the KiCad files as opaque blobs.

Git does work quite well for archiving KiCad files, but KiCad still moves some things around in their files, so diffs are bigger then they could have been, and autmatically merging from git does not work.

As I expected. Thank you both!

[bson]

git is fine.  I'd suggest setting up .gitattributes for file types that are effectively unmergeable.  But you can still allow diffing them for clues as to what has changed in commits since none of them are binary.  Use tags to name versions when you send off gerbers; this lets you easily checkout the files for the actual version of a board you have in front of you.

[SiliconWizard]

If he's the only one working on his projects, the potential merging issue is virtually non-existent (unless he was working on several "branches" of a given circuit at any given time, which is pretty rare). But still something to be aware of.

Even in teams, working on the *same* schematic at the same time is pretty rare, and frankly I don't recommend it. Much too risky. Hardware is not software.
What can be common though, is that the person doing the layout is not the one having designed the schematic, and if the layout person has to swap some pins, that must be back-annotated into the schematic. In which case you have effectively two persons working on the schematic. But in that case, having a clear design process works best. Again hardware is not software. So usually, when a design is being layouted, no one is changing the schematic in the meantime (except again potentially the layout person.) Unless you like working in a constant state of mess.

All obvious probably, but just to say that while using software-oriented version control tools for hardware is fine for the basic stuff, don't overdo it and don't try to copy too much the processes that are usual with software. It rarely works out.

[Doctorandus_P]

I never quite understood the use of "back annotation".
I usually have both the schematic and the PCB open at the same time on the same PC.

But if someone in Brazil starts working on the PCB after the schematic designer in Europe goes home for dinner it makes a bit more sense.

Backannotation in KiCad is quite limited, and I don't think it does pin swapping. Easiest way is probably if that (fictive) person in Brazil also has the whole project, changes the schematic and does normal forward annotation.

In my normal workflow I it is quite normal for me to mix the schematic and PCB. I start the PCB design before the schematic is complete. When I/O goes from an uC to a connector, I usually start drawing PCB tracks from the uC, and stop them just short of the connector. Then I can see what is the most logical way to connect them to the connector.

I also think back annotation is overrated. pin and gate swapping may have been useful in designs with 100+ TTL IC's but with microcontrollers you have a lot of extra constraints. timers, Uarts and other peripherals are often not freely assignable, while GPIO pins to blink a led can be assigned over whatever port has a bit that is convenient for routing. Catching that in "pin swapping logic" would be spice-like behavior.

[Benta]

Back annotation makes a lot of sense with FPGAs, just to name an example.

[hpw]

I use git for all my code, and am comfortable with it. Would git work well for KiCad? Or would it be better to just copy a project into a new folder and resume? (Or copy the files into an archive folder?) Other options?

I use SVN Tortoise as VirtualSVN for server... locally diff & diff 3 has to be setup as unmergeable by bat file. In addition local file(s) lock if one need this.

[gjvdheiden]

I tag/branch the project in Git when I'm having the boards made. So I can track physical versions within Git. As software, having boards made is a iterative proces also (unfortunately).

I also make a release in GitHub and attach schematics as PDF's and the zipped gerbers as release files. Keeps it organized without checked in binary rubbish.

I also put my symbol libs, footprints and 3d models in Git. Shared among my projects. But, because it is shared, these have their own lifecycle.

KiCad developers used to encourage using Git, I think they still do.

[woody]

I am too stupid to really dig git and I am the only one working on my projects, so I keep everything local:

..\Projects\CustomerName\ProjectName\CAD\Onderhanden

During design I work on KiCad files in the Onderhanden directory. As soon as I want to make a proto- or final PCB I update the revision data on the PCB, exit KiCad and make a copy of the Onderhanden directory to a Vxx.yy directory which also lives under \CAD. Such a directory is by principle never worked in. Project specific libraries reside under \CAD\Kicad Libraries

It uses more disk space, but that is by far the cheapest and most abundant resource on my PC. Backups are made automatically of everything important on my PC every 60 minutes to my private cloud, in a per-hour directory. If I make a stupid mistake or something dies on me I loose an hour tops.

No live network connection needed, no diffs, no merging, no zipping, no stuff I do not fully understand (the advantage of). It works for me, but YMMV.

[abeyer]

No live network connection needed, no diffs, no merging, no zipping, no stuff I do not fully understand (the advantage of). It works for me, but YMMV.

That's certainly a workable approach... but if you want some of the power of more complete version control without the complexity of git, you might check out https://fossil-scm.org/

Fossil is popular in the single-user, all local (unless you want a server), simpler than git space.

[PlainName]

How does fossil compare to subversion? Is there OS integration like with TortoiseSVN?

[Veteran68]

How does fossil compare to subversion? Is there OS integration like with TortoiseSVN?

Subversion is server based. Of course you can run the server on your development workstation so it appears to be a local/distributed repository, but it's still working on the client/server model. It's also very long in the tooth, a glorified CVS, and so is not as efficient as more modern SCM systems.

Fossil, git, and other distributed SCM systems are truly local. All repo history is kept local. You can connect them to a remote server (such as Github for example, or a server on your LAN) for centralized team work, but that's optional and after the fact. They're first and foremost, local repositories.

[PlainName]

AFAIK Subversion isn't server-based. It has a master repo is all, and no server software - local or remote - is required. You can run a server for remote access, but you can just as easily plonk the repo on a file share and access it as if it were local.

That has some advantages which I find extremely useful, not least that the local working folder isn't the entire repo. Sometimes I try something and royally screw up, and the resolution is to just wipe that folder and check out again. When I tried that with git I lost everything...

The master repo thing means there is one authoritative source, and one thing to make sure is backed up appropriately. The distributed model is fantastic for distributed access, but the root post (and the one mentioning fossil) is about a single developer on his own doing all local stuff. The messing about that comes with distribution (that is, a full copy of all 150MB history for your 5MB project in every instance, and similar) just gets in the way and complicates matters.

And... each of those big instances may not be the full story anyway. You need to keep track of every one to make sure you have a full backup.

[Veteran68]

AFAIK Subversion isn't server-based. It has a master repo is all, and no server software - local or remote - is required. You can run a server for remote access, but you can just as easily plonk the repo on a file share and access it as if it were local.

That's technically true, but it's still a client/server model. A "file share" is by definition a remote filesystem. And while yes, you could run the master repo on a local filesystem, I've never actually seen SVN implemented that way in any sort of serious or professional setting. Even when I ran it for my own personal usage on a single workstation, I ran the server daemon.

As a software engineer going back to the 80's, I've used many SCMs ranging from RCS (predecessor to CVS) on Unix, TLIB on MS-DOS, PVCS and SourceSafe (both pre- and post-Microsoft acquisition) and up through CVS, SVN, and Git. (Not intended as an "appeal to authority" argument, but more to illustrate the personal change management I've had to go through as these technologies changed.)

I really liked SVN and invested a lot in migrating our company from CVS to SVN. I even contributed changes back to the cvs2svn migration script that ships with SVN. Transitioning to a distributed model like bazaar, mercurial or git was a paradigm shift, and one I initially resisted -- much as I initially resisted seeing the value in moving from ASM to C, from C to C++, and then from C++ to Java. But as with all of those example, after having to work with git due to project requirements, the light bulb eventually goes off and I'm like "oh yeah, I get it now, this is cool!"

I much prefer working in git than any centralized C/S tool that I worked in before.

[phil from seattle]

I'm probably a troglodyte here but I don't bother with source code control for my boards.  For every version that I get manufactured, I need to have a usable and, potentially editable, copy available. This includes prototypes and beta test versions as well as production.  And, the amount of disk space this needs is pretty much de minimis, as the lawyers say.

For short term disasters, I have an auto backup that has yesterday's version. I have used that more than once.

[rhodges]

For every version that I get manufactured, I need to have a usable and, potentially editable, copy available.

So... You put each revision in its own directory? Maybe put the rev numbers at the end of the directory names?

[phil from seattle]

For every version that I get manufactured, I need to have a usable and, potentially editable, copy available.

So... You put each revision in its own directory? Maybe put the rev numbers at the end of the directory names?

Yes. I do.

[PlainName]

For every version that I get manufactured, I need to have a usable and, potentially editable, copy available.

So... You put each revision in its own directory? Maybe put the rev numbers at the end of the directory names?

Yes. I do.

Yeah, I do that. But I use revision control too

Just that I like having the previous version(s) easily available for checking stuff (or maybe trying stuff out). Subversion lends itself to that, git not so much.

(Although, to be clear, I don't have every copy available, just significant ones, perhaps the versions I've given to a client or prior to a breaking change, etc. The ones not present are still in svn, of course.)

[janoc]

Just that I like having the previous version(s) easily available for checking stuff (or maybe trying stuff out). Subversion lends itself to that, git not so much.

Why exactly git doesn't lend itself to that? You know you can have multiple working copies/worktrees checked out simultaneously, each tracking a different branch/commit/whatever of the same repo, right? You can even clone your existing working copy into another folder and switch branch inside of the new copy if you want. Switching between branches with git is as easy if not easier than with Subversion.


Also your problem with "losing everything" with git when you have wiped your working copy - well, if you never "push" your changes anywhere, they are only in your local working copy. Create a different folder somewhere (e.g. on a network share) and create an empty "bare" repository in it using "git init -bare".  Then set this repo as remote for your working copy and push your changes there. Voila, you have replicated your Subversion workflow.  (This happens automatically for you if you clone an existing repo to create your working copy).

Subversion forces you to do this automatically because of its centralized model - there is a clear distinction between a "repo" and a "working copy", so you can't set up the latter without first setting up the former. Git doesn't have anything like that. Each working copy is a "repo" as well - and they are all equal, so you can push and pull changes between them. That's a fundamental idea behind the decentralized revision control system.


Yes, git by default replicates the entire history within your working copy - that's a conscious design decision, disk space is cheap. It allows for both redundancy (each working copy is defacto a complete backup - more than one developer and company were saved by this "feature" when their servers/computers were stolen/hacked!) and operations that wouldn't be possible otherwise without loading down the central server. Try to work with a large Subversion repo when you have a slow connection or many developers!

However, if you really don't want to clone the entire history then you can do that too - use the "--depth" argument to git clone to create a shallow clone, limiting the history being copied only to the given depth.

So the issues and perceived downsides with git you have mentioned are really just user errors and maybe not spending a bit of time with the documentation. I am also with Veteran68 here - having used pretty much everything since the SCCS and RCS times through CVS, Subversion, SourceSafe and now git, I can tell you that the time spent learning how to use git properly is well worth it even if you never collaborate with anyone and use it only on your local disk drive.

All that is not to say that git doesn't have some rough edges and warts - oh it does and plenty. But certainly not those you mention.

[PlainName]

That's essentially saying that if you're an expert with your head screwed on it's no problem. Kind of like needing to use a command prompt to do rm -rf * is not a problem for those sorts. For mere mortals, an easier and safer way to do the same thing is perhaps better. In that context I use revision control as support for the thing I am really trying to do. I don't want to need to know the finer details, just have it be safe to use when my mind is on something else.

Same with backups - simple, safe, works is going to beat works and then some, needs attention, watch for the bears.

[janoc]

That's essentially saying that if you're an expert with your head screwed on it's no problem. Kind of like needing to use a command prompt to do rm -rf * is not a problem for those sorts. For mere mortals, an easier and safer way to do the same thing is perhaps better. In that context I use revision control as support for the thing I am really trying to do. I don't want to need to know the finer details, just have it be safe to use when my mind is on something else.

Same with backups - simple, safe, works is going to beat works and then some, needs attention, watch for the bears.

Well, if you have managed to learn Subversion then git is no more complex to use. One certainly doesn't need a PhD to read a tutorial where all this is explained. E.g.:


https://rogerdudler.github.io/git-guide/
https://www.git-tower.com/blog/git-for-subversion-users-cheat-sheet

And if you want to simulate the server-like workflow (or put a repo on a server):
https://git-scm.com/book/en/v2/Git-on-the-Server-Getting-Git-on-a-Server

Of course, anyone can spend their time as they see fit and I can't force you to invest a bit of time to read the manual to understand what you are actually doing. However, then don't spread half-truths and incorrect information if you don't know what you are talking about (by your own admission)?

There are also tools like git gui/gitk (come with git), GitKraken, TortoiseGit, VSCode has GitLens etc. - I gave the examples using command line because most git users will recognize those. How to achieve those tasks with the UI tools depends on exactly which tool you are using, the GUIs are obviously going to be different. But all support them, this is really basic stuff, the same as you would know what "svn commit" or "svn checkout" does.

[JPortici]

Just that I like having the previous version(s) easily available for checking stuff (or maybe trying stuff out). Subversion lends itself to that, git not so much.

I believe that in git you would tag the commit containing the version and then checkout the tag you need?

[JohanH]

I believe that in git you would tag the commit containing the version and then checkout the tag you need?

It depends on your workflow. You could keep different branches as versions well (then just checkout the branch). The tag is kind of an additional thing. It's maybe especially useful in public projects (I haven't bothered with tags in my own projects).

Tags are kind of pointers and when you check out a tag, you don't check out a real branch. If you also want to work on and update files, create a new branch at the same time when checking out the tag.