Struct gix_ref::file::Store

pub struct Store {
    pub write_reflog: WriteReflog,
    pub namespace: Option<Namespace>,
    pub prohibit_windows_device_names: bool,
    pub precompose_unicode: bool,
    /* 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

prohibit_windows_device_names: bool

This is only needed on Windows, where some device names are reserved at any level of a path, so that reading or writing refs/heads/CON for example would read from the console, or write to it.

precompose_unicode: bool

If set, we will convert decomposed unicode like a\u308 into precomposed unicode like ä when reading ref names from disk. Note that this is an internal operation that isn’t observable on the outside, but it’s needed for lookups to packed-refs or symlinks to work correctly. Iterated references will be returned verbatim, thus when sending them over the wire they have to be precomposed as needed.

Implementations

impl Store

Mutation

pub fn set_packed_buffer_mmap_threshold(&mut self, bytes: u64) -> u64

Set the amount of bytes needed for the .git/packed-refs file to be memory mapped. Returns the previous value, which is always 32KB.

impl Store

Access

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: &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: PathBuf, _: Options) -> Self

Create a new instance at the given git_dir, which commonly is a standard git repository with a refs/ subdirectory. Use Options to adjust settings.

Note that if precompose_unicode is set in the options, the git_dir is also expected to use precomposed unicode, or else some operations that strip prefixes will fail.

pub fn for_linked_worktree( git_dir: PathBuf, common_dir: PathBuf, _: Options ) -> Self

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

Note that if precompose_unicode is set, the git_dir and common_dir are also expected to use precomposed unicode, or else some operations that strip prefixes will fail.

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.

Note that since packed-refs are storing refs as precomposed unicode if Self::precompose_unicode is true, for consistency we also return loose references as precomposed unicode.

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 themselves.

pub fn iter_prefixed_packed<'s, 'p>( &'s self, prefix: &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

Finding References - notes about precomposed unicode.

Generally, ref names and the target of symbolic refs are stored as-is if Self::precompose_unicode is false. If true, refs are stored as precomposed unicode in packed-refs, but stored as is on disk as it is then assumed to be indifferent, i.e. "a\u{308}" is the same as "ä".

This also means that when refs are packed for transmission to another machine, both their names and the target of symbolic references need to be precomposed.

Namespaces are left as is as they never get past the particular repository that uses them.

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 force_refresh_packed_buffer(&self) -> Result<(), Error>

Forcefully reload the packed refs buffer.

This method should be used if it’s clear that the buffer on disk has changed, to make the latest changes visible before other operations are done on this instance.

As some filesystems don’t have nanosecond granularity, changes are likely to be missed if they happen within one second otherwise.

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).

Note that it will automatically be memory mapped if it exceeds the default threshold of 32KB. Change the threshold with file::Store::set_packed_buffer_mmap_threshold().

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.