kigit 0.0.3

KiCad-semantics aware git diff and git status CLI tool

kigit

KiCad-aware git diff and git status for your schematics.

kigit is a command-line tool that makes Git output for KiCad projects readable. Raw git diff on a .kicad_sch file is dominated by formatting, re-ordering, and tool-generated metadata, so it tells you that a file changed but not what meaningfully changed. kigit cuts through that noise and reports the change in electrical terms instead: which nets were added, removed, renamed, or rewired.

Status: early preview (0.0.2). This is an early public release. It focuses on the schematic netlist and intentionally does a small thing well. Interfaces and output may change in future versions. Bug reports and feedback are very welcome.

---

What it does

kigit answers questions a plain text diff struggles with, such as "Did the wiring actually change, or is this just KiCad reshuffling the file?"

For the schematic in your repository it:

• locates the schematic via your project (.kicad_pro) file,
• exports the netlist for two project states using KiCad's own kicad-cli,
• compares the two netlists semantically, ignoring text-level noise, and
• prints a structured, color-coded summary of the real changes.

It reports nets that were added, removed, changed (nodes/pins added, removed, or modified; net-class changes), and renamed (a net whose connections are unchanged but whose name differs). Each changed net is annotated with semantic tags such as power-net, ground-net, critical-net, high-speed-net, connectivity level, and impact tags like connectivity-increased, node-added, or pin-function-changed. Purely cosmetic differences and unconnected (unconnected-*) nets are filtered out.

Not in scope yet

To set expectations for 0.0.2, the following are not analyzed yet and are planned for later releases:

• component value changes (e.g. a resistor going from 10k to 4.7k),
• PCB layout (.kicad_pcb) changes,
• further changes

---

Requirements

kigit orchestrates the tools you already use; it does not reimplement them.

• Python 3.10 or newer.
• Git, available on your PATH.
• KiCad 10.x, with the bundled kicad-cli available on your PATH. (kicad-cli ships with the standard KiCad installation on Windows, Linux, and macOS.)

kigit is cross-platform and runs on Windows and Linux (and other platforms where Python, Git, and KiCad are available). Run kigit check-health at any time to confirm your environment is ready.

---

Installation

From PyPI with pip:

pip install kigit

Or as an isolated tool with uv:

uv tool install kigit

---

Quick start

Prerequisite: your schematic must be committed to Git at least once. kigit retrieves historical versions with git show, so an untracked schematic cannot be diffed.

# Compare your working changes against the last commit (the "status" use case):
kigit diff

# Compare two commits, branches, or tags:
kigit diff -c1 main -c2 my-feature-branch

# See full detail instead of a summary:
kigit diff --verbose

# Confirm Git and KiCad are installed and reachable:
kigit check-health

---

Commands

Run kigit or kigit --help for general help, and kigit COMMAND --help for details on a specific command.

kigit diff

Summarizes the differences between two KiCad project states, filtering out noise from formatting, ordering, and tool-generated metadata.

Option	Alias	Default	Description
--c1-ref	-c1	HEAD	Git reference (commit, branch, or tag) used as the first state for comparison. Validated up front: must resolve in the repository.
--c2-ref	-c2	none	Git reference used as the second state. When omitted, the first ref is compared against the working-directory schematic. When given, it must resolve in the repository.
--search-depth	-p	2	How many directory levels to descend when locating the schematic file. Must be a non-negative integer.
--search-directory	-d	.	Root directory for the schematic file lookup. Must be a path tracked in the repository.

Behavior of the default invocation: with no -c2, kigit diff compares the first reference (default HEAD) against the current schematic on disk — i.e. "what have I changed since my last commit?".

Input validation (new in 0.0.2). kigit diff checks its arguments before any schematic is exported or compared, so mistakes fail fast with a clear message instead of a confusing downstream error:

• a -c1 / -c2 reference that does not resolve in the repository is rejected with "Commit doesn't exist in this repository.";
• a -d search directory that is not tracked in the repository is rejected with "Path doesn't exist in this repository.";
• a negative -p search depth is rejected as an invalid depth.

kigit check-health

Verifies that all required dependencies (Git and kicad-cli) are present on the system and reports any that are missing.

kigit version

Prints the installed kigit version.

---

Example output

The examples below are illustrative; actual output is color-coded in your terminal.

Brief summary (default):

+ 3 net(s) added
- 1 net(s) removed
~ 2 net(s) changed
~ 1 net(s) renamed

Detailed view (--verbose), showing how a changed net is annotated:

Changed Nets:
 Net '+5V':
  * properties: critical-net, power-net, medium-connectivity
  * impact: connectivity-increased, critical-net-change, node-added
  Added nodes:
   + U3 pin 4 (VCC, power_in)

When nothing meaningful changed:

No semantically meaningful changes to show.

 (Hint: only added, removed, changed and renamed items are shown (i.e. code changes are discarded.)

---

How it works

Before the steps below, kigit diff validates its arguments (commit refs, search path, search depth) and stops early with a clear message if any are invalid.

1. Locate — find the project's .kicad_pro and the matching .kicad_sch within the configured search directory and depth.
2. Retrieve — for each requested Git reference, extract that version of the schematic with git show <ref>:<path> into a temporary working area.
3. Export — run kicad-cli sch export netlist --format kicadxml on each version to produce a netlist in KiCad XML.
4. Parse — read the <nets> section into an immutable model of nets and their nodes (component reference, pin, pin function, pin type).
5. Diff — compute added / removed / changed / renamed nets, ignoring net codes and unconnected-* nets, and detect renames by matching nets with identical connections.
6. Classify & report — tag each net and change with semantic categories and print a readable summary.

---

Logs and temporary files

• Diagnostic logs are written to a kigit-log/ directory in the current working directory. If a run fails unexpectedly, this is the first place to look.
• Temporary working data (.kigit_temp/, .kigit_netlist_temp/) is created during a run and cleaned up automatically afterwards.

You may wish to add kigit-log/, .kigit_temp/, and .kigit_netlist_temp/ to your .gitignore.

---

Development

The project uses uv for packaging, pytest and Hypothesis for testing, and Typer for the command-line interface.

---

License

kigit is released under the MIT License.

---

Acknowledgements

kigit is developed as a Software Engineering course project for and with help from Auto-Intern GmbH, whose hardware team uses KiCad and Git for industrial monitoring systems. The goal is to help engineers make better commit decisions and to keep project history readable, with the intention of maintaining it as an open-source tool for the wider KiCad community.