You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
#! There are various categories of features which help to optimize performance and build times. `gix` comes with 'batteries included' and everything is
36
+
#! enabled as long as it doesn't sacrifice compatibility. Most users will be fine with that but will pay with higher compile times than necessary as they
37
+
#! probably don't use all of these features.
38
+
#!
39
+
#! **Thus it's recommended to take a moment and optimize build times by chosing only those 'Components' that you require.** *'Performance' relevant features should
40
+
#! be chosen next to maximize efficiency.*
41
+
#!
42
+
#! #### Application Developers
43
+
#!
44
+
#! These are considered the end-users, all they need to tune is `Performance` features to optimize the efficiency of their app, assuming they don't use `gix`
45
+
#! directly. Otherwise, see the `Library Developers` paragraph.
46
+
#!
47
+
#! In order to configure a crate that isn't a direct dependency, one has to make it a direct dependency. We recommend
48
+
#! `gix-for-configuration = { package = "gix", version = "X.Y.Z", features = […] }` to make clear this dependency isn't used in code.
49
+
#!
50
+
#! #### Library Developers
51
+
#!
52
+
#! As a developer of a library, you should start out with `gix = { version = "X.Y.Z", default-features = false }` and add components as you see fit.
53
+
#! For best compatibility, **do not activate `max-performance-safe`** or any other performance options.
54
+
#!
55
+
#! #### Bundles
56
+
#!
57
+
#! A bundle is a set of related feature toggles which can be activated with a single name that acts as a group.
58
+
#! Bundles are for convenience only and bear no further meaning beyond the cargo manifest file.
55
59
56
60
## Various additional features and capabilities that are not necessarily part of what most users would need.
57
61
extras = ["worktree-stream", "worktree-archive"]
58
62
63
+
## Various progress-related features that improve the look of progress message units.
## Use this if your crate uses `async-std` as runtime, and enable basic runtime integration when connecting to remote servers via the `git://` protocol.
## Stacks with `blocking-network-client` to provide support for HTTP/S using **curl**, and implies blocking networking as a whole, making the `https://` transport avaialble.
## Stacks with `blocking-network-client` to provide support for HTTP/S using **reqwest**, and implies blocking networking as a whole, making the `https://` transport avaialble.
#! The reason these features exist is to allow optimization for compile time and optimize for compatibility by default. This means that some performance options around
105
+
#! SHA1 and ZIP might not compile on all platforms, so it depeneds on the end-user who compiles the application to chose these based on their needs.
97
106
98
107
## Activate features that maximize performance, like usage of threads, `zlib-ng` and access to caching in object databases, skipping the ones known to cause compile failures
Copy file name to clipboardExpand all lines: gix/src/lib.rs
+6-6Lines changed: 6 additions & 6 deletions
Original file line number
Diff line number
Diff line change
@@ -4,7 +4,7 @@
4
4
//! individually. Sometimes it may hide complexity under the assumption that the performance difference doesn't matter
5
5
//! for all but the fewest tools out there, which would be using the underlying crates directly or file an issue.
6
6
//!
7
-
//! # The prelude and extensions
7
+
//! ### The prelude and extensions
8
8
//!
9
9
//! With `use git_repository::prelude::*` you should be ready to go as it pulls in various extension traits to make functionality
10
10
//! available on objects that may use it.
@@ -14,13 +14,13 @@
14
14
//! Most extensions to existing objects provide an `obj_with_extension.attach(&repo).an_easier_version_of_a_method()` for simpler
15
15
//! call signatures.
16
16
//!
17
-
//! ## `ThreadSafe` Mode
17
+
//! ### `ThreadSafe` Mode
18
18
//!
19
19
//! By default, the [`Repository`] isn't `Sync` and thus can't be used in certain contexts which require the `Sync` trait.
20
20
//!
21
21
//! To help with this, convert it with [`.into_sync()`][Repository::into_sync()] into a [`ThreadSafeRepository`].
22
22
//!
23
-
//! ## Object-Access Performance
23
+
//! ### Object-Access Performance
24
24
//!
25
25
//! Accessing objects quickly is the bread-and-butter of working with git, right after accessing references. Hence it's vital
26
26
//! to understand which cache levels exist and how to leverage them.
@@ -42,9 +42,9 @@
42
42
//! When reading the documentation of the canonical gix-worktree program one gets the impression work tree and working tree are used
43
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
44
//!
45
-
//! # Cargo-features
45
+
//! ### Plumbing Crates
46
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
47
+
//! 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
48
48
//! crates which are otherwise harder to discover:
49
49
//!
50
50
//! **`git_repository::`**
@@ -64,7 +64,7 @@
64
64
//! * [`git2::build::CheckoutBuilder::disable_filters()](https://docs.rs/git2/*/git2/build/struct.CheckoutBuilder.html#method.disable_filters) ➡ ❌ *(filters are always applied during checkouts)*
65
65
//! * [`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.
0 commit comments