KiRI compares KiCad schematics and layouts across Git revisions

A visual diff for files Git cannot read

KiRI is a visual tool designed for reviewing schematics and layouts of KiCad projects that are version-controlled with Git. The README explains the origin in a way that tells you what the project is. It started as a script to experiment with having a visual diff tool for KiCad projects including schematics and layouts, and after some time it became an interesting project and it is still being updated. The problem it addresses is real and specific. A KiCad schematic is a structured binary or text format that Git can store but not usefully diff, so a reviewer looking at a commit that touched a schematic sees a file change and no idea what moved. KiRI answers that by rendering the project to images and comparing those. Internally it uses existing tools to generate SVG images of schematics and layouts to be compared, which means the comparison is visual rather than semantic, and a reviewer walks through pages and layers one at a time rather than reading a list of changed components.

The export path changes with every KiCad version

The mechanism is where the version compatibility actually lives, and the README is specific about it. For schematics, if KiCad 7 or later is installed, kicad-cli is used. If KiCad 6 is installed, which does not have kicad-cli available, the schematics are exported using xdotool on Linux and Windows and cliclick on macOS, using the GUI, and the documentation says plainly that this method is far from the ideal and is not recommended. If KiCad 5 is installed, or the project is based on KiCad 5, the plotkicadsch and plotgitsch tools are used instead. For the layout layers the choice is different. KiCad-Diff is used for all supported KiCad versions using the pcbnew library available in Python, and it is also possible to use kicad-cli to export the layout layers, but that process is slower because KiCad-Diff exports all the layers at once while kicad-cli can only do one layer at a time. So the tool supports KiCad 5 and later, but the quality and speed of what you get depends on which version you have and which export path it takes.

Running it is one command, and the project file is optional

KiRI is launched with a single command that can be run anywhere, inside or outside the project repository:

kiri [OPTIONS] [KICAD_PROJECT_FILE]

The project file argument is optional. If you run from inside the project repository, it will use the .pro or .kicad_pro file that is available, and if both are present, which the documentation notes is not good, it will ask you to choose. The same happens if you run outside the repository without passing the file. The command line flags are shown with the -h flag. The screenshots in the README show what the review experience looks like, with a schematic view that walks through and compares each page of the schematics individually, and a layout view that walks through and compares each layer of the layout individually. There is also a comparison image showing the same schematic when the project is updated from the KiCad 5 .sch format to the KiCad 6 .kicad_sch format, which is a nice illustration of why a visual tool earns its place. Keyboard shortcuts are described as a really good way of walking through the commits, pages and layers quickly, with the available shortcuts shown by pressing the shortcut i.

The generated package is a web app you can serve anywhere

There is a possibility to archive the generated files, which turns a review into something you can hand to someone else. The important detail is that it is not necessary to have KiRI installed to visualise the generated files. You unpack the generated package and then execute the web-server script inside of the folder:

tar -xvzf kiri-2021.11.18-16h39.tgz
cd kiri
./kiri-server .

The date in that filename is worth noticing, since it shows the tool stamps its output, which means a review package carries the revision it was generated from. The second half of the design is the separation between generating and viewing, and it is a good one. The person generating the comparison needs KiCad installed and the right export tooling, and the person reviewing it needs nothing but the package and a web server. For a distributed team, or a reviewer on a machine that has no KiCad, that is the difference between a tool that gets used and one that does not. The installation instructions live in a separate INSTALL.md file at the root, and the tree shows the install scripts that support it, with install_dependencies.sh, install_kiri.sh and install_plugin.sh alongside a python-requirements.txt.

A PCBNew toolbar button closes the loop

KiRI integrates with PCBNew by adding a button to its toolbar, and the integration is a copy of a plugin directory into the KiCad scripting plugins folder. The steps are given in the README, starting with creating the folder if it does not exist, and then copying the plugin there, with the plugin named kiri_v6, which points at the KiCad 6 generation of the plugin API:

# Create folder if it does not exist
mkdir -p "~/.kicad/scripting/plugins"

# Copy the plugin there
cd ./kiri
cp -r "./kicad/plugin/kiri_v6/" "~/.kicad/scripting/plugins/kiri"

The value of this is that the review starts from where the design work happens. A designer in PCBNew can produce a comparison without leaving the editor, which removes the step of remembering to run a separate command on a schematic you have open. The plugin directory in the tree is kicad/, alongside a submodules/ directory and a .gitmodules file, so the external tools the project depends on are vendored as submodules rather than assumed to be present. The README also asks for contributions, with a note that a donation is welcome, and the project carries a MIT licence with the version at 1.0.0 from the initial release.

Editorial conclusion

Adopt KiRI when your KiCad project lives in Git and you want reviewers to see a change in a schematic or a board layer rather than a text diff of a binary file. Do not adopt it as a design rule checker, since it compares renderings rather than analysing netlists, and do not expect it to run the same way across KiCad versions, since the export path differs for each. Verify first that your KiCad version has an export path KiRI can use, that the Git history contains the revisions you want to compare, and that the plugin installation path matches the KiCad version you run.

Frequently asked questions

Official sources

1. Issues
2. leoheck/kiri on GitHub
3. License: MIT
4. README
5. Releases