Crate git_meta_lib 

gmeta

A library for storing and exchanging structured metadata in Git repositories. This is the reference implementation of the gmeta spec.

Core Concepts

gmeta attaches key-value metadata to targets in a Git project:

• Commits — attach agent info, review status, provenance to specific commits
• Paths — attach code ownership, agent rules to directories or files
• Branches — attach review comments, CI status to branches
• Change IDs — attach metadata to logical changesets (for tools like Jujutsu)
• Project — global project-wide metadata (configuration, ownership)

Values can be strings (single values), lists (ordered, append-friendly), or sets (unordered, unique members).

Quick Start

use git_meta_lib::{Session, Target, MetaValue};

// Open a session for the current git repository
let session = Session::discover()?;

// Write metadata
let commit = session.target(&Target::commit("abc123")?);
commit.set("agent:model", "claude-4.6")?;
commit.set("review:status", "approved")?;

// Read metadata
if let Some(model) = commit.get_value("agent:model")? {
    println!("Model: {model}");
}

// Sync with remote
session.serialize()?;
session.push_once(None)?;

If you already have a gix::Repository (e.g. in a host application like GitButler), clone it cheaply and pass it in:

let repo = gix::open(".")?;
let session = Session::open(repo.clone())?;
// `repo` is still fully usable here

Data Exchange

Metadata is stored locally in SQLite for fast reads/writes, and exchanged via Git’s object format and transfer protocols:

• Session::serialize() writes local metadata to a Git tree and commit
• Session::materialize() reads remote metadata and merges it locally
• Session::pull() fetches + materializes in one step
• Session::push_once() serializes + pushes to the remote

The exchange format uses Git trees with a deterministic path layout, enabling standard Git merge strategies. See the spec for the full format description.

Blobless Clone Support

For large metadata histories (e.g., AI transcripts), gmeta supports Git’s partial/blobless clone feature. Only tree objects are fetched initially; blob data is fetched on demand when accessed. The Session::pull() method automatically indexes historical keys for lazy loading.

Re-exports

pub use error::Error;

pub use error::Result;

pub use session::Session;

pub use session_handle::SessionTargetHandle;

pub use types::MetaValue;

pub use types::Target;

pub use types::TargetType;

pub use types::ValueType;

Modules

error

Typed error types for all gmeta operations.

session

The library entry point: a session combining a git repo with a metadata store.

session_handle

Session-scoped target handle with automatic email and timestamp.

types

Core metadata types: targets, value types, and path-building helpers.

Structs

ListEntry

A single timestamped entry in a metadata list value.

MaterializeOutput

Result of a materialize operation.

MaterializeRefResult

Result of materializing a single remote ref.

PullOutput

Result of a pull operation.

PushOutput

Result of a single push attempt.

SerializeOutput

Result of a serialize operation.

Enums

MaterializeStrategy

How a remote ref was materialized.