Crate git_meta_lib

Expand description

§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()?;
// or Session::open(path)?

// 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)?;

§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::MetaEdit;
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.