Trait QueryStore

pub trait QueryStore<Ref, T: Send> {
    type Error;

    // Required methods
    fn get_refs<Spec>(
        &self,
        targets: impl IntoIterator<Item = Spec>,
        transport: Option<&mut T>,
    ) -> Result<impl IntoIterator<Item = Ref>, Self::Error>
       where Spec: AsRef<BStr>;
    fn get_transport(&self) -> Result<T, Self::Error>;
    fn get_ref<Spec>(
        &self,
        target: Spec,
        transport: Option<&mut T>,
    ) -> Result<Ref, Self::Error>
       where Spec: AsRef<BStr>;
}

A trait for querying remote stores to retrieve references.

This trait provides a unified interface for querying references from remote stores. It supports different query strategies depending on the implementation.

Examples

use atom::store::QueryStore;
use gix::Url;

// Lightweight reference query
let url = gix::url::parse("https://github.com/example/repo.git".into())?;
let refs = url.get_refs(["main", "refs/tags/v1.0"], None)?;
for ref_info in refs {
    let (name, target, peeled) = ref_info.unpack();
    println!("Ref: {}, Target: {}", name, peeled.or(target).unwrap());
}

Required Associated Types

type Error

The error type representing errors which can occur during query operations.

Required Methods

fn get_refs<Spec>( &self, targets: impl IntoIterator<Item = Spec>, transport: Option<&mut T>, ) -> Result<impl IntoIterator<Item = Ref>, Self::Error>

where Spec: AsRef<BStr>,

Query a remote store for multiple references.

This method retrieves information about the requested references from the remote store. The exact network behavior depends on the implementation.

Arguments

• targets - An iterator of reference specifications (e.g., “main”, “refs/tags/v1.0”)
• transport - An optional mutable reference to a persistent transport (obtained by QueryStore::get_transport). If omitted an ephemeral connection is established.

Returns

An iterator over the requested references, or an error if the query fails.

fn get_transport(&self) -> Result<T, Self::Error>

Establish a persistent connection to a git server.

fn get_ref<Spec>( &self, target: Spec, transport: Option<&mut T>, ) -> Result<Ref, Self::Error>

where Spec: AsRef<BStr>,

Query a remote store for a single reference.

This is a convenience method that queries for a single reference and returns the first result. See [get_refs] for details on network behavior.

Arguments

• target - The reference specification to query (e.g., “main”, “refs/tags/v1.0”)
• transport - An optional mutable reference to a persistent transport (obtained by QueryStore::get_transport). If omitted an ephemeral connection is established.

Returns

The requested reference, or an error if not found or if the query fails.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementations on Foreign Types

impl QueryStore<Ref, Box<dyn Transport + Send>> for Url

fn get_refs<Spec>( &self, targets: impl IntoIterator<Item = Spec>, transport: Option<&mut Box<dyn Transport + Send>>, ) -> Result<impl IntoIterator<Item = Ref>, <Self as QueryStore<Ref, Box<dyn Transport + Send>>>::Error>

where Spec: AsRef<BStr>,

Efficiently queries git references from a remote repository URL.

This implementation performs a lightweight network operation that only retrieves reference information (branch/tag names and their commit IDs) without downloading the actual repository objects. This makes it ideal for scenarios where you need to check reference existence or get commit IDs without the overhead of a full repository fetch.

Network Behavior

• Lightweight: Only queries reference metadata, not repository content
• Fast: Minimal network overhead compared to full fetch operations
• Efficient: Suitable for checking reference existence and getting commit IDs

Use Cases

• Checking if specific branches or tags exist on a remote
• Getting commit IDs for references without downloading objects
• Lightweight remote repository inspection

Performance

This is significantly faster than the [gix::Remote] implementation since it avoids downloading actual git objects, making it appropriate for read-only reference queries.

type Error = Error

fn get_transport(&self) -> Result<Box<dyn Transport + Send>, Self::Error>

fn get_ref<Spec>( &self, target: Spec, transport: Option<&mut Box<dyn Transport + Send>>, ) -> Result<Ref, Self::Error>

where Spec: AsRef<BStr>,

impl<'repo> QueryStore<Ref, Box<dyn Transport + Send>> for Remote<'repo>

fn get_refs<Spec>( &self, references: impl IntoIterator<Item = Spec>, transport: Option<&mut Box<dyn Transport + Send>>, ) -> Result<impl IntoIterator<Item = Ref>, <Self as QueryStore<Ref, Box<dyn Transport + Send>>>::Error>

where Spec: AsRef<BStr>,

Performs a full git fetch operation to retrieve references and repository data.

This implementation executes a complete git fetch operation, which downloads both reference information and the actual repository objects (commits, trees, blobs) from the remote. This provides full access to the repository content but is significantly more expensive than the URL-based implementation.

Network Behavior

• Heavyweight: Performs a full git fetch operation, downloading all objects
• Complete: Provides access to the entire repository state after fetching
• Expensive: Higher network usage and longer execution time

Use Cases

• When you need to access repository content after fetching references
• When working with local repositories that need to sync with remotes
• When you require the complete repository state, not just reference metadata

Performance

This implementation is slower and uses more network bandwidth than the [gix::Url] implementation because it downloads actual git objects. Use it only when you need access to repository content beyond reference metadata.

Progress Reporting

The fetch operation includes progress reporting for sync and initialization phases. Progress is displayed when the log level is set above WARN.

type Error = Error

fn get_transport(&self) -> Result<Box<dyn Transport + Send>, Self::Error>

fn get_ref<Spec>( &self, target: Spec, transport: Option<&mut Box<dyn Transport + Send>>, ) -> Result<Ref, Self::Error>

where Spec: AsRef<BStr>,

Implementors