45 releases (breaking)
0.35.0 | Feb 11, 2023 |
---|---|
0.33.0 | Jan 10, 2023 |
0.31.0 | Dec 30, 2022 |
0.29.0 | Nov 21, 2022 |
0.1.0 | Jul 12, 2020 |
#2591 in Development tools
391 downloads per month
Used in 3 crates
2.5MB
54K
SLoC
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
] protocol
Feature Flags
Dependencies
~12–47MB
~785K SLoC