Struct git_repository::Repository

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

A thread-local handle to interact with a repository from a single thread.

It is Send but not Sync - for the latter you can convert it to_sync(). 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 Repository

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 object_cache_size_if_unset(&mut self, bytes: usize)

Set an object cache of size bytes if none is set.

Use this method to avoid overwriting any existing value while assuring better performance in case no value is set.

impl Repository

pub fn transport_options<'a>( &self, url: impl Into<&'a BStr>, remote_name: Option<&BStr> ) -> Result<Option<Box<dyn Any>>, Error>

Available on crate features blocking-network-client or async-network-client only.

Produce configuration suitable for url, as differentiated by its protocol/scheme, to be passed to a transport instance via [configure()][git_transport::client::TransportWithoutIO::configure()] (via &**config to pass the contained Any and not the Box). None is returned if there is no known configuration. If remote_name is not None, the remote’s name may contribute to configuration overrides, typically for the HTTP transport.

Note that the caller may cast the instance themselves to modify it before passing it on.

For transports that support proxy authentication, the default authentication method will be used with the url of the proxy if it contains a user name.

impl Repository

pub fn remote_names(&self) -> BTreeSet<&str>

Returns a sorted list unique of symbolic names of remotes that we deem trustworthy.

pub fn remote_default_name(&self, direction: Direction) -> Option<Cow<'_, str>>

Obtain the branch-independent name for a remote for use in the given direction, or None if it could not be determined.

For fetching, use the only configured remote, or default to origin if it exists. For pushing, use the remote.pushDefault trusted configuration key, or fall back to the rules for fetching.

Notes

It’s up to the caller to determine what to do if the current head is unborn or detached.

impl Repository

pub fn branch_names(&self) -> BTreeSet<&str>

Return a set of unique short branch names for which custom configuration exists in the configuration, if we deem them trustworthy.

pub fn branch_remote_ref<'a>( &self, short_branch_name: impl Into<&'a BStr> ) -> Option<Result<Cow<'_, FullNameRef>, ValidateNameError>>

Returns the validated reference on the remote associated with the given short_branch_name, always main instead of refs/heads/main.

The returned reference is the one we track on the remote side for merging and pushing. Returns None if the remote reference was not found. May return an error if the reference is invalid.

pub fn branch_remote_name<'a>( &self, short_branch_name: impl Into<&'a BStr> ) -> Option<Name<'_>>

Returns the unvalidated name of the remote associated with the given short_branch_name, typically main instead of refs/heads/main. In some cases, the returned name will be an URL. Returns None if the remote was not found or if the name contained illformed UTF-8.

See also Reference::remote_name() for a more typesafe version to be used when a Reference is available.

impl Repository

General Configuration

pub fn config_snapshot(&self) -> Snapshot<'_>

Return a snapshot of the configuration as seen upon opening the repository.

pub fn config_snapshot_mut(&mut self) -> SnapshotMut<'_>

Return a mutable snapshot of the configuration as seen upon opening the repository, starting a transaction. When the returned instance is dropped, it is applied in full, even if the reason for the drop is an error.

Note that changes to the configuration are in-memory only and are observed only the this instance of the Repository.

pub fn open_options(&self) -> &Options

The options used to open the repository.

pub fn ssh_connect_options(&self) -> Result<Options, Error>

Available on crate feature blocking-network-client only.

Obtain options for use when connecting via ssh.

pub fn object_hash(&self) -> Kind

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

impl Repository

Identity handling.

Deviation

There is no notion of a default user like in git, and instead failing to provide a user is fatal. That way, we enforce correctness and force application developers to take care of this issue which can be done in various ways, for instance by setting gitoxide.committer.nameFallback and similar.

pub fn committer(&self) -> Option<Result<SignatureRef<'_>, Error>>

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

• …the git configuration committer.name|email…
• …the GIT_COMMITTER_(NAME|EMAIL|DATE) environment variables…
• …the configuration for user.name|email as fallback…

…and in that order, or None if no committer name or email was configured, or Some(Err(…)) if the committer date could not be parsed.

Note

The values are cached when the repository is instantiated.

pub fn author(&self) -> Option<Result<SignatureRef<'_>, Error>>

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

• …the git configuration author.name|email…
• …the GIT_AUTHOR_(NAME|EMAIL|DATE) environment variables…
• …the configuration for user.name|email as fallback…

…and in that order, or None if there was nothing configured.

Note

The values are cached when the repository is instantiated.

impl Repository

pub fn into_sync(self) -> ThreadSafeRepository

Convert this instance into a ThreadSafeRepository by dropping all thread-local data.

impl Repository

pub fn git_dir(&self) -> &Path

Return the path to the repository itself, containing objects, references, configuration, and more.

Synonymous to path().

pub fn git_dir_trust(&self) -> Trust

The trust we place in the git-dir, with lower amounts of trust causing access to configuration to be limited.

pub fn common_dir(&self) -> &Path

Returns the main git repository if this is a repository on a linked work-tree, or the git_dir itself.

pub fn index_path(&self) -> PathBuf

Return the path to the worktree index file, which may or may not exist.

pub fn path(&self) -> &Path

The path to the .git directory itself, or equivalent if this is a bare repository.

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

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

pub fn install_dir(&self) -> Result<PathBuf>

The directory of the binary path of the current process.

pub fn prefix(&self) -> Option<Result<PathBuf>>

Returns the relative path which is the components between the working tree and the current working dir (CWD). Note that there may be None if there is no work tree, even though the PathBuf will be empty if the CWD is at the root of the work tree.

pub fn kind(&self) -> Kind

Return the kind of repository, either bare or one with a work tree.

impl Repository

Methods related to object creation.

pub fn find_object(&self, id: impl Into<ObjectId>) -> Result<Object<'_>, 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.

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.

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

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

pub fn write_blob(&self, bytes: impl AsRef<[u8]>) -> Result<Id<'_>, Error>

Write a blob from the given bytes.

pub fn write_blob_stream(&self, bytes: impl Read + Seek) -> Result<Id<'_>, Error>

Write a blob from the given Read implementation.

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_as<'a, 'c, Name, E>( &self, committer: impl Into<SignatureRef<'c>>, author: impl Into<SignatureRef<'a>>, reference: Name, message: impl AsRef<str>, tree: impl Into<ObjectId>, parents: impl IntoIterator<Item = impl Into<ObjectId>> ) -> Result<Id<'_>, Error>where Name: TryInto<FullName, Error = E>, Error: From<E>,

Similar to commit(…), but allows to create the commit with committer and author specified.

This forces setting the commit time and author time by hand. Note that typically, committer and author are the same.

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

Create a new commit object with 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. author and committer fields are pre-set from the configuration, which can be altered temporarily before the call if required.

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.

pub fn empty_tree(&self) -> Tree<'_>

Return an empty tree object, suitable for getting changes.

Note that it is special and doesn’t physically exist in the object database even though it can be returned. This means that this object can be used in an uninitialized, empty repository which would report to have no objects at all.

impl Repository

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<&'a PartialNameRef, 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) -> Result<Vec<RefEdit>, Error>

Edit a single reference as described in edit, 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> ) -> Result<Vec<RefEdit>, Error>

Edit one or more references as described by their edits. Note that one can set the committer name for use in the ref-log by temporarily overriding the git-config.

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 head_id(&self) -> Result<Id<'_>, Error>

Resolve the HEAD reference, follow and peel its target and obtain its object id.

Note that this may fail for various reasons, most notably because the repository is freshly initialized and doesn’t have any commits yet.

Also note that the returned id is likely to point to a commit, but could also point to a tree or blob. It won’t, however, point to a tag as these are always peeled.

pub fn head_name(&self) -> Result<Option<FullName>, Error>

Return the name to the symbolic reference HEAD points to, or None if the head is detached.

The difference to head_ref() is that the latter requires the reference to exist, whereas here we merely return a the name of the possibly unborn reference.

pub fn head_ref(&self) -> Result<Option<Reference<'_>>, Error>

Return the reference that HEAD points to, or None if the head is detached or unborn.

pub fn head_commit(&self) -> Result<Commit<'_>, Error>

Return the commit object the HEAD reference currently points to after peeling it fully.

Note that this may fail for various reasons, most notably because the repository is freshly initialized and doesn’t have any commits yet. It could also fail if the head does not point to a commit.

pub fn find_reference<'a, Name, E>( &self, name: Name ) -> Result<Reference<'_>, Error>where Name: TryInto<&'a PartialNameRef, 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<&'a PartialNameRef, 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 Repository

pub fn remote_at<Url, E>(&self, url: Url) -> Result<Remote<'_>, Error>where Url: TryInto<Url, Error = E>, Error: From<E>,

Create a new remote available at the given url.

It’s configured to fetch included tags by default, similar to git. See with_fetch_tags(…) for a way to change it.

pub fn remote_at_without_url_rewrite<Url, E>( &self, url: Url ) -> Result<Remote<'_>, Error>where Url: TryInto<Url, Error = E>, Error: From<E>,

Create a new remote available at the given url similarly to remote_at(), but don’t rewrite the url according to rewrite rules. This eliminates a failure mode in case the rewritten URL is faulty, allowing to selectively apply rewrite rules later and do so non-destructively.

pub fn find_remote<'a>( &self, name_or_url: impl Into<&'a BStr> ) -> Result<Remote<'_>, Error>

Find the remote with the given name_or_url or report an error, similar to try_find_remote(…).

Note that we will obtain remotes only if we deem them trustworthy.

pub fn find_default_remote( &self, direction: Direction ) -> Option<Result<Remote<'_>, Error>>

Find the default remote as configured, or None if no such configuration could be found.

See remote_default_name() for more information on the direction parameter.

pub fn try_find_remote<'a>( &self, name_or_url: impl Into<&'a BStr> ) -> Option<Result<Remote<'_>, Error>>

Find the remote with the given name_or_url or return None if it doesn’t exist, for the purpose of fetching or pushing data to a remote.

There are various error kinds related to partial information or incorrectly formatted URLs or ref-specs. Also note that the created Remote may have neither fetch nor push ref-specs set at all.

Note that ref-specs are de-duplicated right away which may change their order. This doesn’t affect matching in any way as negations/excludes are applied after includes.

We will only include information if we deem it trustworthy.

pub fn try_find_remote_without_url_rewrite<'a>( &self, name_or_url: impl Into<&'a BStr> ) -> Option<Result<Remote<'_>, Error>>

Similar to try_find_remote(), but removes a failure mode if rewritten URLs turn out to be invalid as it skips rewriting them. Use this in conjunction with Remote::rewrite_urls() to non-destructively apply the rules and keep the failed urls unchanged.

impl Repository

Methods for resolving revisions by spec or working with the commit graph.

pub fn rev_parse<'a>(&self, spec: impl Into<&'a BStr>) -> Result<Spec<'_>, Error>

Parse a revision specification and turn it into the object(s) it describes, similar to git rev-parse.

Deviation

• @ actually stands for HEAD, whereas git resolves it to the object pointed to by HEAD without making the HEAD ref available for lookups.

pub fn rev_parse_single<'repo, 'a>( &'repo self, spec: impl Into<&'a BStr> ) -> Result<Id<'repo>, Error>

Parse a revision specification and return single object id as represented by this instance.

pub fn rev_walk( &self, tips: impl IntoIterator<Item = impl Into<ObjectId>> ) -> Platform<'_>

Create the baseline for a revision walk by initializing it with the tips to start iterating on.

It can be configured further before starting the actual walk.

impl Repository

pub fn open_mailmap(&self) -> Snapshot

Similar to open_mailmap_into(), but ignores all errors and returns at worst an empty mailmap, e.g. if there is no mailmap or if there were errors loading them.

This represents typical usage within git, which also works with what’s there without considering a populated mailmap a reason to abort an operation, considering it optional.

pub fn open_mailmap_into(&self, target: &mut Snapshot) -> Result<(), Error>

Try to merge mailmaps from the following locations into target:

• read the .mailmap file without following symlinks from the working tree, if present
• OR read HEAD:.mailmap if this repository is bare (i.e. has no working tree), if the mailmap.blob is not set.
• read the mailmap as configured in mailmap.blob, if set.
• read the file as configured by mailmap.file, following symlinks, if set.

Only the first error will be reported, and as many source mailmaps will be merged into target as possible. Parsing errors will be ignored.

impl Repository

pub fn state(&self) -> Option<InProgress>

Returns the status of an in progress operation on a repository or None if no operation is currently in progress.

Note to be confused with the repositories ‘status’.

impl Repository

Worktree iteration

pub fn worktrees(&self) -> Result<Vec<Proxy<'_>>>

Return a list of all linked worktrees sorted by private git dir path as a lightweight proxy.

Note that these need additional processing to become usable, but provide a first glimpse a typical worktree information.

impl Repository

Interact with individual worktrees and their information.

pub fn main_repo(&self) -> Result<Repository, Error>

Return the repository owning the main worktree, typically from a linked worktree.

Note that it might be the one that is currently open if this repository doesn’t point to a linked worktree. Also note that the main repo might be bare.

pub fn worktree(&self) -> Option<Worktree<'_>>

Return the currently set worktree if there is one, acting as platform providing a validated worktree base path.

Note that there would be None if this repository is bare and the parent Repository was instantiated without registered worktree in the current working dir.

pub fn is_bare(&self) -> bool

Return true if this repository is bare, and has no main work tree.

This is not to be confused with the worktree() worktree, which may exists if this instance was opened in a worktree that was created separately.

pub fn open_index(&self) -> Result<File, Error>

Open a new copy of the index file and decode it entirely.

It will use the index.threads configuration key to learn how many threads to use. Note that it may fail if there is no index.

pub fn index(&self) -> Result<Index, Error>

Return a shared worktree index which is updated automatically if the in-memory snapshot has become stale as the underlying file on disk has changed.

The index file is shared across all clones of this repository.

Trait Implementations

impl Clone for Repository

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Repository

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

Formats the value using the given formatter.

impl From<&ThreadSafeRepository> for Repository

fn from(repo: &ThreadSafeRepository) -> Self

Converts to this type from the input type.

impl From<PrepareCheckout> for Repository

fn from(prep: PrepareCheckout) -> Self

Converts to this type from the input type.

impl From<PrepareFetch> for Repository

fn from(prep: PrepareFetch) -> Self

Converts to this type from the input type.

impl From<Repository> for ThreadSafeRepository

fn from(r: Repository) -> Self

Converts to this type from the input type.

impl From<ThreadSafeRepository> for Repository

fn from(repo: ThreadSafeRepository) -> Self

Converts to this type from the input type.

impl PartialEq<Repository> for Repository

fn eq(&self, other: &Repository) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.