Metadata-Version: 2.3
Name: kigit
Version: 0.0.1
Summary: KiCad-semantics aware git diff and git status CLI tool
Requires-Dist: typer>=0.25.1
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# kigit

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

[![PyPI version](https://img.shields.io/pypi/v/kigit.svg)](https://pypi.org/project/kigit/)
[![Python versions](https://img.shields.io/pypi/pyversions/kigit.svg)](https://pypi.org/project/kigit/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

`kigit` is a command-line tool that makes Git output for [KiCad](https://www.kicad.org/)
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.1).** This is the first 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.1, 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`:

```bash
pip install kigit
```

Or as an isolated tool with [uv](https://docs.astral.sh/uv/):

```bash
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.

```bash
# 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. |
| `--c2-ref` | `-c2` | *none* | Git reference used as the **second** state. When omitted, the first ref is compared against the **working-directory** schematic. |
| `--search-depth` | `-p` | `2` | How many directory levels to descend when locating the schematic file. |
| `--search-directory` | `-d` | `.` | Root directory for the schematic file lookup. |
| `--verbose` | `-v` | `false` | Show a detailed, per-net and per-node breakdown instead of a brief count summary. |

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?".

### `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):

```text
+ 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:

```text
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:

```text
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

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](https://docs.astral.sh/uv/) for packaging, [pytest](https://docs.pytest.org/)
and [Hypothesis](https://hypothesis.readthedocs.io/) for testing, and
[Typer](https://typer.tiangolo.com/) for the command-line interface.

---

## License

`kigit` is released under the [MIT License](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.
