Lib.rs

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 Trust Model

It is very simple - based on the ownership of the repository compared to the user of the current process Trust is assigned. This can be overridden as well. Further, git configuration files track their trust level per section based on and sensitive values like paths to executables or certain values will be skipped if they are from a source that isn't fully trusted.

That way, data can safely be obtained without risking to execute untrusted executables.

Note that it's possible to let gix act like git or git2 by setting the [open::Options::bail_if_untrusted()] option.

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 [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 on 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 [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 gix-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.

Plumbing Crates

To make using sub-crates and their types 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

libgit2 API to gix

This doc-aliases are used to help finding methods under a possibly changed name. Just search in the docs. Entering git2 into the search field will also surface all methods with such annotations.

What follows is a list of methods you might be missing, along with workarounds if available.

• git2::Repository::open_bare() ➡ ❌ - use [open()] and discard if it is not bare.
• git2::build::CheckoutBuilder::disable_filters() ➡ ❌ (filters are always applied during checkouts)
• git2::Repository::submodule_status() ➡ [Submodule::state()] - status provides more information and conveniences though, and an actual worktree status isn't performed.

Integrity checks

git2 by default performs integrity checks via strict_hash_verification() and strict_object_creation which gitoxide currently does not have.

Feature Flags