Project Revision / Version Control

I feel like I had to do this the brute force way, but I recently had to revise a design and it took me a couple hours just to get it set up to do the actual work.
So I had a complete project, schematic, pcb created in Kicad 6 (call it Rev 1), and needed to create a new revision 2. When I had created Rev 1, I had named the files something like ‘’. So the Kicad project, sch, and pcb all ended up with the revision in the name. The schematic has 4 pages as well. I did n’t see any downside to this until I tried to copy the whole folder the project was in and simply rename the files. Eschema had the biggest problems with this. Trying to reassociate the pages with the master page broke things and made a mess. I ended up using a text editor and changing the file name references using find/replace. Very messy.

Surely there has to be a ‘right’ way to do this…

Messing with the filenames is fraught. I leave them alone and version the directory instead. So I’ve directories named like gargleblaster-reloaded, microphony-compact. There’s a Save As action from the project dashboard intended for this.

You may prefer myboard-v1, -v2 etc. I don’t do electronics for a living and usually don’t expect to try more than twice the same design. :smile_cat:

KiCad has a:

Project Manager / File / Save as to copy and rename a project.

In a similar way, you can create a template from a project (just add an icon to click on and a description in html) and then you can use that as a starting point to create similar projects.

1 Like

I want my project number, revision letter, and project name in directory names and filenames so every generated file (gerber…) has all this info. So I have a directory like 123-4567-B-Project-Name, which has the four main files also named 123-4567-B-Project-Name.kicad_pro/kicad_sch/.kicad_pcb/kicad_prl
(an aside question: what is the purpose of the prl file, and why do I sometimes see an xml file added, and what is the point of fp-info-cache? K, I guess that was three questions).

I use kicad text variables to great advantage for defining things as well.

As an example to generate a new revision C of a board I do this:

  • open 123-4567-B-Project-Name
  • in project manager, File/Save-As “123-4567-C-Project-Name” (this creates new rev C dir, copies files and renames them with rev C embedded).
  • need some manual file system tidy-up (delete old rev-B xxx-backups dir, rename and empty my xxx-FAB, xxx-ASSY, and OUTPUTS dirs, where I move gerbers, pdfs and other output files – this is just my convention)
  • from either File/Schematic-Setup (sch editor) or File/Board-Setup (pcb) edit Text-Variables to change revision letter.
  • start tweaking my board.

I use Text-Variables to populate my custom schematic title block, text on copper layers, and text on silkscreen. Example variables:
“COMPANY”: “Acme Dynamite Works”,
“PCB-TITLE”: “Project-Name”
“PCB-NUM”: “123-4567”
“PCB-REV”: “C”
“FAB-DIR”: “123-4567-C-FAB/”
Easy to define text variables – you can do what works for you.

I use a custom schematic title block that uses the vars populated from Page-Settings:
(Note: it would REALLY be nice to add date-printed in title block)

In schematic File/Page-Settings I use my text vars to populate the title block appropriately (pcb page settings can be same or different as you like, but I never print title block from pcb):

I also use text-vars on silk – here set silk rev text to ${ASSY-NUM}-${PCB-REV} (plus a little box for sharpie note):

And I also use text vars on copper layers:

All on top of each other here:
and if I pull them out they look like this (reading properly for the fab folks to make no stackup mistakes):

Anyway, fwiw that is how I have set things up – probably better ways, but I am happy with my kicad setup.


Wow that’s a pretty comprehensive approach. I’m glad I don’t have to do all that. But to answer your questions, the .kicad_prl stores the current display settings, you can view it as it’s a text file; fp-info-cache is a cache of footprints whenever the PCB editor is run, it’s only an accelerator and can be safely deleted, and certainly does not need to be archived or exported; and I’ve not seen XML files unless you’re exporting BOMs or CPLs. So that’s 2 out of 3, HTH.

Huh. I have had xml files just appear while I am working – maybe I did something I didn’t realize. Here is one:
090-9060-B-BST-eStim.xml (231.7 KB)

Any idea how I can add current date/time to title block of schematic? I print it multiple times as I work on a board, so the release date is not what I am talking about, but a hook to system date/time. Something eagle had – handy.

Sorry, no :eye: :deer: about printing the date. The XML file appears to be an export of the schematic, as eeschema is listed as the provider and there are sheet settings, so you are triggering a plot in XML or something like that.

Most probably KiCad’s own netlist. This isn’t exported accidentally or as part of the normal workflow.

Date string:

I had some trouble getting some text on the fab layer to be the right size and visibility, and tracked it down to the kicad_prl file. I need to verify this, but I don’t think I was outputting the some gerbers for fab layers without that file. Maybe a bug, or maybe it was just on the display only, so I wouldn’t call it that yet. Bottom line is I archive the prl file.

Thank you! Great detail on your process.
I used to include layer and version info on each gerber back when I was using PADs. It was helpful in the film days. But now everything is automated and I am basically lazy, so I’ve not done that in years. It’s good practice though. You may have inspired me to make a project template that has this all set up for next project.

Yeah, one of the devs, think it was Seth, said that .kicad_prl should be included in commits.

If so, it is a bug, because the purpose of the prl (Project Local) is to be a local only file so that per-user settings are separated from the actual design data.

Here’s documentation from the source code:

 * The project local settings are things that are attached to a particular project, but also might
 * be particular to a certain user editing that project, or change quickly, and therefore may not
 * want to be checked in to version control or otherwise distributed with the main project.
 * Examples include layer visibility, recently-used design entry settings, and so on.
 * The backing store is a JSON file named <project>.kicad_prl
 * This file doesn't need to exist for a project to be loaded.  It will be created on-demand if
 * any of the things stored here are modified by the user.

For a project with a single author, like myself, I would still commit it so that subsequent readers can see the project as I see it. For a multi-author project maybe not.