This crate provides the Repository abstraction which serves as a hub into all the functionality of git.

It's powerful and won't sacrifice performance while still increasing convenience compared to using the sub-crates individually. Sometimes it may hide complexity under the assumption that the performance difference doesn't matter for all but the fewest tools out there, which would be using the underlying crates directly or file an issue.

The prelude and extensions

With use git_repository::prelude::* you should be ready to go as it pulls in various extension traits to make functionality available on objects that may use it.

The method signatures are still complex and may require various arguments for configuration and cache control.

Most extensions to existing objects provide an obj_with_extension.attach(&repo).an_easier_version_of_a_method() for simpler call signatures.

ThreadSafe Mode

By default, the Repository isn't Sync and thus can't be used in certain contexts which require the Sync trait.

To help with this, convert it with [.into_sync()][Repository::into_sync()] into a ThreadSafeRepository.

Object-Access Performance

Accessing objects quickly is the bread-and-butter of working with git, right after accessing references. Hence it's vital to understand which cache levels exist and how to leverage them.

When accessing an object, the first cache that's queried is a memory-capped LRU object cache, mapping their id to data and kind. It has to be specifically enabled a Repository. On miss, the object is looked up and if a pack is hit, there is a small fixed-size cache for delta-base objects.

In scenarios where the same objects are accessed multiple times, the object cache can be useful and is to be configured specifically using the [object_cache_size(…)][crate::Repository::object_cache_size()] method.

Use the cache-efficiency-debug cargo feature to learn how efficient the cache actually is - it's easy to end up with lowered performance if the cache is not hit in 50% of the time.

Terminology

WorkingTree and WorkTree

When reading the documentation of the canonical git-worktree program one gets the impression work tree and working tree are used interchangeably. We use the term work tree only and try to do so consistently as its shorter and assumed to be the same.

Cargo-features

To make using sub-crates easier these are re-exported into the root of this crate. Here we list how to access nested plumbing crates which are otherwise harder to discover:

git_repository::

• [odb]
  • pack
• protocol
  • transport
    • packetline

Feature Flags