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.1

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.1
File Size Uploaded Provenance Actions
gitgraf-0.2.1.tar.gz 65.6 kB Without provenance Details for gitgraf-0.2.1.tar.gz

Built distribution (wheel)

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

Total release size: 139.3 kB

Release files / gitgraf-0.2.1.tar.gz

Download URL gitgraf-0.2.1.tar.gz
Size 65.6 kB
Tags Source
SHA-256 checksum
How to use checksums
1f8d0f359fe1f90623bda86dbcfd562a5fad5a585b03df435507242d37633c7b
BLAKE2b-256 checksum
How to use checksums
1434c506d8b8e1ac649ead8eac59792e1f754270fc6c87ccb8df73f2015ffdce
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.1-py3-none-any.whl

Download URL gitgraf-0.2.1-py3-none-any.whl
Size 73.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6c249e0918efb2f29eda4d72ee73e77625f3ecec874ef660476d2dca4750acdb
BLAKE2b-256 checksum
How to use checksums
20265dda6cc9d4c8e48091c220a49ef73d8d0c79896f820ab0445ae080709e8a
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.1

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