How do you do PCB version control with KiCad? - Page 1
Forum section: electronics / general

author: rhodges
author_rank: Frequent Contributor
timestamp: August 09, 2023, 09:05:38 pm
content: 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!

author: SiliconWizard
author_rank: Super Contributor
timestamp: August 09, 2023, 09:45:35 pm
content: 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.

author: Doctorandus_P
author_rank: Super Contributor
timestamp: August 09, 2023, 10:35:12 pm
content: 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=webShows (among other results):https://hackaday.com/2018/09/19/visual-schematic-diffs-in-kicad-help-find-changes/

author: rhodges
author_rank: Frequent Contributor
timestamp: August 09, 2023, 11:52:48 pm
content: Quote from: SiliconWizard on August 09, 2023, 09:45:35 pmI 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.Quote from: Doctorandus_P on August 09, 2023, 10:35:12 pmAs I expected. Thank you both!

author: bson
author_rank: Unknown
timestamp: August 11, 2023, 07:24:45 pm
content: 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.

author: SiliconWizard
author_rank: Super Contributor
timestamp: August 11, 2023, 09:57:26 pm
content: 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.

author: Doctorandus_P
author_rank: Super Contributor
timestamp: August 11, 2023, 11:25:54 pm
content: 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.

author: Benta
author_rank: Super Contributor
timestamp: August 11, 2023, 11:49:25 pm
content: Back annotation makes a lot of sense with FPGAs, just to name an example.

author: hpw
author_rank: Frequent Contributor
timestamp: August 14, 2023, 07:24:35 am
content: Quote from: rhodges on August 09, 2023, 09:05:38 pmI 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.

author: gjvdheiden
author_rank: Contributor
timestamp: August 14, 2023, 01:52:25 pm
content: 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.

author: woody
author_rank: Frequent Contributor
timestamp: September 08, 2023, 11:24:55 am
content: 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\OnderhandenDuring 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 LibrariesIt 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.

author: abeyer
author_rank: Frequent Contributor
timestamp: September 08, 2023, 10:56:08 pm
content: Quote from: woody on September 08, 2023, 11:24:55 amThat'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 outhttps://fossil-scm.org/Fossil is popular in the single-user, all local (unless you want a server), simpler than git space.

author: PlainName
author_rank: Super Contributor
timestamp: September 14, 2023, 11:18:54 am
content: How does fossil compare to subversion? Is there OS integration like with TortoiseSVN?

author: Veteran68
author_rank: Frequent Contributor
timestamp: September 14, 2023, 11:58:35 am
content: Quote from: PlainName on September 14, 2023, 11:18:54 amSubversion 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.

author: PlainName
author_rank: Super Contributor
timestamp: September 14, 2023, 02:29:05 pm
content: AFAIK Subversion isn't server-based. It has a master repo is all, and no server software - local or remote - is required. Youcanrun 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 ineveryinstance, 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.

author: Veteran68
author_rank: Frequent Contributor
timestamp: September 14, 2023, 03:32:15 pm
content: Quote from: PlainName on September 14, 2023, 02:29:05 pmThat'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.

author: phil from seattle
author_rank: Super Contributor
timestamp: December 14, 2023, 01:18:04 am
content: 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.

author: rhodges
author_rank: Frequent Contributor
timestamp: December 14, 2023, 05:04:19 am
content: Quote from: phil from seattle on December 14, 2023, 01:18:04 amSo... You put each revision in its own directory? Maybe put the rev numbers at the end of the directory names?

author: phil from seattle
author_rank: Super Contributor
timestamp: December 17, 2023, 07:07:58 am
content: Quote from: rhodges on December 14, 2023, 05:04:19 amYes. I do.

author: PlainName
author_rank: Super Contributor
timestamp: December 17, 2023, 09:08:50 am
content: Quote from: phil from seattle on December 17, 2023, 07:07:58 amYeah, I do that. But I use revision control tooJust 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 haveeverycopy 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.)

author: janoc
author_rank: Super Contributor
timestamp: December 17, 2023, 12:05:27 pm
content: Quote from: PlainName on December 17, 2023, 09:08:50 amWhy 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.

author: PlainName
author_rank: Super Contributor
timestamp: December 17, 2023, 12:49:35 pm
content: 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.

author: janoc
author_rank: Super Contributor
timestamp: December 17, 2023, 01:35:39 pm
content: Quote from: PlainName on December 17, 2023, 12:49:35 pmWell, 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-sheetAnd 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-ServerOf 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.

author: JPortici
author_rank: Super Contributor
timestamp: December 17, 2023, 08:08:09 pm
content: Quote from: PlainName on December 17, 2023, 09:08:50 amI believe that in git you would tag the commit containing the version and then checkout the tag you need?

author: JohanH
author_rank: Frequent Contributor
timestamp: December 17, 2023, 08:43:16 pm
content: Quote from: JPortici on December 17, 2023, 08:08:09 pmIt 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.

author: janoc
author_rank: Super Contributor
timestamp: December 17, 2023, 10:55:01 pm
content: Quote from: JohanH on December 17, 2023, 08:43:16 pmNot true with git. You can literally check out and start modifying and committing on top of any commit in the history, regardless of whether it is a branch, tag or a simple commit. The only problem with that is that if it is not a branch/tag you will have difficult time to find those commits later since no symbolic name (branch) points to them. That's what git calls "detached head" state. If you check out a branch, you don't end up in with a "detached head" but at the head revision of that branch. That's all.The difference between branch and tag is only that the tag is immutable - it is a label attached to a fixed revision and cannot be moved once it is created, only deleted. A branch label always "moves" to the latest commit on that branch. However, they are both only special names for revisions.Tags are usually nice for things like marking important revisions with a human understandable name - e.g. releases of the code. One can use branches for that too, though.

author: SiliconWizard
author_rank: Super Contributor
timestamp: December 17, 2023, 11:07:38 pm
content: That's well detailed.The bottom line though if you TLDR is to just use tags for marking versions of your work. And especially since we're talking about hardware design here, not software. Tag your versions. Don't try to be clever.What you consider a "version" is of course 100% dependent on your own way of working and releasing, but if you're doing any kind of professional work, what a version is for a board is not going to be very ambiguous. Anything that has been sent to production deserves its own, clear, definite version, and any future change that ends up in production does as well. Tag them. What remains in R&D during development, it's up to you.With that said, as I mentioned earlier, KiCad has an "archive project" function, so archiving the project in a given state takes about 2 s. Just add a version to the archive filename, click OK, and move on. If you don't want to deal with a version control tool. You don't even need to copy any file manually. It's actually faster than using git. (git could provide other benefits of course, but just mentioning the point.)

author: phil from seattle
author_rank: Super Contributor
timestamp: December 19, 2023, 12:14:29 am
content: Quote from: PlainName on December 17, 2023, 09:08:50 amI only keep versions that have a real world PCB.

author: Timot
author_rank: Newbie
timestamp: January 31, 2024, 01:40:17 am
content: A couple of friends and I have been dealing with similar version control issues, both at work and on personal projects. We've come to the conclusion that replacing schematics with code is the way to go. We started a project called "atopile" that does just that. Here is the project repository:https://github.com/atopile/atopileBefore starting atopile, we tried to automate the generation of KiCAD manufacturing files with KiBot:https://github.com/INTI-CMNB/KiBot. KiBot is quite convenient to build output directly on GitHub or GitLab. But merging, diffing and reuse of design is still absent because the design still relies on schematics. We also tried Skidl:https://github.com/devbisme/skidl. The nice thing with Skidl is that you can version control your electronics as code, just like software. That means you can branch the project, make pull requests, merge back into main etc... But because it's baked into python you have to deal with a tool that was not designed for the job. This manifest as being both unintuitive to design electronics (Python's keywords are meant for managing the flow of data, not describing electronics) and difficult to contribute to the skidl python project. So ultimately we ended up designing our own compiler.We already have features like subclassing, replacement, units and tolerances, automatic resistor and capacitor selection. There's a bunch more we'd like to build too like an equation solver and layout reuse.Hope that helps. Have a look and let me know what you think!

author: Smokey
author_rank: Super Contributor
timestamp: January 31, 2024, 03:28:54 am
content: I'm a fan of incremental commit numbers with SVN. Makes it easy to reference stuff.Also checking out per file or per folder is nice compared to git.For a hardware project where you really aren't going to be using a lot of the software design features of git, I don't have a problem being old school and just using svn.The version control system in Altium was SVN forever right? Now it looks like they also push git.

author: dobsonr741
author_rank: Frequent Contributor
timestamp: February 01, 2024, 01:29:27 am
content: Any recommendation for a Kicad specific .gitignore file?

author: abeyer
author_rank: Frequent Contributor
timestamp: February 01, 2024, 06:04:12 am
content: gitignore.io has a template, but I haven't actually looked at it in detail/used it:https://www.toptal.com/developers/gitignore/api/kicad