gix/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 Trust Model
8//!
9//! It is very simple - based on the ownership of the repository compared to the user of the current process [Trust](sec::Trust)
10//! is assigned. This can be [overridden](open::Options::with()) as well. Further, git configuration files track their trust level
11//! per section based on and sensitive values like paths to executables or certain values will be skipped if they are from a source
12//! that isn't [fully](sec::Trust::Full) trusted.
13//!
14//! That way, data can safely be obtained without risking to execute untrusted executables.
15//!
16//! Note that it's possible to let `gix` act like `git` or `git2` by setting the [open::Options::bail_if_untrusted()] option.
17//!
18//! ### The prelude and extensions
19//!
20//! With `use git_repository::prelude::*` you should be ready to go as it pulls in various extension traits to make functionality
21//! available on objects that may use it.
22//!
23//! The method signatures are still complex and may require various arguments for configuration and cache control.
24//!
25//! Most extensions to existing objects provide an `obj_with_extension.attach(&repo).an_easier_version_of_a_method()` for simpler
26//! call signatures.
27//!
28//! ### `ThreadSafe` Mode
29//!
30//! By default, the [`Repository`] isn't `Sync` and thus can't be used in certain contexts which require the `Sync` trait.
31//!
32//! To help with this, convert it with [`.into_sync()`][Repository::into_sync()] into a [`ThreadSafeRepository`].
33//!
34//! ### Object-Access Performance
35//!
36//! Accessing objects quickly is the bread-and-butter of working with git, right after accessing references. Hence it's vital
37//! to understand which cache levels exist and how to leverage them.
38//!
39//! When accessing an object, the first cache that's queried is a memory-capped LRU object cache, mapping their id to data and kind.
40//! It has to be specifically enabled a [`Repository`].
41//! On miss, the object is looked up and if a pack is hit, there is a small fixed-size cache for delta-base objects.
42//!
43//! In scenarios where the same objects are accessed multiple times, the object cache can be useful and is to be configured specifically
44//! using the [`object_cache_size(…)`][crate::Repository::object_cache_size()] method.
45//!
46//! Use the `cache-efficiency-debug` cargo feature to learn how efficient the cache actually is - it's easy to end up with lowered
47//! performance if the cache is not hit in 50% of the time.
48//!
49//! ### Terminology
50//!
51//! #### `WorkingTree` and `WorkTree`
52//!
53//! When reading the documentation of the canonical gix-worktree program one gets the impression work tree and working tree are used
54//! interchangeably. We use the term _work tree_ only and try to do so consistently as its shorter and assumed to be the same.
55//!
56//! ### Plumbing Crates
57//!
58//! To make using _sub-crates_ and their types easier, these are re-exported into the root of this crate. Here we list how to access nested plumbing
59//! crates which are otherwise harder to discover:
60//!
61//! **`git_repository::`**
62//! * [`odb`]
63//! * [`pack`][odb::pack]
64//! * [`protocol`]
65//! * [`transport`][protocol::transport]
66//! * [`packetline`][protocol::transport::packetline]
67//!
68//! ### `libgit2` API to `gix`
69//!
70//! This doc-aliases are used to help finding methods under a possibly changed name. Just search in the docs.
71//! Entering `git2` into the search field will also surface all methods with such annotations.
72//!
73//! What follows is a list of methods you might be missing, along with workarounds if available.
74//! * [`git2::Repository::open_bare()`](https://docs.rs/git2/*/git2/struct.Repository.html#method.open_bare) ➡ ❌ - use [`open()`] and discard if it is not bare.
75//! * [`git2::build::CheckoutBuilder::disable_filters()`](https://docs.rs/git2/*/git2/build/struct.CheckoutBuilder.html#method.disable_filters) ➡ ❌ *(filters are always applied during checkouts)*
76//! * [`git2::Repository::submodule_status()`](https://docs.rs/git2/*/git2/struct.Repository.html#method.submodule_status) ➡ [`Submodule::state()`] - status provides more information and conveniences though, and an actual worktree status isn't performed.
77//!
78//! #### Integrity checks
79//!
80//! `git2` by default performs integrity checks via [`strict_hash_verification()`](https://docs.rs/git2/latest/git2/opts/fn.strict_hash_verification.html) and
81//! [`strict_object_creation`](https://docs.rs/git2/latest/git2/opts/fn.strict_object_creation.html) which `gitoxide` *currently* **does not have**.
82//!
83//! ### Feature Flags
84#![cfg_attr(
85 all(doc, feature = "document-features"),
86 doc = ::document_features::document_features!()
87)]
88#![cfg_attr(all(doc, feature = "document-features"), feature(doc_cfg, doc_auto_cfg))]
89#![deny(missing_docs, rust_2018_idioms, unsafe_code)]
90#![allow(clippy::result_large_err)]
91
92// Re-exports to make this a potential one-stop shop crate avoiding people from having to reference various crates themselves.
93// This also means that their major version changes affect our major version, but that's alright as we directly expose their
94// APIs/instances anyway.
95pub use gix_actor as actor;
96#[cfg(feature = "attributes")]
97pub use gix_attributes as attrs;
98#[cfg(feature = "blame")]
99pub use gix_blame as blame;
100#[cfg(feature = "command")]
101pub use gix_command as command;
102pub use gix_commitgraph as commitgraph;
103#[cfg(feature = "credentials")]
104pub use gix_credentials as credentials;
105pub use gix_date as date;
106#[cfg(feature = "dirwalk")]
107pub use gix_dir as dir;
108pub use gix_features as features;
109use gix_features::threading::OwnShared;
110pub use gix_features::{
111 parallel,
112 progress::{Count, DynNestedProgress, NestedProgress, Progress},
113 threading,
114};
115pub use gix_fs as fs;
116pub use gix_glob as glob;
117pub use gix_hash as hash;
118pub use gix_hashtable as hashtable;
119#[cfg(feature = "excludes")]
120pub use gix_ignore as ignore;
121#[doc(inline)]
122#[cfg(feature = "index")]
123pub use gix_index as index;
124pub use gix_lock as lock;
125#[cfg(feature = "credentials")]
126pub use gix_negotiate as negotiate;
127pub use gix_object as objs;
128pub use gix_object::bstr;
129pub use gix_odb as odb;
130#[cfg(feature = "credentials")]
131pub use gix_prompt as prompt;
132pub use gix_protocol as protocol;
133pub use gix_ref as refs;
134pub use gix_refspec as refspec;
135pub use gix_revwalk as revwalk;
136pub use gix_sec as sec;
137pub use gix_tempfile as tempfile;
138pub use gix_trace as trace;
139pub use gix_traverse as traverse;
140pub use gix_url as url;
141#[doc(inline)]
142pub use gix_url::Url;
143pub use gix_utils as utils;
144pub use gix_validate as validate;
145pub use hash::{oid, ObjectId};
146
147pub mod interrupt;
148
149mod ext;
150///
151pub mod prelude;
152
153#[cfg(feature = "excludes")]
154mod attribute_stack;
155
156///
157pub mod path;
158
159/// The standard type for a store to handle git references.
160pub type RefStore = gix_ref::file::Store;
161/// A handle for finding objects in an object database, abstracting away caches for thread-local use.
162pub type OdbHandle = gix_odb::memory::Proxy<gix_odb::Handle>;
163/// A handle for finding objects in an object database, abstracting away caches for moving across threads.
164pub type OdbHandleArc = gix_odb::memory::Proxy<gix_odb::HandleArc>;
165
166/// A way to access git configuration
167pub(crate) type Config = OwnShared<gix_config::File<'static>>;
168
169mod types;
170#[cfg(any(feature = "excludes", feature = "attributes"))]
171pub use types::AttributeStack;
172pub use types::{
173 Blob, Commit, Head, Id, Object, ObjectDetached, Reference, Remote, Repository, Tag, ThreadSafeRepository, Tree,
174 Worktree,
175};
176#[cfg(feature = "attributes")]
177pub use types::{Pathspec, PathspecDetached, Submodule};
178
179///
180pub mod clone;
181pub mod commit;
182///
183#[cfg(feature = "dirwalk")]
184pub mod dirwalk;
185pub mod head;
186pub mod id;
187pub mod object;
188#[cfg(feature = "attributes")]
189pub mod pathspec;
190pub mod reference;
191pub mod repository;
192#[cfg(feature = "attributes")]
193pub mod submodule;
194pub mod tag;
195#[cfg(any(feature = "dirwalk", feature = "status"))]
196pub(crate) mod util;
197
198///
199pub mod progress;
200///
201pub mod push;
202
203///
204pub mod diff;
205
206///
207#[cfg(feature = "merge")]
208pub mod merge;
209
210/// See [`ThreadSafeRepository::discover()`], but returns a [`Repository`] instead.
211///
212/// # Note
213///
214/// **The discovered repository might not be suitable for any operation that requires authentication with remotes**
215/// as it doesn't see the relevant git configuration.
216///
217/// To achieve that, one has to [enable `git_binary` configuration](https://github.com/GitoxideLabs/gitoxide/blob/9723e1addf52cc336d59322de039ea0537cdca36/src/plumbing/main.rs#L86)
218/// in the open-options and use [`ThreadSafeRepository::discover_opts()`] instead. Alternatively, it might be well-known
219/// that the tool is going to run in a neatly configured environment without relying on bundled configuration.
220#[allow(clippy::result_large_err)]
221pub fn discover(directory: impl AsRef<std::path::Path>) -> Result<Repository, discover::Error> {
222 ThreadSafeRepository::discover(directory).map(Into::into)
223}
224
225/// See [`ThreadSafeRepository::init()`], but returns a [`Repository`] instead.
226#[allow(clippy::result_large_err)]
227pub fn init(directory: impl AsRef<std::path::Path>) -> Result<Repository, init::Error> {
228 ThreadSafeRepository::init(directory, create::Kind::WithWorktree, create::Options::default()).map(Into::into)
229}
230
231/// See [`ThreadSafeRepository::init()`], but returns a [`Repository`] instead.
232#[allow(clippy::result_large_err)]
233pub fn init_bare(directory: impl AsRef<std::path::Path>) -> Result<Repository, init::Error> {
234 ThreadSafeRepository::init(directory, create::Kind::Bare, create::Options::default()).map(Into::into)
235}
236
237/// Create a platform for configuring a bare clone from `url` to the local `path`, using default options for opening it (but
238/// amended with using configuration from the git installation to ensure all authentication options are honored).
239///
240/// See [`clone::PrepareFetch::new()`] for a function to take full control over all options.
241#[allow(clippy::result_large_err)]
242pub fn prepare_clone_bare<Url, E>(
243 url: Url,
244 path: impl AsRef<std::path::Path>,
245) -> Result<clone::PrepareFetch, clone::Error>
246where
247 Url: std::convert::TryInto<gix_url::Url, Error = E>,
248 gix_url::parse::Error: From<E>,
249{
250 clone::PrepareFetch::new(
251 url,
252 path,
253 create::Kind::Bare,
254 create::Options::default(),
255 open_opts_with_git_binary_config(),
256 )
257}
258
259/// Create a platform for configuring a clone with main working tree from `url` to the local `path`, using default options for opening it
260/// (but amended with using configuration from the git installation to ensure all authentication options are honored).
261///
262/// See [`clone::PrepareFetch::new()`] for a function to take full control over all options.
263#[allow(clippy::result_large_err)]
264pub fn prepare_clone<Url, E>(url: Url, path: impl AsRef<std::path::Path>) -> Result<clone::PrepareFetch, clone::Error>
265where
266 Url: std::convert::TryInto<gix_url::Url, Error = E>,
267 gix_url::parse::Error: From<E>,
268{
269 clone::PrepareFetch::new(
270 url,
271 path,
272 create::Kind::WithWorktree,
273 create::Options::default(),
274 open_opts_with_git_binary_config(),
275 )
276}
277
278fn open_opts_with_git_binary_config() -> open::Options {
279 use gix_sec::trust::DefaultForLevel;
280 let mut opts = open::Options::default_for_level(gix_sec::Trust::Full);
281 opts.permissions.config.git_binary = true;
282 opts
283}
284
285/// See [`ThreadSafeRepository::open()`], but returns a [`Repository`] instead.
286#[allow(clippy::result_large_err)]
287#[doc(alias = "git2")]
288pub fn open(directory: impl Into<std::path::PathBuf>) -> Result<Repository, open::Error> {
289 ThreadSafeRepository::open(directory).map(Into::into)
290}
291
292/// See [`ThreadSafeRepository::open_opts()`], but returns a [`Repository`] instead.
293#[allow(clippy::result_large_err)]
294#[doc(alias = "open_ext", alias = "git2")]
295pub fn open_opts(directory: impl Into<std::path::PathBuf>, options: open::Options) -> Result<Repository, open::Error> {
296 ThreadSafeRepository::open_opts(directory, options).map(Into::into)
297}
298
299///
300pub mod create;
301
302///
303pub mod open;
304
305///
306pub mod config;
307
308///
309#[cfg(feature = "mailmap")]
310pub mod mailmap;
311
312///
313pub mod worktree;
314
315pub mod revision;
316
317#[cfg(feature = "attributes")]
318pub mod filter;
319
320///
321pub mod remote;
322
323///
324pub mod init;
325
326/// Not to be confused with 'status'.
327pub mod state;
328
329///
330#[cfg(feature = "status")]
331pub mod status;
332
333///
334pub mod shallow;
335
336///
337pub mod discover;
338
339pub mod env;
340
341#[cfg(feature = "attributes")]
342fn is_dir_to_mode(is_dir: bool) -> gix_index::entry::Mode {
343 if is_dir {
344 gix_index::entry::Mode::DIR
345 } else {
346 gix_index::entry::Mode::FILE
347 }
348}