Skip to main content

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)

Source distribution for gitgraf 0.2.0
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)

Table of built distributions (wheels) for gitgraf 0.2.0
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page