Struct Session 

pub struct Session { /* private fields */ }

A session combining a Git repository with its gmeta metadata store.

This is the primary entry point for gmeta consumers. It owns the gix::Repository, the SQLite Store, and resolved configuration values (namespace, user email).

Timestamps

By default, workflow operations use the wall clock for timestamps. For deterministic tests, call with_timestamp() to pin all operations to a fixed time:

let session = Session::discover()?.with_timestamp(1_700_000_000_000);
session.serialize()?; // uses the fixed timestamp

Example

use git_meta_lib::Session;

let session = Session::discover()?;
println!("email: {}", session.email());
println!("namespace: {}", session.namespace());

Implementations

impl Session

pub fn discover() -> Result<Self>

Discover a git repository from the current directory and open its metadata store.

Walks upward from the current directory to find a .git directory, reads user.email and meta.namespace from git config, and opens (or creates) the SQLite database at .git/git-meta.sqlite.

pub fn open(repo: Repository) -> Result<Self>

Open a session for a known repository.

Use this when you already have a gix::Repository handle (e.g. from a host application like GitButler that manages its own repo lifetime).

If you need to keep using the repository after creating a session, pass repo.clone() — gix::Repository is cheaply cloneable since its object database and ref store are behind Arc.

Example

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

pub fn with_timestamp(self, timestamp_ms: i64) -> Self

Pin all workflow operations to a fixed timestamp.

The value is milliseconds since the Unix epoch. When set, now() returns this value instead of the wall clock. Useful for deterministic tests and replay scenarios.

pub fn namespace(&self) -> &str

The metadata namespace (from git config meta.namespace, default "meta").

Used to construct ref paths like refs/{namespace}/local/main.

pub fn email(&self) -> &str

The user email from git config user.email.

Used for authorship tracking on metadata mutations.

pub fn name(&self) -> &str

The user name from git config user.name.

Used for commit signatures during serialization.

pub fn target(&self, target: &Target) -> SessionTargetHandle<'_>

Create a scoped handle for operations on a specific target.

The handle carries the session’s email and timestamp, so write operations don’t need them as parameters:

let handle = session.target(&Target::parse("commit:abc123")?);
handle.set_value("key", &MetaValue::String("value".into()))?;

pub fn resolve_target(&self, target: &Target) -> Result<Target>

Resolve a target’s partial commit SHA using this session’s repository.

Returns a new target with the full SHA if the target was a partial commit, or a clone of the original target otherwise.

pub fn resolve_remote(&self, remote: Option<&str>) -> Result<String>

Resolve which metadata remote to use.

If remote is Some, validates that it is a configured meta remote. If None, returns the first configured meta remote.

Parameters

• remote: optional remote name to validate; if None, the first configured metadata remote is returned

Returns

The name of the resolved meta remote.

Errors

Returns Error::NoRemotes if no meta remotes are configured, or Error::RemoteNotFound if the specified name is not a meta remote.

pub fn serialize(&self) -> Result<SerializeOutput>

Serialize local metadata to Git tree(s) and commit(s).

Determines incremental vs full mode automatically. Applies filter routing and pruning rules. Updates local refs and the materialization timestamp.

pub fn serialize_with_progress( &self, progress: impl FnMut(SerializeProgress), ) -> Result<SerializeOutput>

Serialize local metadata and report progress through a callback.

Parameters

• progress: callback invoked at major serialization steps.

pub fn serialize_full(&self) -> Result<SerializeOutput>

Serialize local metadata by rebuilding from the complete SQLite state.

This bypasses incremental dirty-target detection while still avoiding a new commit when the rebuilt tree is identical to the current serialized ref. Applies filter routing and pruning rules. Updates local refs and the materialization timestamp when serialization succeeds.

pub fn serialize_full_with_progress( &self, progress: impl FnMut(SerializeProgress), ) -> Result<SerializeOutput>

Serialize all local metadata and report progress through a callback.

Parameters

• progress: callback invoked at major serialization steps.

pub fn materialize(&self, remote: Option<&str>) -> Result<MaterializeOutput>

Materialize remote metadata into the local store.

For each matching remote ref, determines the merge strategy and applies changes. Updates tracking refs and materialization timestamp.

Parameters

• remote: optional remote name filter. If None, all remotes are materialized.

pub fn pull(&self, remote: Option<&str>) -> Result<PullOutput>

Pull metadata from remote: fetch, materialize, and index history.

Resolves the remote, fetches the metadata ref, hydrates tip blobs, serializes local state for merge, materializes remote changes, and indexes historical keys for lazy loading.

Parameters

• remote: optional remote name to pull from. If None, the first configured metadata remote is used.

pub fn push_once(&self, remote: Option<&str>) -> Result<PushOutput>

Serialize and attempt a single push to the remote.

Returns the result of the push attempt. On non-fast-forward failure, the caller is responsible for calling resolve_push_conflict() and retrying.

Parameters

• remote: optional remote name to push to. If None, the first configured metadata remote is used.

pub fn push_once_with_progress( &self, remote: Option<&str>, progress: impl FnMut(PushProgress), ) -> Result<PushOutput>

Serialize and attempt a single push to the remote, reporting progress.

Parameters

• remote: optional remote name. If None, the first configured metadata remote is used.
• progress: callback invoked before long-running push phases.

Errors

Returns an error if serialization, ref inspection, rebasing, or pushing fails.

pub fn resolve_push_conflict(&self, remote: Option<&str>) -> Result<()>

After a failed push, fetch remote changes, materialize, re-serialize, and rebase local ref for clean fast-forward.

Call this between push retries.

Parameters

• remote: optional remote name. If None, the first configured metadata remote is used.

pub fn resolve_push_conflict_with_progress( &self, remote: Option<&str>, progress: impl FnMut(PushProgress), ) -> Result<()>

Resolve a failed push and report progress.

Parameters

• remote: optional remote name. If None, the first configured metadata remote is used.
• progress: callback invoked before long-running conflict resolution phases.

Errors

Returns an error if fetch, hydration, materialization, serialization, or rebase fails.