Struct 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 using Repository::into_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.

Send only with parallel feature

When built with default-features = false, this type is not Send. The minimal feature set to activate Send is features = ["parallel"].

Fields

refs: RefStore

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

objects: OdbHandle

A way to access objects.

Implementations

impl Repository

pub fn attributes( &self, index: &State, attributes_source: Source, ignore_source: Source, exclude_overrides: Option<Search>, ) -> Result<AttributeStack<'_>, Error>

Available on (crate features attributes or excludes) and crate feature attributes only.

Configure a file-system cache for accessing git attributes and excludes on a per-path basis.

Use attribute_source to specify where to read attributes from. Also note that exclude information will always try to read .gitignore files from disk before trying to read it from the index.

Note that no worktree is required for this to work, even though access to in-tree .gitattributes and .gitignore files would require a non-empty index that represents a git tree.

This takes into consideration all the usual repository configuration, namely:

• $XDG_CONFIG_HOME/…/ignore|attributes if core.excludesFile|attributesFile is not set, otherwise use the configured file.
• $GIT_DIR/info/exclude|attributes if present.

pub fn attributes_only( &self, index: &State, attributes_source: Source, ) -> Result<AttributeStack<'_>, Error>

Available on (crate features attributes or excludes) and crate feature attributes only.

Like attributes(), but without access to exclude/ignore information.

pub fn excludes( &self, index: &State, overrides: Option<Search>, source: Source, ) -> Result<AttributeStack<'_>, Error>

Available on (crate features attributes or excludes) and crate feature excludes only.

Configure a file-system cache checking if files below the repository are excluded, reading .gitignore files from the specified source.

Note that no worktree is required for this to work, even though access to in-tree .gitignore files would require a non-empty index that represents a tree with .gitignore files.

This takes into consideration all the usual repository configuration, namely:

• $XDG_CONFIG_HOME/…/ignore if core.excludesFile is not set, otherwise use the configured file.
• $GIT_DIR/info/exclude if present.

When only excludes are desired, this is the most efficient way to obtain them. Otherwise use Repository::attributes() for accessing both attributes and excludes.

impl Repository

pub fn blame_file( &self, file_path: &BStr, suspect: impl Into<ObjectId>, options: Options, ) -> Result<Outcome, Error>

Available on crate feature blame only.

Produce a list of consecutive gix_blame::BlameEntry instances. Each BlameEntry corresponds to a hunk of consecutive lines of the file at suspect:<file_path> that got introduced by a specific commit.

For details, see the documentation of gix_blame::file().

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.

pub fn compute_object_cache_size_for_tree_diffs(&self, index: &State) -> usize

Available on crate feature index only.

Return the amount of bytes the object cache should be set to to perform diffs between trees who are similar to index in a typical source code repository.

Currently, this allocates about 10MB for every 10k files in index, and a minimum of 4KB.

impl Repository

Handling of InMemory object writing

pub fn with_object_memory(self) -> Self

When writing objects, keep them in memory instead of writing them to disk. This makes any change to the object database non-persisting, while keeping the view to the object database consistent for this instance.

impl Repository

pub fn checkout_options( &self, attributes_source: Source, ) -> Result<Options, Error>

Available on crate feature worktree-mutation only.

Return options that can be used to drive a low-level checkout operation. Use attributes_source to determine where .gitattributes files should be read from, which depends on the presence of a worktree to begin with. Here, typically this value would be gix_worktree::stack::state::attributes::Source::IdMapping

impl Repository

Query configuration related to branches.

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.

Note

Branch names that have illformed UTF-8 will silently be skipped.

pub fn branch_remote_ref_name( &self, name: &FullNameRef, direction: Direction, ) -> Option<Result<Cow<'_, FullNameRef>, Error>>

Returns the validated reference name of the upstream branch on the remote associated with the given name, which will be used when merging. The returned value corresponds to the branch.<short_branch_name>.merge configuration key for remote::Direction::Fetch. For the push direction the Git configuration is used for a variety of different outcomes, similar to what would happen when running git push <name>.

Returns None if there is nothing configured, or if no remote or remote ref is configured.

Note

The returned name refers to what Git calls upstream branch (as opposed to upstream tracking branch). The value is also fast to retrieve compared to its tracking branch.

See also Reference::remote_ref_name().

pub fn branch_remote_tracking_ref_name( &self, name: &FullNameRef, direction: Direction, ) -> Option<Result<Cow<'_, FullNameRef>, Error>>

Return the validated name of the reference that tracks the corresponding reference of name on the remote for direction. Note that a branch with that name might not actually exist.

• with remote being remote::Direction::Fetch, we return the tracking branch that is on the destination side of a src:dest refspec. For instance, with name being main and the default refspec refs/heads/*:refs/remotes/origin/*, refs/heads/main would match and produce refs/remotes/origin/main.
• with remote being remote::Direction::Push, we return the tracking branch that corresponds to the remote branch that we would push to. For instance, with name being main and no setup at all, we would push to refs/heads/main on the remote. And that one would be fetched matching the refs/heads/*:refs/remotes/origin/* fetch refspec, hence refs/remotes/origin/main is returned. Note that push refspecs can be used to map main to other (using a push refspec refs/heads/main:refs/heads/other), which would then lead to refs/remotes/origin/other to be returned instead.

Note that if there is an ambiguity, that is if name maps to multiple tracking branches, the first matching mapping is returned, according to the order in which the fetch or push refspecs occur in the configuration file.

See also Reference::remote_tracking_ref_name().

pub fn upstream_branch_and_remote_for_tracking_branch( &self, tracking_branch: &FullNameRef, ) -> Result<Option<(FullName, Remote<'_>)>, Error>

Given a local tracking_branch name, find the remote that maps to it along with the name of the branch on the side of the remote, also called upstream branch.

Return Ok(None) if there is no remote with fetch-refspecs that would match tracking_branch on the right-hand side, or Err if the matches were ambiguous.

Limitations

A single valid mapping is required as fine-grained matching isn’t implemented yet. This means that

pub fn branch_remote_name<'a>( &self, short_branch_name: impl Into<&'a BStr>, direction: Direction, ) -> 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.

• if direction is remote::Direction::Fetch, we will query the branch.<short_name>.remote configuration.
• if direction is remote::Direction::Push, the push remote will be queried by means of branch.<short_name>.pushRemote or remote.pushDefault as fallback.

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

short_branch_name can typically be obtained by shortening a full branch name.

pub fn branch_remote<'a>( &self, short_branch_name: impl Into<&'a BStr>, direction: Direction, ) -> Option<Result<Remote<'_>, Error>>

Like branch_remote_name(…), but returns a Remote. short_branch_name is the name to use for looking up branch.<short_branch_name>.* values in the configuration.

See also Reference::remote().

impl Repository

Query configuration related to remotes.

pub fn remote_names(&self) -> Names<'_>

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

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

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

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 this instance of the Repository.

pub fn filesystem_options(&self) -> Result<Capabilities, Error>

Return filesystem options as retrieved from the repository configuration.

Note that these values have not been probed.

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

Available on crate feature index only.

Return filesystem options on how to perform stat-checks, typically in relation to the index.

Note that these values have not been probed.

pub fn open_options(&self) -> &Options

The options used to open the repository.

pub fn big_file_threshold(&self) -> Result<u64, Error>

Return the big-file threshold above which Git will not perform a diff anymore or try to delta-diff packs, as configured by core.bigFileThreshold, or the default value.

pub fn ignore_pattern_parser(&self) -> Result<Ignore, Error>

Available on crate feature excludes only.

Create a low-level parser for ignore patterns, for instance for use in excludes().

Depending on the configuration, precious-file parsing in .gitignore-files is supported. This means that $ prefixed files will be interpreted as precious, which is a backwards-incompatible change.

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

Available on crate feature attributes only.

Return the context to be passed to any spawned program that is supposed to interact with the repository, like hooks or filters.

pub fn object_hash(&self) -> Kind

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

pub fn diff_algorithm(&self) -> Result<Algorithm, Error>

Available on crate feature blob-diff only.

Return the algorithm to perform diffs or merges with.

In case of merges, a diff is performed under the hood in order to learn which hunks need merging.

impl Repository

Diff-utilities

pub fn diff_resource_cache( &self, mode: Mode, worktree_roots: WorktreeRoots, ) -> Result<Platform, Error>

Available on crate feature blob-diff only.

Create a resource cache for diffable objects, and configured with everything it needs to know to perform diffs faithfully just like git would. mode controls what version of a resource should be diffed. worktree_roots determine if files can be read from the worktree, where each side of the diff operation can be represented by its own worktree root. .gitattributes are automatically read from the worktree if at least one worktree is present.

Note that attributes will always be obtained from the current HEAD index even if the resources being diffed might live in another tree. Further, if one of the worktree_roots are set, attributes will also be read from the worktree. Otherwise, it will be skipped and attributes are read from the index tree instead.

pub fn diff_tree_to_tree<'a, 'old_repo: 'a, 'new_repo: 'a>( &self, old_tree: impl Into<Option<&'a Tree<'old_repo>>>, new_tree: impl Into<Option<&'a Tree<'new_repo>>>, options: impl Into<Option<Options>>, ) -> Result<Vec<ChangeDetached>, Error>

Available on crate feature blob-diff only.

Produce the changes that would need to be applied to old_tree to create new_tree. If options are unset, they will be filled in according to the git configuration of this repository, and with full paths being tracked as well, which typically means that rewrite tracking might be disabled if done so explicitly by the user. If options are set, the user can take full control over the settings.

Note that this method exists to evoke similarity to git2, and makes it easier to fully control diff settings. A more fluent version may be used as well.

pub fn diff_resource_cache_for_tree_diff(&self) -> Result<Platform, Error>

Available on crate feature blob-diff only.

Return a resource cache suitable for diffing blobs from trees directly, where no worktree checkout exists.

For more control, see diff_resource_cache().

impl Repository

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

Available on crate feature dirwalk only.

Return default options suitable for performing a directory walk on this repository.

Used in conjunction with dirwalk()

pub fn dirwalk( &self, index: &State, patterns: impl IntoIterator<Item = impl AsRef<BStr>>, should_interrupt: &AtomicBool, options: Options, delegate: &mut dyn Delegate, ) -> Result<Outcome<'_>, Error>

Available on crate feature dirwalk only.

Perform a directory walk configured with options under control of the delegate. Use patterns to further filter entries. should_interrupt is polled to see if an interrupt is requested, causing an error to be returned instead.

The index is used to determine if entries are tracked, and for excludes and attributes lookup. Note that items will only count as tracked if they have the gix_index::entry::Flags::UPTODATE flag set.

Note that dirwalks for the purpose of deletion will be initialized with the worktrees of this repository if they fall into the working directory of this repository as well to mark them as tracked. That way it’s hard to accidentally flag them for deletion. This is intentionally not the case when deletion is not intended so they look like untracked repositories instead.

See gix_dir::walk::delegate::Collect for a delegate that collects all seen entries.

pub fn dirwalk_iter( &self, index: impl Into<IndexPersistedOrInMemory>, patterns: impl IntoIterator<Item = impl Into<BString>>, should_interrupt: OwnedOrStaticAtomicBool, options: Options, ) -> Result<Iter, Error>

Available on crate feature dirwalk only.

Create an iterator over a running traversal, which stops if the iterator is dropped. All arguments are the same as in dirwalk().

should_interrupt should be set to Default::default() if it is supposed to be unused. Otherwise, it can be created by passing a &'static AtomicBool, &Arc<AtomicBool> or Arc<AtomicBool>.

impl Repository

pub fn filter_pipeline( &self, tree_if_bare: Option<ObjectId>, ) -> Result<(Pipeline<'_>, IndexPersistedOrInMemory), Error>

Available on crate feature attributes only.

Configure a pipeline for converting byte buffers to the worktree representation, and byte streams to the git-internal representation. Also return the index that was used when initializing the pipeline as it may be useful when calling convert_to_git(). Bare repositories will either use HEAD^{tree} for accessing all relevant worktree files or the given tree_if_bare.

Note that this is considered a primitive as it operates on data directly and will not have permanent effects. We also return the index that was used to configure the attributes cache (for accessing .gitattributes), which can be reused after it was possibly created from a tree, an expensive operation.

Performance

Note that when in a repository with worktree, files in the worktree will be read with priority, which causes at least a stat each time the directory is changed. This can be expensive if access isn’t in sorted order, which would cause more then necessary stats: one per directory.

impl Repository

Freelist configuration

The free-list is an internal and ‘transparent’ mechanism for obtaining and re-using memory buffers when reading objects. That way, trashing is avoided as buffers are re-used and re-written.

However, there are circumstances when releasing memory early is preferred, for instance on the server side.

Also note that the free-list isn’t cloned, so each clone of this instance starts with an empty one.

pub fn empty_reusable_buffer(&self) -> Buffer<'_>

Return an empty buffer which is tied to this repository instance, and reuse its memory allocation by keeping it around even after it drops.

pub fn set_freelist( &mut self, list: Option<Vec<Vec<u8>>>, ) -> Option<Vec<Vec<u8>>>

Set the currently used freelist to list. If None, it will be disabled entirely.

Return the currently previously allocated free-list, a list of reusable buffers typically used when reading objects. May be None if there was no free-list.

pub fn without_freelist(self) -> Self

A builder method to disable the free-list on a newly created instance.

impl Repository

pub fn revision_graph<'cache, T>( &self, cache: Option<&'cache Graph>, ) -> Graph<'_, 'cache, T>

Create a graph data-structure capable of accelerating graph traversals and storing state of type T with each commit it encountered.

Note that the cache will be used if present, and it’s best obtained with commit_graph_if_enabled().

Note that a commitgraph is only allowed to be used if core.commitGraph is true (the default), and that configuration errors are ignored as well.

Performance

Note that the Graph can be sensitive to various object database settings that may affect the performance of the commit walk.

pub fn commit_graph(&self) -> Result<Graph, Error>

Return a cache for commits and their graph structure, as managed by git commit-graph, for accelerating commit walks on a low level.

Note that revision_graph() should be preferred for general purpose walks that don’t rely on the actual commit cache to be present, while leveraging the commit-graph if possible.

pub fn commit_graph_if_enabled(&self) -> Result<Option<Graph>, Error>

Return a newly opened commit-graph if it is available and enabled in the Git configuration.

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 committer_or_set_generic_fallback( &mut self, ) -> Result<SignatureRef<'_>, Error>

Return the committer or its fallback just like committer(), but if not set generate a possibly arbitrary fallback and configure it in memory on this instance. That fallback is then returned and future calls to committer() will return it as well.

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

Index access

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

Available on crate feature index only.

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>

Available on crate feature index only.

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.

Notes

• This will fail if the file doesn’t exist, like in a newly initialized repository. If that is the case, use index_or_empty() or try_index() instead.

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

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

Available on crate feature index only.

Return the shared worktree index if present, or return a new empty one which has an association to the place where the index would be.

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

Available on crate feature index only.

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, or None if no such file exists.

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

pub fn index_or_load_from_head(&self) -> Result<IndexPersistedOrInMemory, Error>

Available on crate feature index only.

Open the persisted worktree index or generate it from the current HEAD^{tree} to live in-memory only.

Use this method to get an index in any repository, even bare ones that don’t have one naturally.

Note

• The locally stored index is not guaranteed to represent HEAD^{tree} if this repository is bare - bare repos don’t naturally have an index and if an index is present it must have been generated by hand.
• This method will fail on unborn repositories as HEAD doesn’t point to a reference yet, which is needed to resolve the revspec. If that is a concern, use Self::index_or_load_from_head_or_empty() instead.

pub fn index_or_load_from_head_or_empty( &self, ) -> Result<IndexPersistedOrInMemory, Error>

Available on crate feature index only.

Open the persisted worktree index or generate it from the current HEAD^{tree} to live in-memory only, or resort to an empty index if HEAD is unborn.

Use this method to get an index in any repository, even bare ones that don’t have one naturally, or those that are in a state where HEAD is invalid or points to an unborn reference.

pub fn index_from_tree(&self, tree: &oid) -> Result<File, Error>

Available on crate feature index only.

Create new index-file, which would live at the correct location, in memory from the given tree.

Note that this is an expensive operation as it requires recursively traversing the entire tree to unpack it into the index.

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. Note that if the git-dir is trusted but the worktree is not, the result is that the git-dir is also less trusted.

pub fn current_dir(&self) -> &Path

Return the current working directory as present during the instantiation of this repository.

Note that this should be preferred over manually obtaining it as this may have been adjusted to deal with core.precomposeUnicode.

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 modules_path(&self) -> Option<PathBuf>

Available on crate feature attributes only.

The path to the .gitmodules file in the worktree, if a worktree is available.

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>

👎Deprecated: Use workdir() instead

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

pub fn set_workdir( &mut self, workdir: impl Into<Option<PathBuf>>, ) -> Result<Option<PathBuf>, Error>

Forcefully set the given workdir to be the worktree of this repository, in memory, no matter if it had one or not, or unset it with None. Return the previous working directory if one existed.

Fail if the workdir, if not None, isn’t accessible or isn’t a directory. No change is performed on error.

About Worktrees

• When setting a main worktree to a linked worktree directory, this repository instance will still claim that it is the main worktree as that depends on the git_dir, not the worktree dir.
• When setting a linked worktree to a main worktree directory, this repository instance will still claim that it is not a main worktree as that depends on the git_dir, not the worktree dir.

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

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

pub fn workdir_path(&self, rela_path: impl AsRef<BStr>) -> Option<PathBuf>

Turn rela_path into a path qualified with the workdir() of this instance, if one is available.

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

The directory of the binary path of the current process.

pub fn prefix(&self) -> Result<Option<&Path>, Error>

Returns the relative path which is the components between the working tree and the current working dir (CWD). Note that it may be None if there is no work tree, or if CWD isn’t inside of the working tree directory.

Note that the CWD is obtained once upon instantiation of the repository.

pub fn kind(&self) -> Kind

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

pub fn is_pristine(&self) -> Option<bool>

Returns Some(true) if the reference database is untouched. This typically indicates that the repository is new and empty. Return None if a defect in the database makes the answer uncertain.

impl Repository

pub fn open_mailmap(&self) -> Snapshot

Available on crate feature mailmap only.

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>

Available on crate feature mailmap only.

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

Merge-utilities

pub fn merge_resource_cache( &self, worktree_roots: WorktreeRoots, ) -> Result<Platform, Error>

Available on crate feature merge only.

Create a resource cache that can hold the three resources needed for a three-way merge. worktree_roots determines which side of the merge is read from the worktree, or from which worktree.

The platform can be used to set up resources and finally perform a merge among blobs.

Note that the current index is used for attribute queries.

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

Available on crate feature merge only.

Return options for use with gix_merge::blob::PlatformRef::merge(), accessible through merge_resource_cache().

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

Available on crate feature merge only.

Read all relevant configuration options to instantiate options for use in merge_trees().

pub fn merge_trees( &self, ancestor_tree: impl AsRef<oid>, our_tree: impl AsRef<oid>, their_tree: impl AsRef<oid>, labels: Labels<'_>, options: Options, ) -> Result<Outcome<'_>, Error>

Available on crate feature merge only.

Merge our_tree and their_tree together, assuming they have the same ancestor_tree, to yield a new tree which is provided as tree editor to inspect and finalize results at will. No change to the worktree or index is made, but objects may be written to the object database as merge results are stored. If these changes should not be observable outside of this instance, consider enabling object memory.

Note that ancestor_tree can be the empty tree hash to indicate no common ancestry.

labels are typically chosen to identify the refs or names for our_tree and their_tree and ancestor_tree respectively.

options should be initialized with tree_merge_options().

Performance

It’s highly recommended to set an object cache to avoid extracting the same object multiple times.

pub fn merge_commits( &self, our_commit: impl Into<ObjectId>, their_commit: impl Into<ObjectId>, labels: Labels<'_>, options: Options, ) -> Result<Outcome<'_>, Error>

Available on crate feature merge only.

Merge our_commit and their_commit together to yield a new tree which is provided as tree editor to inspect and finalize results at will. The merge-base will be determined automatically between both commits, along with special handling in case there are multiple merge-bases. No change to the worktree or index is made, but objects may be written to the object database as merge results are stored. If these changes should not be observable outside of this instance, consider enabling object memory.

labels are typically chosen to identify the refs or names for our_commit and their_commit, with the ancestor being set automatically as part of the merge-base handling.

options should be initialized with Repository::tree_merge_options().into().

Performance

It’s highly recommended to set an object cache to avoid extracting the same object multiple times.

pub fn virtual_merge_base( &self, merge_bases: impl IntoIterator<Item = impl Into<ObjectId>>, options: Options, ) -> Result<Outcome<'_>, Error>

Available on crate feature merge only.

Create a single virtual merge-base by merging all merge_bases into one. If the list is empty, an error will be returned as the histories are then unrelated. If there is only one commit in the list, it is returned directly with this case clearly marked in the outcome.

Note that most of options are overwritten to match the requirements of a merge-base merge, but they can be useful to control the diff algorithm or rewrite tracking, for example.

This method is useful in conjunction with Self::merge_trees(), as the ancestor tree can be produced here.

pub fn virtual_merge_base_with_graph( &self, merge_bases: impl IntoIterator<Item = impl Into<ObjectId>>, graph: &mut Graph<'_, '_, Commit<Flags>>, options: Options, ) -> Result<Outcome<'_>, Error>

Available on crate feature merge only.

Like Self::virtual_merge_base(), but also allows to reuse a graph for faster merge-base calculation, particularly if graph was used to find the merge_bases.

impl Repository

Tree editing

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

Available on crate feature tree-editor only.

Return an editor for adjusting the tree at id.

This can be the empty tree id to build a tree from scratch.

impl Repository

Find objects of various kins

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 find_commit(&self, id: impl Into<ObjectId>) -> Result<Commit<'_>, Error>

Find a commit with id or fail if there was no object or the object wasn’t a commit.

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

Find a tree with id or fail if there was no object or the object wasn’t a tree.

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

Find an annotated tag with id or fail if there was no object or the object wasn’t a tag.

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

Find a blob with id or fail if there was no object or the object wasn’t a blob.

pub fn find_header(&self, id: impl Into<ObjectId>) -> Result<Header, Error>

Obtain information about an object without fully decoding it, or fail if the object doesn’t exist.

Note that despite being cheaper than Self::find_object(), there is still some effort traversing delta-chains. Also note that for empty trees and blobs, it will always report it to exist in loose objects, even if they don’t exist or if they exist in a pack.

pub fn has_object(&self, id: impl AsRef<oid>) -> bool

Return true if id exists in the object database.

Performance

This method can be slow if the underlying object database has an unsuitable RefreshMode and id is not likely to exist. Use repo.objects.refresh_never() to avoid expensive IO-bound refreshes if an object wasn’t found.

pub fn try_find_header( &self, id: impl Into<ObjectId>, ) -> Result<Option<Header>, Error>

Obtain information about an object without fully decoding it, or None if the object doesn’t exist.

Note that despite being cheaper than Self::try_find_object(), there is still some effort traversing delta-chains.

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

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

impl Repository

Write objects of any type.

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

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

Note that we hash the object in memory to avoid storing objects that are already present. That way, we avoid writing duplicate objects using slow disks that will eventually have to be garbage collected.

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

Write a blob from the given bytes.

We avoid writing duplicate objects to slow disks that will eventually have to be garbage collected by pre-hashing the data, and checking if the object is already present.

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

Write a blob from the given Read implementation.

Note that we hash the object in memory to avoid storing objects that are already present. That way, we avoid writing duplicate objects using slow disks that will eventually have to be garbage collected.

If that is prohibitive, use the object database directly.

impl Repository

Create commits and tags

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.

Writing a commit without reference update

If the reference shouldn’t be updated, use Self::write_object() along with a newly created crate::objs::Object whose fields can be fully defined.

pub fn new_commit( &self, message: impl AsRef<str>, tree: impl Into<ObjectId>, parents: impl IntoIterator<Item = impl Into<ObjectId>>, ) -> Result<Commit<'_>, Error>

Create a new commit object with message referring to tree with parents, and write it to the object database. Do not, however, update any references.

The commit is created 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.

pub fn new_commit_as<'a, 'c>( &self, committer: impl Into<SignatureRef<'c>>, author: impl Into<SignatureRef<'a>>, message: impl AsRef<str>, tree: impl Into<ObjectId>, parents: impl IntoIterator<Item = impl Into<ObjectId>>, ) -> Result<Commit<'_>, Error>

Create a nwe commit object with message referring to tree with parents, using the specified committer and author, and write it to the object database. Do not, however, update any references.

This forces setting the commit time and author time by hand. Note that typically, committer and author are the same. The commit is created without message encoding field, which can be assumed to be UTF-8.

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

Return an empty tree object, suitable for getting changes.

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

pub fn empty_blob(&self) -> Blob<'_>

Return an empty blob object.

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

impl Repository

pub fn pathspec( &self, empty_patterns_match_prefix: bool, patterns: impl IntoIterator<Item = impl AsRef<BStr>>, inherit_ignore_case: bool, index: &State, attributes_source: Source, ) -> Result<Pathspec<'_>, Error>

Available on crate feature attributes only.

Create a new pathspec abstraction that allows to conduct searches using patterns. inherit_ignore_case should be true if patterns will match against files on disk, or false otherwise, for more natural matching (but also note that git does not do that). index may be needed to load attributes which is required only if patterns refer to attributes via :(attr:…) syntax. In the same vein, attributes_source affects where .gitattributes files are read from if pathspecs need to match against attributes. If empty_patterns_match_prefix is true, then even empty patterns will match only what’s inside of the prefix. Otherwise they will match everything.

It will be initialized exactly how it would, and attribute matching will be conducted by reading the worktree first if available. If that is not desirable, consider calling Pathspec::new() directly.

pub fn pathspec_defaults(&self) -> Result<Defaults, Error>

Available on crate feature attributes only.

Return default settings that are required when parsing pathspecs by hand.

These are stemming from environment variables which have been converted to config settings, which now serve as authority for configuration.

pub fn pathspec_defaults_inherit_ignore_case( &self, inherit_ignore_case: bool, ) -> Result<Defaults, Error>

Available on crate feature attributes only.

Similar to Self::pathspec_defaults(), but will automatically configure the returned defaults to match case-insensitively if the underlying filesystem is also configured to be case-insensitive according to core.ignoreCase, and inherit_ignore_case is true.

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, or use edit_references_as(committer) for convenience.

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 edit_references_as( &self, edits: impl IntoIterator<Item = RefEdit>, committer: Option<SignatureRef<'_>>, ) -> Result<Vec<RefEdit>, Error>

A way to apply reference edits similar to edit_references(…), but set a specific commiter for use in the reflog. It can be None if it’s the purpose edits are configured to not update the reference log, or cause a failure otherwise.

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, following symbolic references and tags until a commit is found.

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, following symbolic references and tags until a commit is found.

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

Return the tree id the HEAD reference currently points to after peeling it fully, following symbolic references and tags until a commit is found.

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

Like Self::head_tree_id(), but will return an empty tree hash if the repository HEAD is unborn.

pub fn head_tree(&self) -> Result<Tree<'_>, Error>

Return the tree object the HEAD^{tree} reference currently points to after peeling it fully, following symbolic references and tags until a tree is found.

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 tree, unlikely but possible.

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

where Name: TryInto<&'a PartialNameRef, Error = E> + Clone, 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 configured 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 configured remote with the given name_or_url or return None if it doesn’t exist, for the purpose of fetching or pushing data.

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 find_fetch_remote( &self, name_or_url: Option<&BStr>, ) -> Result<Remote<'_>, Error>

This method emulate what git fetch <remote> does in order to obtain a remote to fetch from.

As such, with name_or_url being Some, it will:

• use name_or_url verbatim if it is a URL, creating a new remote in memory as needed.
• find the named remote if name_or_url is a remote name

If name_or_url is None:

• use the current HEAD branch to find a configured remote
• fall back to either a generally configured remote or the only configured remote.

Fail if no remote could be found despite all of the above.

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>

Available on crate feature revision only.

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>

Available on crate feature revision only.

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

pub fn merge_base( &self, one: impl Into<ObjectId>, two: impl Into<ObjectId>, ) -> Result<Id<'_>, Error>

Available on crate feature revision only.

Obtain the best merge-base between commit one and two, or fail if there is none.

Performance

For repeated calls, prefer merge_base_with_cache(). Also be sure to set an object cache to accelerate repeated commit lookups.

pub fn merge_base_with_graph( &self, one: impl Into<ObjectId>, two: impl Into<ObjectId>, graph: &mut Graph<'_, '_, Commit<Flags>>, ) -> Result<Id<'_>, Error>

Available on crate feature revision only.

Obtain the best merge-base between commit one and two, or fail if there is none, providing a commit-graph graph to potentially greatly accelerate the operation by reusing graphs from previous runs.

Performance

Be sure to set an object cache to accelerate repeated commit lookups.

pub fn merge_bases_many_with_graph( &self, one: impl Into<ObjectId>, others: &[ObjectId], graph: &mut Graph<'_, '_, Commit<Flags>>, ) -> Result<Vec<Id<'_>>, Error>

Available on crate feature revision only.

Get all merge-bases between commit one and others, or an empty list if there is none, providing a commit-graph graph to potentially greatly speed up the operation.

Performance

Be sure to set an object cache to speed up repeated commit lookups.

pub fn merge_bases_many( &self, one: impl Into<ObjectId>, others: &[ObjectId], ) -> Result<Vec<Id<'_>>, Error>

Available on crate feature revision only.

Like merge_bases_many_with_graph(), but without the ability to speed up consecutive calls with a graph.

Performance

Be sure to set an object cache to speed up repeated commit lookups, and consider using merge_bases_many_with_graph() for consecutive calls.

pub fn merge_base_octopus_with_graph( &self, commits: impl IntoIterator<Item = impl Into<ObjectId>>, graph: &mut Graph<'_, '_, Commit<Flags>>, ) -> Result<Id<'_>, Error>

Available on crate feature revision only.

Return the best merge-base among all commits, or fail if commits yields no commit or no merge-base was found.

Use graph to speed up repeated calls.

pub fn merge_base_octopus( &self, commits: impl IntoIterator<Item = impl Into<ObjectId>>, ) -> Result<Id<'_>, Error>

Available on crate feature revision only.

Return the best merge-base among all commits, or fail if commits yields no commit or no merge-base was found.

For repeated calls, prefer Self::merge_base_octopus_with_graph() for cache-reuse.

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 is_shallow(&self) -> bool

Return true if the repository is a shallow clone, i.e. contains history only up to a certain depth.

pub fn shallow_commits(&self) -> Result<Option<Commits>, Error>

Return a shared list of shallow commits which is updated automatically if the in-memory snapshot has become stale as the underlying file on disk has changed.

The list of shallow commits represents the shallow boundary, beyond which we are lacking all (parent) commits. Note that the list is never empty, as Ok(None) is returned in that case indicating the repository isn’t a shallow clone.

The shared list is shared across all clones of this repository.

pub fn shallow_file(&self) -> PathBuf

Return the path to the shallow file which contains hashes, one per line, that describe commits that don’t have their parents within this repository.

Note that it may not exist if the repository isn’t actually shallow.

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

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

Available on crate feature attributes only.

Open the .gitmodules file as present in the worktree, or return None if no such file is available. Note that git configuration is also contributing to the result based on the current snapshot.

Note that his method will not look in other places, like the index or the HEAD tree.

pub fn modules(&self) -> Result<Option<ModulesSnapshot>, Error>

Available on crate feature attributes only.

Return a shared .gitmodules file which is updated automatically if the in-memory snapshot has become stale as the underlying file on disk has changed. The snapshot based on the file on disk is shared across all clones of this repository.

If a file on disk isn’t present, we will try to load it from the index, and finally from the current tree. In the latter two cases, the result will not be cached in this repository instance as we can’t detect freshness anymore, so time this method is called a new modules file will be created.

Note that git configuration is also contributing to the result based on the current snapshot.

pub fn submodules( &self, ) -> Result<Option<impl Iterator<Item = Submodule<'_>>>, Error>

Available on crate feature attributes only.

Return the list of available submodules, or None if there is no submodule configuration.

impl Repository

Interact with individual worktrees and their information.

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

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

This means the number is 0 even if there is the main worktree, as it is not counted as linked worktree. This also means it will be 1 if there is one linked worktree next to the main worktree. It’s worth noting that a bare repository may have one or more linked worktrees, but has no main worktree, which is the reason why the possibly available main worktree isn’t listed here.

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

pub fn worktree_proxy_by_id<'a>( &self, id: impl Into<&'a BStr>, ) -> Option<Proxy<'_>>

Return the worktree that is identified by the given id, if it exists at .git/worktrees/<id> and its gitdir file exists. Return None otherwise.

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, even if no .git file or directory exists. It’s merely based on configuration, see Worktree::dot_git_exists() for a way to perform more validation.

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() method, which may exist if this instance was opened in a worktree that was created separately.

pub fn worktree_stream( &self, id: impl Into<ObjectId>, ) -> Result<(Stream, File), Error>

Available on crate feature worktree-stream only.

If id points to a tree, produce a stream that yields one worktree entry after the other. The index of the tree at id is returned as well as it is an intermediate byproduct that might be useful to callers.

The entries will look exactly like they would if one would check them out, with filters applied. The export-ignore attribute is used to skip blobs or directories to which it applies.

pub fn worktree_archive( &self, stream: Stream, out: impl Write + Seek, blobs: impl Count, should_interrupt: &AtomicBool, options: Options, ) -> Result<(), Error>

Available on crate feature worktree-archive only.

Produce an archive from the stream and write it to out according to options. Use blob to provide progress for each entry written to out, and note that it should already be initialized to the amount of expected entries, with should_interrupt being queried between each entry to abort if needed, and on each write to out.

Performance

Be sure that out is able to handle a lot of write calls. Otherwise wrap it in a BufWriter.

Additional progress and fine-grained interrupt handling

For additional progress reporting, wrap out into a writer that counts throughput on each write. This can also be used to react to interrupts on each write, instead of only for each entry.

impl Repository

pub fn is_dirty(&self) -> Result<bool, Error>

Available on crate feature status only.

Returns true if the repository is dirty. This means it’s changed in one of the following ways:

• the index was changed in comparison to its working tree
• the working tree was changed in comparison to the index
• submodules are taken in consideration, along with their ignore and isActive configuration

Note that untracked files do not affect this flag.

impl Repository

pub fn index_worktree_status<'index, T, U, E>( &self, index: &'index State, patterns: impl IntoIterator<Item = impl AsRef<BStr>>, delegate: &mut impl VisitEntry<'index, ContentChange = T, SubmoduleStatus = U>, compare: impl CompareBlobs<Output = T> + Send + Clone, submodule: impl SubmoduleStatus<Output = U, Error = E> + Send + Clone, progress: &mut dyn Progress, should_interrupt: &AtomicBool, options: Options, ) -> Result<Outcome, Error>

where T: Send + Clone, U: Send + Clone, E: Error + Send + Sync + 'static,

Available on crate feature status only.

Obtain the status between the index and the worktree, involving modification checks for all tracked files along with information about untracked (and posisbly ignored) files (if configured).

• index
  • The index to use for modification checks, and to know which files are tacked when applying the dirwalk.
• patterns
  • Optional patterns to use to limit the paths to look at. If empty, all paths are considered.
• delegate
  • The sink for receiving all status data.
• compare
  • The implementations for fine-grained control over what happens if a hash must be recalculated.
• submodule
  • Control what kind of information to retrieve when a submodule is encountered while traversing the index.
• progress
  • A progress indication for index modification checks.
• should_interrupt
  • A flag to stop the whole operation.
• options
  • Additional configuration for all parts of the operation.

Note

This is a lower-level method, prefer the status method for greater ease of use.

impl Repository

pub fn tree_index_status<'repo, E>( &'repo self, tree_id: &oid, worktree_index: &State, pathspec: Option<&mut Pathspec<'repo>>, renames: TrackRenames, cb: impl FnMut(ChangeRef<'_, '_>, &State, &State) -> Result<Action, E>, ) -> Result<Outcome, Error>

where E: Into<Box<dyn Error + Send + Sync>>,

Available on crate feature status only.

Produce the git status portion that shows the difference between tree_id (usually HEAD^{tree}) and the worktree_index (typically the current .git/index), and pass all changes to cb(change, tree_index, worktree_index) with full access to both indices that contributed to the change.

(It’s notable that internally, the tree_id is converted into an index before diffing these). Set pathspec to Some(_) to further reduce the set of files to check.

Notes

• This is a low-level method - prefer the Repository::status() platform instead for access to various iterators over the same information.

impl Repository

Status

pub fn status<P>(&self, progress: P) -> Result<Platform<'_, P>, Error>

where P: Progress + 'static,

Available on crate feature status only.

Obtain a platform for configuring iterators for traversing git repository status information.

By default, this is set to the fastest and most immediate way of obtaining a status, which is most similar to

git status --ignored=no

which implies that submodule information is provided by default.

Note that status.showUntrackedFiles is respected, which leads to untracked files being collapsed by default. If that needs to be controlled, configure the directory walk explicitly or more implicitly.

Pass progress to receive progress information on file modifications on this repository. Use progress::Discard to discard all progress information.

Deviation

Whereas Git runs the index-modified check before the directory walk to set entries as up-to-date to (potentially) safe some disk-access, we run both in parallel which ultimately is much faster.

Trait Implementations

impl Clone for Repository

fn clone(&self) -> Self

Returns a duplicate 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 Exists for Repository

fn exists(&self, id: &oid) -> bool

Returns true if the object exists in the database.

impl Find for Repository

fn try_find<'a>( &self, id: &oid, buffer: &'a mut Vec<u8>, ) -> Result<Option<Data<'a>>, Error>

Find an object matching id in the database while placing its raw, possibly encoded data into buffer.

impl Header for Repository

fn try_header(&self, id: &oid) -> Result<Option<Header>, Error>

Find the header of the object matching id in the database.

impl From<&ThreadSafeRepository> for Repository

fn from(repo: &ThreadSafeRepository) -> Self

Converts to this type from the input type.

impl From<PrepareCheckout> for Repository

Available on crate feature worktree-mutation only.

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 for Repository

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

Tests for self and other values to be equal, and is used by ==.

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

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

impl Write for Repository

fn write(&self, object: &dyn WriteTo) -> Result<ObjectId, Error>

Write objects using the intrinsic kind of hash into the database, returning id to reference it in subsequent reads.

fn write_buf(&self, object: Kind, from: &[u8]) -> Result<ObjectId, Error>

As write, but takes an object kind along with its encoded bytes.

fn write_stream( &self, kind: Kind, size: u64, from: &mut dyn Read, ) -> Result<ObjectId, Error>

As write, but takes an input stream. This is commonly used for writing blobs directly without reading them to memory first.