zig-git
Reading and writing git repositories in Zig, without running git.
Star
Fork
Watch
1 1 0
Files
.forgejo
docs
LICENSES
src
tools
.gitignore
build.zig
build.zig.zon
CONTRIBUTING.md
flake.lock
flake.nix
GLOSSARY.md
package.nix
README.md
REUSE.toml
README.md

zig-git #

A library for reading git repositories from Zig 0.17 without running git, written in Zig alone: no libgit2, no C zlib, nothing to link. It is meant to answer the questions a history browser asks git — what a commit holds, what a revision range means, what a diff says — with the same answers git gives, and to grow into writing to repositories and talking to remote ones.

It is early. Nothing works yet.

The API documentation is generated from the doc comments and published at https://jeff.jcollie.page/zig-git/.

What it is for #

grebe, a history browser for git, reads repositories by running git log and git show. zig-git is being written so that it can stop: the plan is a library in layers, each depending only on the ones before it.

  1. Core — the object database (loose objects, packs, the multi-pack index, alternates), the ref store (loose refs, packed-refs, reftable, reflogs), configuration with includes, discovering a repository the way git does, and the index file.
  2. Revision — revision arguments in git's own syntax, and walking the history they choose: ranges, path limiting, the three orderings, mailmap, replace refs, grafts.
  3. Diff — between trees, the index and the working tree, producing patches byte-identical to git's.
  4. Write and transport, later: ref transactions, writing objects, signing, and git's protocol v2 over file://, ssh:// and https://.

Three choices run through all of it, and the decision records in docs/adr/ give the reasons:

  • Agreeing with git is the definition of correct. The tests build their repositories with git and compare answers with it, and patches are to match git's byte for byte.
  • What it does not support, it says so. A revision argument outside the supported set is an error naming it, and a repository using an extension it does not implement is refused, so a caller can fall back to git rather than receive an answer that is nearly right.
  • It is written from git's documentation and behavior, never its source, so that it can be MIT licensed.

The words used for the things in a repository — object ID, object format, object database, ref store, git directory — are defined in GLOSSARY.md.

Building and testing #

Everything is pinned in the Nix flake, Zig and the git the tests compare against included:

nix develop
zig build test --summary all   # every repository test runs with SHA-1 and SHA-256
zig build docs-serve           # the API documentation on http://localhost:8000

CONTRIBUTING.md says more.

Where this lives #

The canonical repository is on my Forgejo instance, and Tangled carries a mirror of it:

git clone https://git.jcollie.dev/jeff/zig-git.git

Report issues and send pull requests to the Tangled mirror. CI and the published documentation come from the Forgejo repository.

License #

MIT; see LICENSES/MIT.txt. The project follows REUSE.

References cited #