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.

Plugins

A graph can bring its own rules, so that the commands above enforce them and no second command line is needed. It names the plugins in its marker file:

plugins: [energyassets]

A plugin is a module that an installed package registers under the entry point group gitgraf.plugins:

[project.entry-points."gitgraf.plugins"]
energyassets = "energyassets.plugin"

It can define either or both of:

  • check(graph) -> list[str]: problems reported along with the graph's own, by gitgraf check, the pre-commit hook and the CI workflow.
  • new_node(graph, type, name) -> dict | None: what a node being created starts with, as {"id": ..., "facts": {...}}, for ids that are minted and facts every node has from birth. gitgraf add node and gitgraf import both use it.

Only a graph that names a plugin runs it, and only an installed package that registers one can be named. A plugin that is named but not installed is an error, so its checks are never skipped silently.

A fact the model marks identity: true is the node's own (a uuid, a serial number): when the node is merged into another, it is retired with the node and the other keeps its own.

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.3.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.3.0
File Size Uploaded Provenance Actions
gitgraf-0.3.0.tar.gz 67.7 kB Without provenance Details for gitgraf-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for gitgraf 0.3.0
File Interpreter ABI Platform Actions
gitgraf-0.3.0-py3-none-any.whl Python 3 none any Details for gitgraf-0.3.0-py3-none-any.whl

Total release size: 143.9 kB

Release files / gitgraf-0.3.0.tar.gz

Download URL gitgraf-0.3.0.tar.gz
Size 67.7 kB
Tags Source
SHA-256 checksum
How to use checksums
11c3c538a0fe51f5899ad8765efd5199c02c6cd17436a6d6447aa60531db74cf
BLAKE2b-256 checksum
How to use checksums
1a51207213e7c480ea0ed58eb7ac687b73bd884c90e427258616721593053ea3
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.3.0-py3-none-any.whl

Download URL gitgraf-0.3.0-py3-none-any.whl
Size 76.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ad7b37ff49810061970b9d1d86ab3b6cc0d004d0b989d914ebe0c1421886dd4b
BLAKE2b-256 checksum
How to use checksums
3d7781dd056fa93298b2ca70aa14ff93fc0e859ca222ac712a0baafe2c84c8bf
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.3.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