Struct git_repository::easy::Handle

pub struct Handle {
    pub refs: RefStore,
    pub objects: OdbHandle,
    /* private fields */
}

State for use in Easy* to provide mutable parts of a repository such as caches and buffers.

Note that it clones itself so that it is empty, requiring the user to configure each clone separately, specifically and explicitly. This is to have the fastest-possible default configuration available by default, but allow those who experiment with workloads to get speed boosts of 2x or more.

Fields

refs: RefStore

A ref store with shared ownership (or the equivalent of it).

objects: OdbHandle

A way to access objects.

Implementations

impl Handle

Methods related to object creation.

pub fn find_object(
    &self,
    id: impl Into<ObjectId>
) -> Result<Object<'_>, Error<Error>>

Find the object with id in the object database or return an error if it could not be found.

There are various legitimate reasons for an object to not be present, which is why try_find_object(…) might be preferable instead.

Important

As a shared buffer is written to back the object data, the returned ObjectRef will prevent other find_object() operations from succeeding while alive. To bypass this limit, clone this easy::Handle instance.

Performance Note

In order to get the kind of the object, is must be fully decoded from storage if it is packed with deltas. Loose object could be partially decoded, even though that’s not implemented.

pub fn try_find_object(
    &self,
    id: impl Into<ObjectId>
) -> Result<Option<Object<'_>>, Error>

Try to find the object with id or return None it it wasn’t found.

Important

As a shared buffer is written to back the object data, the returned ObjectRef will prevent other try_find_object() operations from succeeding while alive. To bypass this limit, clone this easy::Handle instance.

pub fn write_object(&self, object: impl WriteTo) -> Result<Oid<'_>, Error>

Write the given object into the object database and return its object id.

pub fn tag(
    &self,
    name: impl AsRef<str>,
    target: impl AsRef<oid>,
    target_kind: Kind,
    tagger: Option<&SignatureRef<'_>>,
    message: impl AsRef<str>,
    constraint: PreviousValue
) -> Result<Reference<'_>, Error>

Create a tag reference named name (without refs/tags/ prefix) pointing to a newly created tag object which in turn points to target and return the newly created reference.

It will be created with constraint which is most commonly to only create it or to force overwriting a possibly existing tag.

pub fn commit<Name, E>(
    &self,
    reference: Name,
    author: &SignatureRef<'_>,
    committer: &SignatureRef<'_>,
    message: impl AsRef<str>,
    tree: impl Into<ObjectId>,
    parents: impl IntoIterator<Item = impl Into<ObjectId>>
) -> Result<Oid<'_>, Error> where
    Name: TryInto<FullName, Error = E>,
    Error: From<E>, 

Create a new commit object with author, committer and message referring to tree with parents, and point reference to it. The commit is written without message encoding field, which can be assumed to be UTF-8.

reference will be created if it doesn’t exist, and can be "HEAD" to automatically write-through to the symbolic reference that HEAD points to if it is not detached. For this reason, detached head states cannot be created unless the HEAD is detached already. The reflog will be written as canonical git would do, like <operation> (<detail>): <summary>.

The first parent id in parents is expected to be the current target of reference and the operation will fail if it is not. If there is no parent, the reference is expected to not exist yet.

The method fails immediately if a reference lock can’t be acquired.

impl Handle

Obtain and alter references comfortably

pub fn tag_reference(
    &self,
    name: impl AsRef<str>,
    target: impl Into<ObjectId>,
    constraint: PreviousValue
) -> Result<Reference<'_>, Error>

Create a lightweight tag with given name (and without refs/tags/ prefix) pointing to the given target, and return it as reference.

It will be created with constraint which is most commonly to only create it or to force overwriting a possibly existing tag.

pub fn namespace(&self) -> Option<&Namespace>

Returns the currently set namespace for references, or None if it is not set.

Namespaces allow to partition references, and is configured per Easy.

pub fn clear_namespace(&mut self) -> Option<Namespace>

Remove the currently set reference namespace and return it, affecting only this Easy.

pub fn set_namespace<'a, Name, E>(
    &mut self,
    namespace: Name
) -> Result<Option<Namespace>, Error> where
    Name: TryInto<PartialNameRef<'a>, Error = E>,
    Error: From<E>, 

Set the reference namespace to the given value, like "foo" or "foo/bar".

Note that this value is shared across all Easy… instances as the value is stored in the shared Repository.

pub fn reference<Name, E>(
    &self,
    name: Name,
    target: impl Into<ObjectId>,
    constraint: PreviousValue,
    log_message: impl Into<BString>
) -> Result<Reference<'_>, Error> where
    Name: TryInto<FullName, Error = E>,
    Error: From<E>, 

Create a new reference with name, like refs/heads/branch, pointing to target, adhering to constraint during creation and writing log_message into the reflog. Note that a ref-log will be written even if log_message is empty.

The newly created Reference is returned.

pub fn edit_reference(
    &self,
    edit: RefEdit,
    lock_mode: Fail,
    log_committer: Option<&Signature>
) -> Result<Vec<RefEdit>, Error>

Edit a single reference as described in edit, handle locks via lock_mode and write reference logs as log_committer.

One or more RefEdits are returned - symbolic reference splits can cause more edits to be performed. All edits have the previous reference values set to the ones encountered at rest after acquiring the respective reference’s lock.

pub fn edit_references(
    &self,
    edits: impl IntoIterator<Item = RefEdit>,
    lock_mode: Fail,
    log_committer: Option<&Signature>
) -> Result<Vec<RefEdit>, Error>

Edit one or more references as described by their edits, with lock_mode deciding on how to handle competing transactions. log_committer is the name appearing in reference logs.

Returns all reference edits, which might be more than where provided due the splitting of symbolic references, and whose previous (old) values are the ones seen on in storage after the reference was locked.

pub fn head(&self) -> Result<Head<'_>, Error>

Return the repository head, an abstraction to help dealing with the HEAD reference.

The HEAD reference can be in various states, for more information, the documentation of Head.

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

Find the reference with the given partial or full name, like main, HEAD, heads/branch or origin/other, or return an error if it wasn’t found.

Consider try_find_reference(…) if the reference might not exist without that being considered an error.

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

Return a platform for iterating references.

Common kinds of iteration are all or prefixed references.

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

Try to find the reference named name, like main, heads/branch, HEAD or origin/other, and return it.

Otherwise return None if the reference wasn’t found. If the reference is expected to exist, use find_reference().

impl Handle

The catch-all of extension traits.

pub fn committer(&self) -> Signature

Return the committer as configured by this repository, which is determined by…

• …the git configuration…
• …the GIT_(AUTHOR|COMMITTER)_(NAME|EMAIL|DATE) environment variables…

…and in that order.

pub fn object_hash(&self) -> Kind

The kind of object hash the repository is configured to use.

impl Handle

Configure how caches are used to speed up various git repository operations

pub fn object_cache_size(&mut self, bytes: impl Into<Option<usize>>)

Sets the amount of space used at most for caching most recently accessed fully decoded objects, to Some(bytes), or None to deactivate it entirely.

Note that it is unset by default but can be enabled once there is time for performance optimization. Well-chosen cache sizes can improve performance particularly if objects are accessed multiple times in a row. The cache is configured to grow gradually.

Note that a cache on application level should be considered as well as the best object access is not doing one.

pub fn apply_environment(self) -> Self

Read well-known environment variables related to caches and apply them to this instance, but not to clones of it - each needs their own configuration.

Note that environment configuration never fails due to invalid environment values, but it should be used with caution as it could be used to cause high memory consumption.

Use the GITOXIDE_DISABLE_PACK_CACHE environment variable to turn off any pack cache, which can be beneficial when it’s known that the cache efficiency is low. Use GITOXIDE_PACK_CACHE_MEMORY=512MB to use up to 512MB of RAM for the pack delta base cache. If none of these are set, the default cache is fast enough to nearly never cause a (marginal) slow-down while providing some gains most of the time. Note that the value given is per-thread.

Use the GITOXIDE_OBJECT_CACHE_MEMORY=16mb to set the given amount of memory to store full objects, on a per-thread basis.

impl Handle

Access

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

Return the work tree containing all checked out files, if there is one.

Trait Implementations

impl Clone for Handle

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl From<&'_ Repository> for Handle

fn from(repo: &Repository) -> Self

Performs the conversion.

impl From<Repository> for Handle

fn from(repo: Repository) -> Self

Performs the conversion.