git_meta_lib/
lib.rs

1//! # gmeta
2//!
3//! A library for storing and exchanging structured metadata in Git repositories.
4//! This is the reference implementation of the [gmeta spec](https://git-meta.com/).
5//!
6//! ## Core Concepts
7//!
8//! gmeta attaches key-value metadata to **targets** in a Git project:
9//!
10//! - **Commits** — attach agent info, review status, provenance to specific commits
11//! - **Paths** — attach code ownership, agent rules to directories or files
12//! - **Branches** — attach review comments, CI status to branches
13//! - **Change IDs** — attach metadata to logical changesets (for tools like Jujutsu)
14//! - **Project** — global project-wide metadata (configuration, ownership)
15//!
16//! Values can be **strings** (single values), **lists** (ordered, append-friendly),
17//! or **sets** (unordered, unique members).
18//!
19//! ## Quick Start
20//!
21//! ```no_run
22//! use git_meta_lib::{Session, Target, MetaValue};
23//!
24//! // Open a session for the current git repository
25//! let session = Session::discover()?;
26//! // or Session::open(path)?
27//!
28//! // Write metadata
29//! let commit = session.target(&Target::commit("abc123")?);
30//! commit.set("agent:model", "claude-4.6")?;
31//! commit.set("review:status", "approved")?;
32//!
33//! // Read metadata
34//! if let Some(model) = commit.get_value("agent:model")? {
35//!     println!("Model: {model}");
36//! }
37//!
38//! // Sync with remote
39//! session.serialize()?;
40//! session.push_once(None)?;
41//! # Ok::<(), git_meta_lib::Error>(())
42//! ```
43//!
44//! ## Data Exchange
45//!
46//! Metadata is stored locally in SQLite for fast reads/writes, and exchanged
47//! via Git's object format and transfer protocols:
48//!
49//! - [`Session::serialize()`] writes local metadata to a Git tree and commit
50//! - [`Session::materialize()`] reads remote metadata and merges it locally
51//! - [`Session::pull()`] fetches + materializes in one step
52//! - [`Session::push_once()`] serializes + pushes to the remote
53//!
54//! The exchange format uses Git trees with a deterministic path layout, enabling
55//! standard Git merge strategies. See the [spec](https://git-meta.com/)
56//! for the full format description.
57//!
58//! ## Blobless Clone Support
59//!
60//! For large metadata histories (e.g., AI transcripts), gmeta supports Git's
61//! partial/blobless clone feature. Only tree objects are fetched initially;
62//! blob data is fetched on demand when accessed. The [`Session::pull()`] method
63//! automatically indexes historical keys for lazy loading.
64
65/// Typed error types for all gmeta operations.
66pub mod error;
67
68/// The library entry point: a session combining a git repo with a metadata store.
69pub mod session;
70/// Session-scoped target handle with automatic email and timestamp.
71pub mod session_handle;
72/// Core metadata types: targets, value types, and path-building helpers.
73pub mod types;
74
75// Modules that are `pub(crate)` by default, `pub` with the `internal` feature.
76// The CLI enables this feature; library consumers do not.
77
78#[cfg(not(feature = "internal"))]
79pub(crate) mod db;
80#[cfg(feature = "internal")]
81pub mod db;
82
83#[cfg(not(feature = "internal"))]
84pub(crate) mod git_utils;
85#[cfg(feature = "internal")]
86pub mod git_utils;
87
88#[cfg(not(feature = "internal"))]
89pub(crate) mod list_value;
90#[cfg(feature = "internal")]
91pub mod list_value;
92
93#[cfg(not(feature = "internal"))]
94pub(crate) mod materialize;
95#[cfg(feature = "internal")]
96pub mod materialize;
97
98#[cfg(not(feature = "internal"))]
99pub(crate) mod prune;
100#[cfg(feature = "internal")]
101pub mod prune;
102
103#[cfg(not(feature = "internal"))]
104pub(crate) mod pull;
105#[cfg(feature = "internal")]
106pub mod pull;
107
108#[cfg(not(feature = "internal"))]
109pub(crate) mod push;
110#[cfg(feature = "internal")]
111pub mod push;
112
113#[cfg(not(feature = "internal"))]
114pub(crate) mod serialize;
115#[cfg(feature = "internal")]
116pub mod serialize;
117
118#[cfg(not(feature = "internal"))]
119pub(crate) mod sync;
120#[cfg(feature = "internal")]
121pub mod sync;
122
123#[cfg(not(feature = "internal"))]
124pub(crate) mod tree;
125#[cfg(feature = "internal")]
126pub mod tree;
127
128#[cfg(not(feature = "internal"))]
129pub(crate) mod tree_paths;
130#[cfg(feature = "internal")]
131pub mod tree_paths;
132
133// Public API re-exports: these are visible regardless of feature flags.
134// The `pub use` makes specific types public even when the source module
135// is `pub(crate)`.
136
137pub use error::{Error, Result};
138pub use list_value::ListEntry;
139pub use session::Session;
140pub use session_handle::SessionTargetHandle;
141pub use types::{MetaEdit, MetaValue, Target, TargetType, ValueType};
142
143// Workflow output types
144pub use materialize::{MaterializeOutput, MaterializeRefResult, MaterializeStrategy};
145pub use pull::PullOutput;
146pub use push::PushOutput;
147pub use serialize::SerializeOutput;
git_meta_lib/lib.rs

git_meta_lib/
lib.rs
