Plotgitsch User’s Guide

Plotgitsch is a utility command coming from the plotkicadsch package. Its core feature is the ability to generate visual diff between two versions of a Kicad schematic managed in a Git project.

Provided your Kicad project is versioned with Git, this feature is useful in several cases, among which:

To walk you through some of these use cases, we are going to use a fake repository of a board and show how to use the commands.

In order to play with plotgitsch, let’s prepare a sandbox project and see what can be done.

Now, we have a project with a schematic with changes in the working copy. This project has a pretty strange history that will help us exercise the features of plotgitsch.

As you can already see, the schematic project isn’t located at the root of the git working copy. plotgitsch can compute changes recursively in subdirectories, from the current directory. It’s always safer to change the current directory to the root of kicad project you are interested in, in case several kicad projects share the same git project worktree.

This is a checkout of what is usually followed under git in kicad projects. For more information, refer to how to set up your git repository.

Although plotgitsch is invoked by default to run an external image diff tool, we will focus on using the internal diff feature by using the -i option. This feature tries to compute the visual differences between lists of drawing primitives (lines, texts, arcs…) of the schematics drawings and keeps the difference at the level of vector graphics, which allows any zooming level.

The primitives are reordered internally, so that the diffing algorithm can cope with great reworks of the schematics but still find the differences at the shape level.

In order to visualize the vector output of the difference, you’ll need an application able to display SVG pictures. Your default web browser should be able to handle these files. Let’s try for instance with firefox:

This should display:

It seems the last change to the working copy was the addition of a screw terminal block.

This is the display of changes that were introduced in your present working copy with respect to the latest revision checked in git, just like git diff would display the textual differences introduced in your working copy. Of course, instead of firefox, you can specify the tool of your choice to handle the svg output file.

For the simplicity of this guide, all the revisions of this playground repo have been tagged so that you can easily type them in.

plotgitsch handles revision specifiers just like git (behind the scene, it uses git). Please have a look at git revisions for all the kinds of commit reference specifiers.

Revisions to be compared can be specified in three forms: with two, one or no revisions.

For instance, let’s check the changes between two tagged revisions:

By default, the background is white, the unmodified part of the drawing is black, the added parts are green and the removed ones are red. These colors can be changed with the -c option. Say we’d rather have the background in black (RGB hex code 000000), the unchanged parts in white (RGB hex: FFFFFF), the added lines in clear blue (RGB hex: 008FFF) and keep the removed in red (RGB hex: FF0000), we need to issue the following command:

You may have noticed while performing the previous commands that the corresponding files are opened in your web browser but do not clutter your working directory. This is because these files are generated in the temp directory.

If you need the files, as documentation for instance, you can specify the -k option (--keep in long format) to force the generation in the working directory and disable deletion after use.

The project was not correctly checked in during the first revisions, namely, the cache library was not checked in:

This message indicates that in one of the revisions, the definition of a component is missing. The definitions are provided in libraries which must be checked in. To circumvent this forgotten step, plotgitsch lets you specify a path in your filesystem to one or several libraries to preload with the option -l or --lib=. If we are lucky, we can assume that the cache lib present in our working copy contains the required components in their correct version:

This works quite well. However, you can still notice that some changes appear at the shape of the LED which may have changed in the cache, because the wires around it show changes. We are quite lucky that the shape of more complex components haven’t changed (for instance a mapping on a microcontroller).

When a sheet is added or when several sheets are changed at once, the diffs are opened one tab per sheet in your browser.

It’s tedious to repeat the same options on and on each time you wish to visualize a diff. One option around that is to define an alias in you preferred shell script environment. For instance, if you are using bash, you can add this line to your .bashrc:

This lets you use the pgs alias to quickly check your local diffs from the last commit.

Another option is to use environment variables to customize the behavior of plotgitsch. Two environment variables are usable:

Set and export these variables in your $HOME/.bashrc or in you $HOME/.profilerc, like this:

This way, plotgitsch 's default behavior will be to use the internal diff with firefox as a viewer with customized colors.

There are a few last options: