vendor/gix/src/lib.rs

   1 //! This crate provides the [`Repository`] abstraction which serves as a hub into all the functionality of git.
   2 //!
   3 //! It's powerful and won't sacrifice performance while still increasing convenience compared to using the sub-crates
   4 //! individually. Sometimes it may hide complexity under the assumption that the performance difference doesn't matter
   5 //! for all but the fewest tools out there, which would be using the underlying crates directly or file an issue.
   6 //!
   7 //! # The prelude and extensions
   8 //!
   9 //! With `use git_repository::prelude::*` you should be ready to go as it pulls in various extension traits to make functionality
  10 //! available on objects that may use it.
  11 //!
  12 //! The method signatures are still complex and may require various arguments for configuration and cache control.
  13 //!
  14 //! Most extensions to existing objects provide an `obj_with_extension.attach(&repo).an_easier_version_of_a_method()` for simpler
  15 //! call signatures.
  16 //!
  17 //! ## ThreadSafe Mode
  18 //!
  19 //! By default, the [`Repository`] isn't `Sync` and thus can't be used in certain contexts which require the `Sync` trait.
  20 //!
  21 //! To help with this, convert it with [`.into_sync()`][Repository::into_sync()] into a [`ThreadSafeRepository`].
  22 //!
  23 //! ## Object-Access Performance
  24 //!
  25 //! Accessing objects quickly is the bread-and-butter of working with git, right after accessing references. Hence it's vital
  26 //! to understand which cache levels exist and how to leverage them.
  27 //!
  28 //! When accessing an object, the first cache that's queried is a  memory-capped LRU object cache, mapping their id to data and kind.
  29 //! It has to be specifically enabled a [`Repository`].
  30 //! On miss, the object is looked up and if a pack is hit, there is a small fixed-size cache for delta-base objects.
  31 //!
  32 //! In scenarios where the same objects are accessed multiple times, the object cache can be useful and is to be configured specifically
  33 //! using the [`object_cache_size(…)`][crate::Repository::object_cache_size()] method.
  34 //!
  35 //! Use the `cache-efficiency-debug` cargo feature to learn how efficient the cache actually is - it's easy to end up with lowered
  36 //! performance if the cache is not hit in 50% of the time.
  37 //!
  38 //! ### Terminology
  39 //!
  40 //! #### WorkingTree and WorkTree
  41 //!
  42 //! When reading the documentation of the canonical gix-worktree program one gets the impression work tree and working tree are used
  43 //! interchangeably. We use the term _work tree_ only and try to do so consistently as its shorter and assumed to be the same.
  44 //!
  45 //! # Cargo-features
  46 //!
  47 //! To make using  _sub-crates_ easier these are re-exported into the root of this crate. Here we list how to access nested plumbing
  48 //! crates which are otherwise harder to discover:
  49 //!
  50 //! **`git_repository::`**
  51 //! * [`odb`]
  52 //!   * [`pack`][odb::pack]
  53 //! * [`protocol`]
  54 //!   * [`transport`][protocol::transport]
  55 //!     * [`packetline`][protocol::transport::packetline]
  56 //!
  57 //!
  58 //! ## Feature Flags
  59 #![cfg_attr(
  60     feature = "document-features",
  61     cfg_attr(doc, doc = ::document_features::document_features!())
  62 )]
  63 #![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
  64 #![deny(missing_docs, rust_2018_idioms, unsafe_code)]
  65
  66 // Re-exports to make this a potential one-stop shop crate avoiding people from having to reference various crates themselves.
  67 // This also means that their major version changes affect our major version, but that's alright as we directly expose their
  68 // APIs/instances anyway.
  69 pub use gix_actor as actor;
  70 pub use gix_attributes as attrs;
  71 pub use gix_credentials as credentials;
  72 pub use gix_date as date;
  73 pub use gix_features as features;
  74 use gix_features::threading::OwnShared;
  75 pub use gix_features::{parallel, progress::Progress, threading};
  76 pub use gix_glob as glob;
  77 pub use gix_hash as hash;
  78 #[doc(inline)]
  79 pub use gix_index as index;
  80 pub use gix_lock as lock;
  81 pub use gix_object as objs;
  82 pub use gix_object::bstr;
  83 pub use gix_odb as odb;
  84 pub use gix_prompt as prompt;
  85 #[cfg(all(feature = "gix-protocol"))]
  86 pub use gix_protocol as protocol;
  87 pub use gix_ref as refs;
  88 pub use gix_refspec as refspec;
  89 pub use gix_sec as sec;
  90 pub use gix_tempfile as tempfile;
  91 pub use gix_traverse as traverse;
  92 pub use gix_url as url;
  93 #[doc(inline)]
  94 pub use gix_url::Url;
  95 pub use hash::{oid, ObjectId};
  96
  97 pub mod interrupt;
  98
  99 mod ext;
 100 ///
 101 pub mod prelude {
 102     pub use gix_features::parallel::reduce::Finalize;
 103     pub use gix_odb::{Find, FindExt, Header, HeaderExt, Write};
 104
 105     pub use crate::ext::*;
 106 }
 107
 108 ///
 109 pub mod path;
 110
 111 /// The standard type for a store to handle git references.
 112 pub type RefStore = gix_ref::file::Store;
 113 /// A handle for finding objects in an object database, abstracting away caches for thread-local use.
 114 pub type OdbHandle = gix_odb::Handle;
 115 /// A way to access git configuration
 116 pub(crate) type Config = OwnShared<gix_config::File<'static>>;
 117
 118 ///
 119 mod types;
 120 pub use types::{
 121     Commit, Head, Id, Kind, Object, ObjectDetached, Reference, Remote, Repository, Tag, ThreadSafeRepository, Tree,
 122     Worktree,
 123 };
 124
 125 ///
 126 pub mod clone;
 127 pub mod commit;
 128 pub mod head;
 129 pub mod id;
 130 pub mod object;
 131 pub mod reference;
 132 mod repository;
 133 pub mod tag;
 134
 135 ///
 136 pub mod progress {
 137     #[cfg(feature = "progress-tree")]
 138     pub use gix_features::progress::prodash::tree;
 139     pub use gix_features::progress::*;
 140 }
 141
 142 ///
 143 pub mod diff {
 144     pub use gix_diff::*;
 145     ///
 146     pub mod rename {
 147         /// Determine how to do rename tracking.
 148         #[derive(Debug, Copy, Clone, Eq, PartialEq)]
 149         pub enum Tracking {
 150             /// Do not track renames at all, the fastest option.
 151             Disabled,
 152             /// Track renames.
 153             Renames,
 154             /// Track renames and copies.
 155             ///
 156             /// This is the most expensive option.
 157             RenamesAndCopies,
 158         }
 159     }
 160 }
 161
 162 /// See [ThreadSafeRepository::discover()], but returns a [`Repository`] instead.
 163 #[allow(clippy::result_large_err)]
 164 pub fn discover(directory: impl AsRef<std::path::Path>) -> Result<Repository, discover::Error> {
 165     ThreadSafeRepository::discover(directory).map(Into::into)
 166 }
 167
 168 /// See [ThreadSafeRepository::init()], but returns a [`Repository`] instead.
 169 #[allow(clippy::result_large_err)]
 170 pub fn init(directory: impl AsRef<std::path::Path>) -> Result<Repository, init::Error> {
 171     ThreadSafeRepository::init(directory, create::Kind::WithWorktree, create::Options::default()).map(Into::into)
 172 }
 173
 174 /// See [ThreadSafeRepository::init()], but returns a [`Repository`] instead.
 175 #[allow(clippy::result_large_err)]
 176 pub fn init_bare(directory: impl AsRef<std::path::Path>) -> Result<Repository, init::Error> {
 177     ThreadSafeRepository::init(directory, create::Kind::Bare, create::Options::default()).map(Into::into)
 178 }
 179
 180 /// Create a platform for configuring a bare clone from `url` to the local `path`, using default options for opening it (but
 181 /// amended with using configuration from the git installation to ensure all authentication options are honored).
 182 ///
 183 /// See [`clone::PrepareFetch::new()] for a function to take full control over all options.
 184 #[allow(clippy::result_large_err)]
 185 pub fn prepare_clone_bare<Url, E>(
 186     url: Url,
 187     path: impl AsRef<std::path::Path>,
 188 ) -> Result<clone::PrepareFetch, clone::Error>
 189 where
 190     Url: std::convert::TryInto<gix_url::Url, Error = E>,
 191     gix_url::parse::Error: From<E>,
 192 {
 193     clone::PrepareFetch::new(
 194         url,
 195         path,
 196         create::Kind::Bare,
 197         create::Options::default(),
 198         open_opts_with_git_binary_config(),
 199     )
 200 }
 201
 202 /// Create a platform for configuring a clone with main working tree from `url` to the local `path`, using default options for opening it
 203 /// (but amended with using configuration from the git installation to ensure all authentication options are honored).
 204 ///
 205 /// See [`clone::PrepareFetch::new()] for a function to take full control over all options.
 206 #[allow(clippy::result_large_err)]
 207 pub fn prepare_clone<Url, E>(url: Url, path: impl AsRef<std::path::Path>) -> Result<clone::PrepareFetch, clone::Error>
 208 where
 209     Url: std::convert::TryInto<gix_url::Url, Error = E>,
 210     gix_url::parse::Error: From<E>,
 211 {
 212     clone::PrepareFetch::new(
 213         url,
 214         path,
 215         create::Kind::WithWorktree,
 216         create::Options::default(),
 217         open_opts_with_git_binary_config(),
 218     )
 219 }
 220
 221 fn open_opts_with_git_binary_config() -> open::Options {
 222     use gix_sec::trust::DefaultForLevel;
 223     let mut opts = open::Options::default_for_level(gix_sec::Trust::Full);
 224     opts.permissions.config.git_binary = true;
 225     opts
 226 }
 227
 228 /// See [ThreadSafeRepository::open()], but returns a [`Repository`] instead.
 229 #[allow(clippy::result_large_err)]
 230 pub fn open(directory: impl Into<std::path::PathBuf>) -> Result<Repository, open::Error> {
 231     ThreadSafeRepository::open(directory).map(Into::into)
 232 }
 233
 234 /// See [ThreadSafeRepository::open_opts()], but returns a [`Repository`] instead.
 235 #[allow(clippy::result_large_err)]
 236 pub fn open_opts(directory: impl Into<std::path::PathBuf>, options: open::Options) -> Result<Repository, open::Error> {
 237     ThreadSafeRepository::open_opts(directory, options).map(Into::into)
 238 }
 239
 240 ///
 241 pub mod permission {
 242     ///
 243     pub mod env_var {
 244         ///
 245         pub mod resource {
 246             ///
 247             pub type Error = gix_sec::permission::Error<std::path::PathBuf>;
 248         }
 249     }
 250 }
 251 ///
 252 pub mod permissions {
 253     pub use crate::repository::permissions::{Config, Environment};
 254 }
 255 pub use repository::permissions::Permissions;
 256
 257 ///
 258 pub mod create;
 259
 260 ///
 261 pub mod open;
 262
 263 ///
 264 pub mod config;
 265
 266 ///
 267 pub mod mailmap;
 268
 269 ///
 270 pub mod worktree;
 271
 272 pub mod revision;
 273
 274 ///
 275 pub mod remote;
 276
 277 ///
 278 pub mod init;
 279
 280 /// Not to be confused with 'status'.
 281 pub mod state {
 282     /// Tell what operation is currently in progress.
 283     #[derive(Debug, PartialEq, Eq)]
 284     pub enum InProgress {
 285         /// A mailbox is being applied.
 286         ApplyMailbox,
 287         /// A rebase is happening while a mailbox is being applied.
 288         // TODO: test
 289         ApplyMailboxRebase,
 290         /// A git bisect operation has not yet been concluded.
 291         Bisect,
 292         /// A cherry pick operation.
 293         CherryPick,
 294         /// A cherry pick with multiple commits pending.
 295         CherryPickSequence,
 296         /// A merge operation.
 297         Merge,
 298         /// A rebase operation.
 299         Rebase,
 300         /// An interactive rebase operation.
 301         RebaseInteractive,
 302         /// A revert operation.
 303         Revert,
 304         /// A revert operation with multiple commits pending.
 305         RevertSequence,
 306     }
 307 }
 308
 309 ///
 310 pub mod discover;
 311
 312 pub mod env;
 313
 314 mod kind;