1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139
//! 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][git_hash::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.
//! * **ref-table**
//! * supersedes all of the above to allow handling hundreds of thousands of references.
#![deny(unsafe_code, missing_docs, rust_2018_idioms)]
use std::borrow::Cow;
use git_hash::{oid, ObjectId};
pub use git_object::bstr;
use git_object::bstr::{BStr, BString};
#[path = "store/mod.rs"]
mod store_impl;
pub use store_impl::{file, packed};
mod fullname;
///
pub mod name;
///
pub mod namespace;
///
pub mod transaction;
mod parse;
mod raw;
pub use raw::Reference;
mod target;
///
pub mod log;
///
pub mod peel;
///
pub mod store {
/// The way a file store handles the reflog
#[derive(Debug, PartialOrd, PartialEq, Ord, Eq, Hash, Clone, Copy)]
pub enum WriteReflog {
/// Write a ref log for ref edits according to the standard rules.
Normal,
/// Never write a ref log.
Disable,
}
/// A thread-local handle for interacting with a [`Store`][crate::Store] to find and iterate references.
#[derive(Clone)]
pub struct Handle {
/// A way to access shared state with the requirement that interior mutability doesn't leak or is incorporated into error types
/// if it could. The latter can't happen if references to said internal aren't ever returned.
state: handle::State,
}
pub(crate) enum State {
Loose { store: file::Store },
}
#[path = "general/mod.rs"]
pub(crate) mod general;
///
#[path = "general/handle/mod.rs"]
mod handle;
pub use handle::find;
use crate::file;
}
/// The git reference store.
/// TODO: Figure out if handles are needed at all, which depends on the ref-table implementation.
pub struct Store {
inner: store::State,
}
/// Indicate that the given BString is a validate reference name or path that can be used as path on disk or written as target
/// of a symbolic reference
#[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone)]
pub struct FullName(pub(crate) BString);
/// A validated and potentially partial reference name - it can safely be used for common operations.
#[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone, Copy)]
pub struct FullNameRef<'a>(&'a BStr);
/// A validated complete and fully qualified reference name, safe to use for all operations.
#[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone)]
pub struct PartialNameRef<'a>(Cow<'a, BStr>);
/// A _validated_ prefix for references to act as a namespace.
#[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone)]
pub struct Namespace(BString);
/// Denotes the kind of reference.
#[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone, Copy)]
#[cfg_attr(feature = "serde1", derive(serde::Serialize, serde::Deserialize))]
pub enum Kind {
/// A ref that points to an object id
Peeled,
/// A ref that points to another reference, adding a level of indirection.
///
/// It can be resolved to an id using the [`peel_in_place_to_id()`][`crate::file::ReferenceExt::peel_to_id_in_place()`] method.
Symbolic,
}
/// Denotes a ref target, equivalent to [`Kind`], but with mutable data.
#[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone)]
pub enum Target {
/// A ref that points to an object id
Peeled(ObjectId),
/// A ref that points to another reference by its validated name, adding a level of indirection.
///
/// Note that this is an extension of gitoxide which will be helpful in logging all reference changes.
Symbolic(FullName),
}
/// Denotes a ref target, equivalent to [`Kind`], but with immutable data.
#[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone, Copy)]
pub enum TargetRef<'a> {
/// A ref that points to an object id
Peeled(&'a oid),
/// A ref that points to another reference by its validated name, adding a level of indirection.
Symbolic(FullNameRef<'a>),
}