Struct git_ref::file::Store

pub struct Store {
    pub write_reflog: WriteReflog,
    pub namespace: Option<Namespace>,
    /* private fields */
}

A store for reference which uses plain files.

Each ref is represented as a single file on disk in a folder structure that follows the relative path used to identify references.

Fields

write_reflog: WriteReflog

The way to handle reflog edits

namespace: Option<Namespace>

The namespace to use for edits and reads

Implementations

impl Store

pub fn git_dir(&self) -> &Path

Return the .git directory at which all references are loaded.

For worktrees, this is the linked work-tree private ref location, then common_dir() is Some(parent_git_dir).

pub fn common_dir(&self) -> Option<&Path>

If this is a linked work tree, there will be Some(git_dir) pointing to the parent repository, while git_dir() points to the location holding linked work-tree private references.

pub fn common_dir_resolved(&self) -> &Path

Similar to common_dir(), but it will produce either the common-dir, or the git-dir if the former isn’t present.

This is also the directory in which the packed references file would be placed.

impl Store

pub fn reflog_exists<'a, Name, E>(&self, name: Name) -> Result<bool, E>where
    Name: TryInto<&'a FullNameRef, Error = E>,
    Error: From<E>,

Returns true if a reflog exists for the given reference name.

Please note that this method shouldn’t be used to check if a log exists before trying to read it, but instead is meant to be the fastest possible way to determine if a log exists or not. If the caller needs to know if it’s readable, try to read the log instead with a reverse or forward iterator.

pub fn reflog_iter_rev<'a, 'b, Name, E>(
    &self,
    name: Name,
    buf: &'b mut [u8]
) -> Result<Option<Reverse<'b, File>>, Error>where
    Name: TryInto<&'a FullNameRef, Error = E>,
    Error: From<E>,

Return a reflog reverse iterator for the given fully qualified name, reading chunks from the back into the fixed buffer buf.

The iterator will traverse log entries from most recent to oldest, reading the underlying file in chunks from the back. Return Ok(None) if no reflog exists.

pub fn reflog_iter<'a, 'b, Name, E>(
    &self,
    name: Name,
    buf: &'b mut Vec<u8>
) -> Result<Option<Forward<'b>>, Error>where
    Name: TryInto<&'a FullNameRef, Error = E>,
    Error: From<E>,

Return a reflog forward iterator for the given fully qualified name and write its file contents into buf.

The iterator will traverse log entries from oldest to newest. Return Ok(None) if no reflog exists.

impl Store

pub fn loose_iter(&self) -> Result<LooseThenPacked<'_, '_>>

Return an iterator over all loose references, notably not including any packed ones, in lexical order. Each of the references may fail to parse and the iterator will not stop if parsing fails, allowing the caller to see all files that look like references whether valid or not.

Reference files that do not constitute valid names will be silently ignored.

pub fn loose_iter_prefixed(
    &self,
    prefix: impl AsRef<Path>
) -> Result<LooseThenPacked<'_, '_>>

Return an iterator over all loose references that start with the given prefix.

Otherwise it’s similar to loose_iter().

impl Store

pub fn at(
    git_dir: impl Into<PathBuf>,
    write_reflog: WriteReflog,
    object_hash: Kind
) -> Self

Create a new instance at the given git_dir, which commonly is a standard git repository with a refs/ subdirectory. The object_hash defines which kind of hash we should recognize.

pub fn for_linked_worktree(
    git_dir: impl Into<PathBuf>,
    common_dir: impl Into<PathBuf>,
    write_reflog: WriteReflog,
    object_hash: Kind
) -> Self

Like at(), but for linked work-trees which use git_dir as private ref store and common_dir for shared references.

impl Store

pub fn iter(&self) -> Result<Platform<'_>, Error>

Return a platform to obtain iterator over all references, or prefixed ones, loose or packed, sorted by their name.

Errors are returned similarly to what would happen when loose and packed refs where iterated by themselves.

impl Store

pub fn iter_packed<'s, 'p>(
    &'s self,
    packed: Option<&'p Buffer>
) -> Result<LooseThenPacked<'p, 's>>

Return an iterator over all references, loose or packed, sorted by their name.

Errors are returned similarly to what would happen when loose and packed refs where iterated by themeselves.

pub fn iter_prefixed_packed<'s, 'p>(
    &'s self,
    prefix: impl AsRef<Path>,
    packed: Option<&'p Buffer>
) -> Result<LooseThenPacked<'p, 's>>

As iter(…), but filters by prefix, i.e. “refs/heads”.

Please note that “refs/heads` or “refs\heads” is equivalent to “refs/heads/”

impl Store

pub fn find<'a, Name, E>(&self, partial: Name) -> Result<Reference, Error>where
    Name: TryInto<&'a PartialNameRef, Error = E>,
    Error: From<E>,

Similar to file::Store::try_find() but a non-existing ref is treated as error.

pub fn find_packed<'a, Name, E>(
    &self,
    partial: Name,
    packed: Option<&Buffer>
) -> Result<Reference, Error>where
    Name: TryInto<&'a PartialNameRef, Error = E>,
    Error: From<E>,

Similar to file::Store::find(), but supports a stable packed buffer.

pub fn find_loose<'a, Name, E>(&self, partial: Name) -> Result<Reference, Error>where
    Name: TryInto<&'a PartialNameRef, Error = E>,
    Error: From<E>,

Similar to file::Store::find() won’t handle packed-refs.

impl Store

pub fn try_find<'a, Name, E>(
    &self,
    partial: Name
) -> Result<Option<Reference>, Error>where
    Name: TryInto<&'a PartialNameRef, Error = E>,
    Error: From<E>,

Find a single reference by the given path which is required to be a valid reference name.

Returns Ok(None) if no such ref exists.

Note

• The lookup algorithm follows the one in the git documentation.
• The packed buffer is checked for modifications each time the method is called. See file::Store::try_find_packed() for a version with more control.

pub fn try_find_loose<'a, Name, E>(
    &self,
    partial: Name
) -> Result<Option<Reference>, Error>where
    Name: TryInto<&'a PartialNameRef, Error = E>,
    Error: From<E>,

Similar to file::Store::find() but a non-existing ref is treated as error.

Find only loose references, that is references that aren’t in the packed-refs buffer. All symbolic references are loose references. HEAD is always a loose reference.

pub fn try_find_packed<'a, Name, E>(
    &self,
    partial: Name,
    packed: Option<&Buffer>
) -> Result<Option<Reference>, Error>where
    Name: TryInto<&'a PartialNameRef, Error = E>,
    Error: From<E>,

Similar to file::Store::find(), but allows to pass a snapshotted packed buffer instead.

impl Store

Edits

pub fn transaction(&self) -> Transaction<'_, '_>

Open a transaction with the given edits, and determine how to fail if a lock cannot be obtained. A snapshot of packed references will be obtained automatically if needed to fulfill this transaction and will be provided as result of a successful transaction. Note that upon transaction failure, packed-refs will never have been altered.

The transaction inherits the parent namespace.

impl Store

pub fn open_packed_buffer(&self) -> Result<Option<Buffer>, Error>

Try to open a new packed buffer. It’s not an error if it doesn’t exist, but yields Ok(None).

pub fn cached_packed_buffer(
    &self
) -> Result<Option<SharedBufferSnapshot>, Error>

Return a possibly cached packed buffer with shared ownership. At retrieval it will assure it’s up to date, but after that it can be considered a snapshot as it cannot change anymore.

Use this to make successive calls to file::Store::try_find_packed() or obtain iterators using file::Store::iter_packed() in a way that assures the packed-refs content won’t change.

pub fn packed_refs_path(&self) -> PathBuf

Return the path at which packed-refs would usually be stored

Trait Implementations

impl Clone for Store

fn clone(&self) -> Store

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Store

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.