A crate for handling the references stored in various formats in a git repository.
References are also called refs which are used interchangeably.
Refs are the way to keep track of objects and come in two flavors.
- symbolic refs are pointing to another reference
- peeled refs point to the an object by its [
ObjectId]
They can be identified by a relative path and stored in various flavors.
- files
- [loose][file::Store]
- one reference maps to a file on disk
- packed
- references are stored in a single human-readable file, along with their targets if they are symbolic.
- [loose][file::Store]
Concrete recovery signals such as missing references and reflog identities expose classification-only
[gix_error::ClassificationMarker] sources. Use is_not_found(), is_corrupted(), is_validation(), or
classify() on [gix_error::Exn] and [gix_error::Error] rather than downcasting these sources to classifier
error types. Callee errors retain their concrete causes. Locally detected failures may use a single classified
[gix_error::Message] containing both the diagnostic and its values.
Operations return [gix_error::Exn], with diagnostic [gix_error::Message] keys documented where they are added.
Inspect these dictionaries with metadata(), and add context available at the call site.
For recovery, downcast to [file::find::NotFound] to distinguish an absent reference from an absent object,
[file::find::ReferenceDecode] for loose reference contents that could not be decoded,
[file::transaction::prepare::ReferenceOutOfDate] or [file::transaction::prepare::MustNotExist] for a failed
update constraint, and [file::log::create_or_update::MissingCommitter] for a missing reflog identity.