Gitgraf
Gitgraf keeps a graph of nodes, facts and edges as human-readable YAML files in a git repository: pip install, no server, no database.
Every fact and edge carries three time axes, and nothing is ever overwritten:
- Valid time (
valid_from,valid_to): when it is true in the world. - Knowledge time (
known_at): when it was first known. - Change time (
changed_at,superseded_at): when the record was written or replaced. An update appends a new version, so the graph can be read as it was at any earlier moment.
It is the store that bibliotheke, a knowledge graph framework, is built on, and it works on its own for any register of dated facts.
Quickstart
gitgraf init
gitgraf add node windfarm "Hornsea 2"
gitgraf add node bmu "T_HOWBO-1"
gitgraf add fact hornsea-2 capacity_mw 1386 --valid-from 2022-08-31
gitgraf add edge t-howbo-1 part_of hornsea-2 --valid-from 2021-12
gitgraf show hornsea-2 # the current graph
gitgraf show hornsea-2 --valid-at 2022-01 # what was true then
gitgraf show hornsea-2 --known-at 2024 # what had been learned by then
gitgraf show hornsea-2 --at-commit v1.0 # as committed at a git revision
gitgraf show hornsea-2 --json
add fact and add edge print a record id. Use it to change a record without losing history:
gitgraf update f53fd77 --value 1320 # appends a new version
gitgraf retract f53fd77 # hides it from the current graph
gitgraf history hornsea-2 # every version, including superseded ones
Sources and edge attributes
Any fact or edge can say where it comes from, and an edge can carry attributes of the link itself, such as a share of ownership:
gitgraf add fact hornsea-2 capacity_mw 1386 --source "TEC register 2026-03"
gitgraf add edge hornsea-2 owned_by orsted --set share=0.5 --valid-from 2022-09 --source "company announcement"
gitgraf update e2778f9 --set share=0.4 --source "annual report 2025" # a new version; the old share stays in history
A new version keeps the source and attributes it does not change. In a batch for gitgraf import, source can be set once for the whole batch, per node, or per record, and an edge takes attrs: {share: 0.5}.
The data model can type the attributes of a relation and require a source on every record:
source: required # a write without a source is refused; `check` reports hand edits that drop one
edges:
owned_by:
from: windfarm
to: company
attrs:
share: {type: number, required: true}
role: {type: enum, values: [operator, investor]}
gitgraf model add edge owned_by windfarm company --attr share:number declares one from the command line. Both are stored only where present, so a graph that uses neither has the same files as before.
Files
A graph is a directory with a gitgraf.yaml marker and one file per node at nodes/<type>/<id>.yaml, with optional Markdown next to it at nodes/<type>/<id>.md:
id: hornsea-2
type: windfarm
name: Hornsea 2
notes: ''
facts:
- id: f53fd77
key: capacity_mw
value: 1386
valid_from: 2022-08-31
valid_to: null
known_at: 2026-11-14T10:07:00Z
changed_at: 2026-11-14T10:07:00Z
superseded_at: null
edges: []
A node's file is dumped deterministically, so a git diff shows only what changed.
Commands
| Command | What it does |
|---|---|
init, add node|fact|edge, update, retract, import |
Write the graph; import merges a batch file and is safe to re-run |
show, history, list, types, search, export |
Read it; all take --valid-at, --known-at, --changed-at and --at-commit |
merge |
Join two nodes that are the same thing; an alias resolves wherever an id is expected |
model, model add|rename|drop, model diff|log|version|tag |
An optional data model: what node types, facts and edges the graph allows, and how it changed |
check |
Validate the files against each other and the model; lists possible duplicates |
diff |
What changed between two git revisions |
hook install, ci |
A pre-commit hook and a GitHub Actions workflow that run check and refuse destructive model changes |
From Python
from gitgraf import At, Graph
graph = Graph.open("registry")
node = graph.node("hornsea-2")
facts = graph.facts(node.id, At(valid_at="2022-01", known_at="2024"))
Graph.nx(at) returns a frozen networkx.MultiDiGraph of what is in view.
Building on it
A package on top keeps its own names with gitgraf.settings.configure(cli=..., package=..., markers=...), called before gitgraf.cli is imported, and adds its own commands to gitgraf.cli.app. gitgraf.hooks.checks and gitgraf.hooks.rewrites let it check and maintain its own sections of the marker file.
Development
uv sync
uv run pytest
Metadata
Release files for gitgraf 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| gitgraf-0.2.0.tar.gz | 65.5 kB | Without provenance | Details for gitgraf-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| gitgraf-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for gitgraf-0.2.0-py3-none-any.whl |
Total release size: 139.1 kB
Release files / gitgraf-0.2.0.tar.gz
| Download URL | gitgraf-0.2.0.tar.gz |
|---|---|
| Size | 65.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
caa2ce28889e83687cc8de6f38d02202b2abc3be6bd588659d0fbcc5f9f492eb
|
|
BLAKE2b-256 checksum How to use checksums |
3e35bebe2f813fc1b186cde1f86d92651a3677fba820b65ff1dc5c13f7d5b8c0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.2
|
Release files / gitgraf-0.2.0-py3-none-any.whl
| Download URL | gitgraf-0.2.0-py3-none-any.whl |
|---|---|
| Size | 73.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c0bd9b26e436488bc97ddd6041c3a40d7764bf933f0365f4c674e18fda9a88d7
|
|
BLAKE2b-256 checksum How to use checksums |
296efa54fcfd0313df7a27d623cedb29598bba7aba10e522c8f8aafb6b0d3b6f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.2
|
Security for gitgraf 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.