Crate git_repository

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() 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(…) 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][protocol::transport]
    • [packetline][protocol::transport::packetline]

Feature Flags

Mutually Exclusive Network Client

Either async-* or blocking-* versions of these toggles may be enabled at a time.

• async-network-client — Make git-protocol available along with an async client.

• async-network-client-async-std — Use this if your crate uses async-std as runtime, and enable basic runtime integration when connecting to remote servers.

• blocking-network-client — Make git-protocol available along with a blocking client.

• blocking-http-transport-curl — Stacks with blocking-network-client to provide support for HTTP/S using curl, and implies blocking networking as a whole.

• blocking-http-transport-reqwest — Stacks with blocking-network-client to provide support for HTTP/S using reqwest, and implies blocking networking as a whole.

• blocking-http-transport-reqwest-rust-tls — Stacks with blocking-http-transport-reqwest and enables HTTPS via the rustls crate. Note that https isn’t available without a selection.

• blocking-http-transport-reqwest-native-tls — Stacks with blocking-http-transport-reqwest and enables HTTPS via the native-tls crate. Note that https isn’t available without a selection.

Other

• serde1 — Data structures implement serde::Serialize and serde::Deserialize.

• max-performance — Activate other features that maximize performance, like usage of threads, zlib-ng and access to caching in object databases. Note that some platforms might suffer from compile failures, which is when max-performance-safe should be used.

• fast-sha1 — If enabled, use assembly versions of sha1 on supported platforms. This might cause compile failures as well which is why it can be turned off separately.

• max-performance-safe (enabled by default) — Activate features that maximize performance, like usage of threads, zlib-ng and access to caching in object databases, skipping the ones known to cause compile failures on some platforms.

• cache-efficiency-debug — Print debugging information about usage of object database caches, useful for tuning cache sizes.

• regex — For use in rev-parse, which provides searching commits by running a regex on their message.

  If disabled, the text will be search verbatim in any portion of the commit message, similar to how a simple unanchored regex of only ‘normal’ characters would work.

Re-exports

pub use git_actor as actor;

pub use git_attributes as attrs;

pub use git_credentials as credentials;

pub use git_date as date;

pub use git_features as features;

pub use git_glob as glob;

pub use git_hash as hash;

pub use git_lock as lock;

pub use git_object as objs;

pub use git_object::bstr;

pub use git_odb as odb;

pub use git_prompt as prompt;

pub use git_protocol as protocol;

pub use git_ref as refs;

pub use git_refspec as refspec;

pub use git_sec as sec;

pub use git_tempfile as tempfile;

pub use git_traverse as traverse;

pub use git_url as url;

Modules

clone

commit

config

create

diff

discover

env

Utilities to handle program arguments and other values of interest.

head

id

index

Feature Flags

init

interrupt

Process-global interrupt handling

mailmap

object

open

parallel

Run computations in parallel, or not based the parallel feature toggle.

path

permission

permissions

prelude

progress

reference

remote

revision

Revisions is the generalized notion of a commit.

state

Not to be confused with ‘status’.

tag

threading

Type definitions for putting shared ownership and synchronized mutation behind the threading feature toggle.

worktree

Structs

Commit

A decoded commit object with access to its owning repository.

Head

The head reference, as created from looking at .git/HEAD, able to represent all of its possible states.

Id

An ObjectId with access to a repository.

Object

A decoded object with a reference to its owning repository.

ObjectDetached

A detached, self-contained object, without access to its source repository.

Permissions

Permissions associated with various resources of a git repository

Reference

A reference that points to an object or reference, with access to its source repository.

Remote

A remote which represents a way to interact with hosts for remote clones of the parent repository.

Repository

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

Tag

A decoded tag object with access to its owning repository.

ThreadSafeRepository

An instance with access to everything a git repository entails, best imagined as container implementing Sync + Send for most for system resources required to interact with a git repository which are loaded in once the instance is created.

Tree

A decoded tree object with access to its owning repository.

Url

A URL with support for specialized git related capabilities.

Worktree

A worktree checkout containing the files of the repository in consumable form.

oid

A borrowed reference to a hash identifying objects.

Enums

Kind

The kind of repository.

ObjectId

An owned hash identifying objects, most commonly Sha1

Traits

Progress

A trait for describing hierarchical process.

Functions

discover

See ThreadSafeRepository::discover(), but returns a Repository instead.

init

See ThreadSafeRepository::init(), but returns a Repository instead.

init_bare

See ThreadSafeRepository::init(), but returns a Repository instead.

open

See ThreadSafeRepository::open(), but returns a Repository instead.

open_opts

See ThreadSafeRepository::open_opts(), but returns a Repository instead.

prepare_clone

Create a platform for configuring a clone with main working tree from url to the local path, using default options for opening it (but amended with using configuration from the git installation to ensure all authentication options are honored).

prepare_clone_bare

Create a platform for configuring a bare clone from url to the local path, using default options for opening it (but amended with using configuration from the git installation to ensure all authentication options are honored).

Type Definitions

OdbHandle

A handle for finding objects in an object database, abstracting away caches for thread-local use.

RefStore

The standard type for a store to handle git references.