Struct References

Source

pub struct References<'repo> { /* private fields */ }

Expand description

Resolve, list, and update refs for one open repository.

Implementations§

Source §

impl<'repo> References<'repo>

Source

pub fn new(repo: &'repo Repository) -> Self

Bind ref operations to repo.

Source

pub fn repository(&self) -> &'repo Repository

Underlying repository.

Source

pub fn resolve(&self, name: &RefName) -> Result<ObjectId>

Resolve a ref name to an object id, following symbolic refs.

§Errors

Propagates ref store and resolution errors.

§Examples

use grit_lib::refs::store::RefName;
use grit_lib::repo::{InitOptions, Repository};
use grit_lib::ident::Signature;
use grit_lib::porcelain::commit::{create_commit, CommitRequest};
use grit_lib::progress::NullProgress;
let dir = std::env::temp_dir().join("grit-refs-resolve-doc");
let repo = Repository::init(&dir, &InitOptions::default())?;
let mut req = CommitRequest::new("doc");
req.author = Some(Signature::new("Doc", "doc@example.com", repo.identity_now())?);
req.committer = Some(Signature::new("Doc", "doc@example.com", repo.identity_now())?);
req.allow_empty = true;
let _ = create_commit(&repo, &req, &mut NullProgress, &grit_lib::progress::NeverCancel)?;
let main = RefName::try_from("refs/heads/main").expect("valid ref");
let head = repo.references().resolve(&main)?;
assert!(!head.to_hex().is_empty());

Source

pub fn list(&self, prefix: &str) -> Result<Vec<(String, ObjectId)>>

List refs under prefix (for example "refs/heads/"), sorted by name.

§Errors

Propagates ref store iteration errors.

Source

pub fn query( &self, query: &RefQuery, options: &RefQueryOptions, ) -> Result<Vec<RefListing>, RefQueryError>

List refs matching query (patterns, sort, limit) through this repository’s ref store.

§Errors

Returns RefQueryError when the ref store cannot be read, when creator-date sort is requested without object data, or when an object read fails.

Source

pub fn update(&self, name: &RefName, oid: &ObjectId) -> Result<()>

Point name at oid, creating parent directories as needed.

Uses the RefStore installed on this repository (including injected in-memory stores), not a fresh open from git_dir alone.

oid must be stored in this repository, and must be a commit when name is a branch (refs/heads/…) or HEAD. This catches a commit that a concurrent prune deleted after you wrote it, instead of leaving the ref pointing at a missing object.

§Errors

RefStoreError::MissingObject when the repository does not store oid.
RefStoreError::NotACommit when name is a branch or HEAD and oid is not a commit.
Validation, locking, and I/O errors from the ref backend.

The two object errors are returned as crate::error::Error::RefStore. The ref is unchanged on error.

§Examples

use grit_lib::refs::store::RefName;
use grit_lib::repo::{InitOptions, Repository};
use grit_lib::ident::Signature;
use grit_lib::porcelain::commit::{create_commit, CommitRequest};
use grit_lib::progress::NullProgress;
let dir = std::env::temp_dir().join("grit-refs-write-doc");
let repo = Repository::init(&dir, &InitOptions::default())?;
let mut req = CommitRequest::new("doc");
req.author = Some(Signature::new("Doc", "doc@example.com", repo.identity_now())?);
req.committer = Some(Signature::new("Doc", "doc@example.com", repo.identity_now())?);
req.allow_empty = true;
let commit = create_commit(&repo, &req, &mut NullProgress, &grit_lib::progress::NeverCancel)?.oid;
let name = RefName::try_from("refs/heads/handle-demo").expect("valid ref");
repo.references().update(&name, &commit)?;
assert_eq!(repo.references().resolve(&name)?, commit);