Lib.rs

Cargo Features

[dependencies]
gix = { version = "0.67.0", default-features = false, features = ["basic", "extras", "need-more-recent-msrv", "comfort", "command", "status", "interrupt", "index", "dirwalk", "credentials", "worktree-mutation", "excludes", "tree-editor", "attributes", "mailmap", "revision", "revparse-regex", "blob-diff", "blob-merge", "worktree-stream", "worktree-archive", "async-network-client", "async-network-client-async-std", "blocking-network-client", "blocking-http-transport-curl", "blocking-http-transport-curl-rustls", "blocking-http-transport-reqwest", "blocking-http-transport-reqwest-rust-tls", "blocking-http-transport-reqwest-rust-tls-trust-dns", "blocking-http-transport-reqwest-native-tls", "max-control", "max-performance-safe", "parallel-walkdir", "hp-tempfile-registry", "parallel", "pack-cache-lru-static", "pack-cache-lru-dynamic", "max-performance", "fast-sha1", "zlib-ng", "zlib-ng-compat", "zlib-stock", "tracing", "tracing-detail", "verbose-object-parsing-errors", "serde", "progress-tree", "cache-efficiency-debug", "document-features"] }

default = basic, comfort, extras, max-performance-safe

These default features are set whenever gix is added without default-features = false somewhere in the dependency tree.

basic default = blob-diff, index, revision

There are various categories of features which help to optimize performance and build times. gix comes with 'batteries included' and everything is 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 probably don't use all of these features.

Thus it's recommended to take a moment and optimize build times by choosing only those 'Components' that you require. 'Performance' relevant features should be chosen next to maximize efficiency.

Application Developers

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 directly. Otherwise, see the Library Developers paragraph.

In order to configure a crate that isn't a direct dependency, one has to make it a direct dependency. We recommend gix-for-configuration = { package = "gix", version = "X.Y.Z", features = […] } to make clear this dependency isn't used in code.

Library Developers

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. For best compatibility, do not activate max-performance-safe or any other performance options.

Bundles

A bundle is a set of related feature toggles which can be activated with a single name that acts as a group. Bundles are for convenience only and bear no further meaning beyond the cargo manifest file.

More fundamental components that most will be able to make good use of.

extras default = attributes, blob-merge, credentials, dirwalk, excludes, interrupt, mailmap, revparse-regex, status, worktree-archive, worktree-mutation, worktree-stream

Various additional features and capabilities that are not necessarily part of what most users would need.

need-more-recent-msrv = tree-editor

A collection of features that need a larger MSRV, and thus are disabled by default.

comfort default

Various progress-related features that improve the look of progress message units.

Enables progress-unit-bytes and progress-unit-human-numbers of gix-features

command attributes?

Components

A component is a distinct feature which may be comprised of one or more methods around a particular topic. Providers of libraries should only activate the components they need.

Provide a top-level command module that helps with spawning commands similarly to git.

Enables gix-command

status extras = blob-diff, dirwalk, gix-status, index

Obtain information similar to git status.

Affects sections::Status, sections::status, gix::status, submodule::status…

interrupt extras

Utilities for interrupting computations and cleaning up tempfiles.

Enables signals of gix-tempfile and parking_lot and signal-hook

parking_lot:

for interrupt feature

index basic excludes? revision? status?

Access to .git/index files.

Enables gix-index

Affects repository::index_from_tree, repository::index_or_load_from_head, worktree::Index, worktree::IndexPersistedOrInMemory, worktree::open_index…

dirwalk extras status? = attributes, excludes

Support directory walks with Git-style annoations.

Enables gix-dir

Affects gix::dirwalk…

credentials async-network-client? blocking-network-client? extras

Access to credential helpers, which provide credentials for URLs. Note that gix-negotiate just piggibacks here, as 'credentials' is equivalent to 'fetch & push' right now.

Enables gix-credentials, gix-negotiate, and gix-prompt

Affects snapshot::credential_helpers…

worktree-mutation extras = attributes

Various ways to alter the worktree makeup by checkout and reset.

Enables gix-worktree-state

Affects clone::PrepareCheckout, clone::checkout…

excludes attributes? dirwalk? extras = index

Retrieve a worktree stack for querying exclude information

Enables gix-ignore and gix-worktree

Affects worktree::excludes, repository::attributes, types::AttributeStack…

tree-editor need-more-recent-msrv?

Provide facilities to edit trees conveniently.

Not that currently, this requires Rust 1.75. This feature toggle is likely going away then.

Affects tree::Editor, tree::editor, repository::edit_tree…

attributes async-network-client? blob-diff? blob-merge? blocking-network-client? dirwalk? extras worktree-archive? worktree-mutation? worktree-stream? = command, excludes

Query attributes and excludes. Enables access to pathspecs, worktree checkouts, filter-pipelines and submodules.

Enables gix-attributes, gix-filter, gix-pathspec, and gix-submodule, attributes of optional gix-worktree

Affects config::checkout_options, config::command_context, fetch::RecurseSubmodules, gix::pathspec, gix::submodule, gix::filter, repository::filter, repository::pathspec_defaults_ignore_case, types::Pathspec, types::PathspecDetached, types::Submodule, worktree::attributes, worktree::pathspec, repository::attributes, types::AttributeStack…

mailmap extras = revision

Add support for mailmaps, as way of determining the final name of commmiters and authors.

Enables gix-mailmap

Affects gix::mailmap…

revision basic mailmap? revparse-regex? = index

Make revspec parsing possible, as well describing revision.

Enables describe and merge_base of gix-revision

Affects commit::describe, repository::merge_base, repository::merge_base_with_graph, revision::spec, revision::Spec…

revparse-regex extras = regex, revision

If enabled, revspecs now support the regex syntax like @^{/^.*x}. Otherwise, only substring search is supported. This feature does increase compile time for niche-benefit, but is required for fully git-compatible revspec parsing.

blob-diff basic status? = attributes

Make it possible to diff blobs line by line. Note that this feature is integral for implementing tree-diffs as well due to the handling of rename-tracking,
which relies on line-by-line diffs in some cases.

Enables blob of gix-diff

Affects sections::Diff, sections::diff, tree::TreeDiffChangeExt, blob::diff, tree::diff, repository::diff_tree_to_tree, repository::diff_resource_cache…

blob-merge extras = attributes

Add functions to specifically merge files, using the standard three-way merge that git offers.

Enables blob of gix-merge

Affects merge::ConflictStyle, repository::blob_merge_options, repository::merge_resource_cache…

worktree-stream extras worktree-archive? = attributes, gix-worktree-stream

Make it possible to turn a tree into a stream of bytes, which can be decoded to entries and turned into various other formats.

Affects repository::worktree_stream…

worktree-archive extras = attributes, gix-archive, worktree-stream

Create archives from a tree in the repository, similar to what git archive does.

Note that we disable all default features which strips it off all container support, like tar and zip. Your application should add it as dependency and re-activate the desired features.

Affects repository::worktree_archive…

async-network-client async-network-client-async-std? = attributes, credentials

Mutually Exclusive Network Client

Either async-* or blocking-* versions of these toggles may be enabled at a time. For this reason, these must be chosen by the user of the library and can't be pre-selected. Making a choice here also affects which crypto-library ends up being used.

Make gix-protocol available along with an async client.

Enables streaming-input of gix-pack and async-client of gix-protocol

For communication with remotes

Affects fetch::RefMap, fetch::Source, fetch::SpecIndex, fetch::Mapping, remote::connect, url::scheme_permission, shallow::write…

async-network-client-async-std = async-network-client, async-std

Use this if your crate uses async-std as runtime, and enable basic runtime integration when connecting to remote servers via the git:// protocol.

Enables async-std of gix-transport

Affects clone::fetch…

blocking-network-client blocking-http-transport-curl? blocking-http-transport-reqwest? = attributes, credentials

Make gix-protocol available along with a blocking client, providing access to the file://, git:// and ssh:// transports.

Enables streaming-input of gix-pack, blocking-client of gix-protocol

Affects clone::fetch, fetch::RefMap, fetch::Source, fetch::SpecIndex, fetch::Mapping, remote::connect, url::scheme_permission, shallow::write…

blocking-http-transport-curl blocking-http-transport-curl-rustls? = blocking-network-client

Stacks with blocking-network-client to provide support for HTTP/S using curl, and implies blocking networking as a whole, making the https:// transport available.

Enables http-client-curl of gix-transport

blocking-http-transport-curl-rustls = blocking-http-transport-curl

Stacks with blocking-http-transport-curl and also enables the rustls backend to avoid openssl.

Enables http-client-curl-rust-tls of gix-transport

blocking-http-transport-reqwest blocking-http…reqwest-native-tls? blocking-http…reqwest-rust-tls? blocking-http…rust-tls-trust-dns? = blocking-network-client

Stacks with blocking-network-client to provide support for HTTP/S using reqwest, and implies blocking networking as a whole, making the https:// transport available.

Enables http-client-reqwest of gix-transport

blocking-http-transport-reqwest-rust-tls = blocking-http-transport-reqwest

Stacks with blocking-http-transport-reqwest and enables https:// via the rustls crate.

Enables http-client-reqwest-rust-tls of gix-transport

blocking-http-transport-reqwest-rust-tls-trust-dns = blocking-http-transport-reqwest

Stacks with blocking-http-transport-reqwest and enables https:// via the rustls crate. This also makes use of trust-dns to avoid getaddrinfo, but note it comes with its own problems.

Enables http-client-reqwest…tls-trust-dns of gix-transport

blocking-http-transport-reqwest-native-tls = blocking-http-transport-reqwest

Stacks with blocking-http-transport-reqwest and enables https:// via the native-tls crate.

Enables http-client-reqwest-native-tls of gix-transport

max-control max-performance-safe = pack-cache-lru-dynamic, pack-cache-lru-static, parallel

Performance

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 SHA1 and ZIP might not compile on all platforms, so it depends on the end-user who compiles the application to chose these based on their needs.

Activate features that maximize performance, like using threads, but leave everything else that might affect compatibility out to allow users more fine-grained control over performance features like which zlib* implementation to use. No C toolchain is involved.

max-performance-safe default max-performance? = max-control

Activate features that maximize performance, like usage of threads, `and access to caching in object databases, skipping the ones known to cause compile failures on some platforms. Note that this configuration still uses a pure Rust zlib implementation which isn't the fastest compared to its C-alternatives. No C toolchain is involved.

parallel-walkdir

If set, walkdir iterators will be multi-threaded which affects the listing of loose objects and references. Note, however, that this will use rayon under the hood and spawn threads for each traversal to avoid a global rayon thread pool. Thus this option is more interesting to one-off client applications, rather than the server.

Enables fs-walkdir-parallel of gix-features

hp-tempfile-registry

The tempfile registry uses a better implementation of a thread-safe hashmap, relying on an external crate.
This may be useful when tempfiles are created and accessed in a massively parallel fashion and you know that this is indeed faster than the simpler implementation that is the default.

Enables hp-hashmap of gix-tempfile

parallel max-control?

Make certain data structure threadsafe (or Sync) to facilitate multithreading. Further, many algorithms will now use multiple threads by default.

If unset, most of gix can only be used in a single thread as data structures won't be Send anymore.

Enables parallel of gix-features

Affects util::parallel_iter_drop…

pack-cache-lru-static max-control?

Provide a fixed-size allocation-free LRU cache for packs. It's useful if caching is desired while keeping the memory footprint for the LRU-cache itself low.

Enables pack-cache-lru-static of gix-pack

pack-cache-lru-dynamic max-control?

Provide a hash-map based LRU cache whose eviction is based a memory cap calculated from object data.

Enables pack-cache-lru-dynamic of gix-pack

max-performance = fast-sha1, max-performance-safe, zlib-ng

Activate other features that maximize performance, like usage of threads, zlib-ng and access to caching in object databases. Note that some platforms might suffer from compile failures, which is when max-performance-safe should be used.

fast-sha1 max-performance?

If enabled, use assembly versions of sha1 on supported platforms.
This might cause compile failures as well which is why it can be turned off separately.

Enables fast-sha1 of gix-features

zlib-ng max-performance?

Use the C-based zlib-ng backend, which can compress and decompress significantly faster. Note that this will cause duplicate symbol errors if the application also depends on zlib - use zlib-ng-compat in that case.

Enables zlib-ng of gix-features

zlib-ng-compat

Use zlib-ng via its zlib-compat API. Useful if you already need zlib for C code elsewhere in your dependencies. Otherwise, use zlib-ng.

Enables zlib-ng-compat of gix-features

zlib-stock

Use a slower C-based backend which can compress and decompress significantly faster than the rust version. Unlike zlib-ng-compat, this allows using dynamic linking with system zlib libraries and doesn't require cmake.

Enables zlib-stock of gix-features

tracing tracing-detail?

Other

The catch-all of feature toggles.

Enable tracing using the tracing crate for coarse tracing.

Enables tracing of gix-features

tracing-detail = tracing

Enable tracing using the tracing crate for detailed tracing. Also enables coarse tracing.

Enables tracing-detail of gix-features

verbose-object-parsing-errors

When parsing objects by default errors will only be available on the granularity of success or failure, and with the above flag enabled details information about the error location will be collected.
Use it in applications which expect broken or invalid objects or for debugging purposes.
Incorrectly formatted objects aren't very common otherwise.

Enables verbose-object-parsing-errors of gix-object

serde

Data structures implement serde::Serialize and serde::Deserialize.

Enables serde, serde of gix-commitgraph, gix-object, gix-odb, gix-pack, gix-ref, gix-revision, gix-url, optional gix-attributes, optional gix-credentials, optional gix-ignore, optional gix-index, optional gix-mailmap, optional gix-protocol, optional gix-transport, and optional gix-worktree

progress-tree

Re-export the progress tree root which allows to obtain progress from various functions which take impl gix::Progress. Applications which want to display progress will probably need this implementation.

Enables prodash

Just to get the progress-tree feature

cache-efficiency-debug

Print debugging information about usage of object database caches, useful for tuning cache sizes.

Enables cache-efficiency-debug of gix-features

Features from optional dependencies

In crates that don't use the dep: syntax, optional dependencies automatically become Cargo features. These features may have been created by mistake, and this functionality may be removed in the future.

gix-status status?

gix-worktree-stream worktree-stream?

gix-archive worktree-archive?

gix-protocol async-network-client? blocking-network-client?

gix-transport async-network-client-async-std? blocking-http-transport-curl? blocking-http-transport-curl-rustls? blocking-http-transport-reqwest? blocking-http…reqwest-native-tls? blocking-http…reqwest-rust-tls? blocking-http…rust-tls-trust-dns?

prodash progress-tree?

async-std async-network-client-async-std?

regex revparse-regex?

Enables regex

For use in rev-parse, which provides searching commits by running a regex on their message.

If disabled, the text will be search verbatim in any portion of the commit message, similar to how a simple unanchored regex of only 'normal' characters would work.

document-features implicit feature

Enables document-features

document-features:

Extract documentation for the feature flags from comments in Cargo.toml