Lib.rs

› Gitoxide › Features

Cargo Features

[dependencies]
gitoxide = { version = "0.38.0", default-features = false, features = ["max", "max-pure", "max-control", "lean", "small", "lean-async", "fast", "fast-safe", "tracing", "pretty-cli", "prodash-render-line-crossterm", "prodash-render-tui", "prodash-render-line", "cache-efficiency-debug", "gitoxide-core-tools", "gitoxide-core-tools-query", "gitoxide-core-tools-corpus", "gitoxide-core-tools-archive", "gitoxide-core-tools-clean", "gitoxide-core-blocking-client", "http-client-curl", "http-client-curl-rustls", "http-client-reqwest", "gitoxide-core-async-client", "document-features"] }
default = max

The max feature is set by default whenever gitoxide is added without default-features = false somewhere in the dependency tree.

max default = fast, gitoxide-core-blocking-client, http-client-curl, max-control

Build Configuration

These combine common choices of building blocks to represent typical builds.

Everything, all at once.

As fast as possible, tracing, with TUI progress, progress line rendering with autoconfiguration, all transports based on their most mature implementation (HTTP), all ein tools, CLI colors and local-time support, JSON output, regex support for rev-specs. Can be amended with the http-client-curl-rustls feature to avoid openssl as backend.

max-pure = gitoxide-core-blocking-client, http-client-reqwest, max-control

Like max, but only Rust is allowed.

This is the most compatible build as it won't need a C compiler or C toolchains to build. It's also not the fastest as or the most feature-rich in terms of available transports as it uses Rust's HTTP implementation.

As fast as possible, with TUI progress, progress line rendering with auto-configuration, all transports available but less mature pure Rust HTTP implementation, all ein tools, CLI colors and local-time support, JSON output, regex support for rev-specs.

Enables rustsha1 and zlib-rust-backend of gix-features

max-control max max-pure? = fast-safe, gitoxide-core-tools, gitoxide-core-tools-corpus, gitoxide-core-tools-query, pretty-cli, prodash-render-line, prodash-render-tui, tracing

Like max, but with more control for configuration. See the Package Maintainers headline for more information.

Enables revparse-regex of gix, render-line-autoconfigure of prodash

lean = fast, gitoxide-core-blocking-client, gitoxide-core-tools, gitoxide-core-tools-corpus, gitoxide-core-tools-query, http-client-curl, pretty-cli, prodash-render-line, tracing

All of the good stuff, with less fanciness for smaller binaries.

As fast as possible, progress line rendering, all transports based on their most mature implementation (HTTP), all ein tools, CLI colors and local-time support, JSON output.

small = is-terminal, pretty-cli, prodash-render-line

The smallest possible build, best suitable for small single-core machines.

This build is essentially limited to local operations without any fanciness.

Optimized for size, no parallelism thus much slower, progress line rendering.

Enables rustsha1 and zlib-rust-backend of gix-features

Affects shared::pretty.prepare_and_run…

lean-async = fast, gitoxide-core-async-client, gitoxide-core-tools, gitoxide-core-tools-corpus, gitoxide-core-tools-query, pretty-cli, prodash-render-line, tracing

Like lean, but uses Rusts async implementations for networking.

This build is more of a demonstration showing how async can work with gitoxide, which generally is blocking. This also means that the selection of async transports is very limited to only HTTP (without typical git configuration) and git over TCP like provided by the git daemon.

As fast as possible, progress line rendering, less featureful HTTP (pure Rust) and only git-daemon support, all ein tools, CLI colors and local-time support, JSON output.

Due to async client-networking not being implemented for most transports, this one supports only the 'git+tcp' and HTTP transport. It uses, however, a fully asynchronous networking implementation which can serve a real-world example on how to implement custom async transports.

fast lean? lean-async? max

Package Maintainers

*-control features leave it to you to configure C libraries, involving choices for zlib, ! hashing and transport implementation.

Additional features can be provided with --features and are handled by the gix-features crate. If nothing else is specified, the Rust implementation is used. ! Note that only one feature of each section can be enabled at a time.

  • zlib
    • gix-features/zlib-ng
    • gix-features/zlib-ng-compat
    • gix-features/zlib-stock
    • gix-features/zlib-rust-backend (default if no choice is made)
  • sha1
    • gix-features/fast-sha1
    • gix-features/rustsha1 (default if no choice is made)
  • HTTP - see the Building Blocks for mutually exclusive networking headline

Examples

  • cargo build --release --no-default-features --features max-control,gix-features/zlib-stock,gitoxide-core-blocking-client,http-client-curl
    • Create a build just like max, but using the stock zlib library instead of zlib-ng
  • cargo build --release --no-default-features --features max-control,http-client-reqwest,gitoxide-core-blocking-client,gix-features/fast-sha1
    • Create a build just like max-pure, but with faster hashing due to fast-sha1.

Building Blocks

Typical combinations of features of our dependencies, some of which are referred to in the gitoxide crate's code for conditional compilation.

Makes the crate execute as fast as possible by supporting parallel computation of otherwise long-running functions as well as fast, hardware accelerated hashing, along with a faster zlib backend. If disabled, the binary will be visibly smaller.

Enables comfort and max-performance of gix

fast-safe max-control?

Makes the crate execute as fast as possible by supporting parallel computation of otherwise long-running functions as well as fast, hardware accelerated hashing, along with a faster zlib backend.
If disabled, the binary will be visibly smaller.

Enables comfort and max-performance-safe of gix

tracing lean? lean-async? max-control?

Enable tracing in gitoxide-core.

Enables tracing and tracing-detail of gix-features and tracing, tracing-forest, and tracing-subscriber

tracing-forest:

for 'tracing'

Affects options::Args.trace…

pretty-cli lean? lean-async? max-control? small?

Use clap 3.0 to build the prettiest, best documented and most user-friendly CLI at the expense of binary size. Provides a terminal user interface for detailed and exhaustive progress. Provides a line renderer for leaner progress display, without the need for a full-blown TUI.

Enables auto-color, color and humantime of env_logger ^0.10.0, serde of gitoxide-core, local-time, progress-tree and progress-tree-log of prodash

Affects shared::pretty…

prodash-render-line-crossterm prodash-render-line? = crosstermion, is-terminal, prodash-render-line

The --verbose flag will be powered by an interactive progress mechanism that doubles as log as well as interactive progress that appears after a short duration.

Enables render-line-crossterm and signal-hook of prodash

prodash-render-tui max-control? = futures-lite

Progress reporting with a TUI, can then be enabled with the --progress flag.

Enables progress-tree of gix, render-tui and render-tui-crossterm of prodash

Affects options::Args.progress, options::Args.progress_keep_open, shared::DEFAULT_FRAME_RATE…

prodash-render-line lean? lean-async? max-control? prodash-render-line-crossterm? small? = prodash-render-line-crossterm

Progress reporting by visually drawing lines into the terminal without switching to an alternate window.

Enables progress-tree of gix, render-line of prodash

Affects shared::progress_tree, shared::setup_line_renderer_range, shared::DEFAULT_FRAME_RATE…

cache-efficiency-debug

Prints statistical information to inform about cache efficiency when those are dropped.
Use this as a way to understand if bigger caches actually produce greater yiedls.

Enables cache-efficiency-debug of gix-features

gitoxide-core-tools lean? lean-async? max-control? = gitoxide-core-tools-archive, gitoxide-core-tools-clean

A way to enable most gitoxide-core tools found in ein tools, namely organize and estimate hours.

Enables estimate-hours and organize of gitoxide-core

Affects options::ToolCommands, options::tools…

gitoxide-core-tools-query lean? lean-async? max-control?

A program to perform analytics on a git repository, using an auto-maintained sqlite database

Enables query of gitoxide-core

Affects options::tools.Query, options::tools.query…

gitoxide-core-tools-corpus lean? lean-async? max-control?

A program to run algorithms on a corpus of repositories, recording each run for later comparison.

Enables corpus of gitoxide-core

Affects options::corpus…

gitoxide-core-tools-archive gitoxide-core-tools?

A sub-command to generate archive from virtual worktree checkouts.

Enables archive of gitoxide-core

Affects options::archive…

gitoxide-core-tools-clean gitoxide-core-tools?

A sub-command to clean the worktree from untracked and ignored files.

Enables clean of gitoxide-core

Affects options::clean…

gitoxide-core-blocking-client lean? max max-pure?

Building Blocks for mutually exclusive networking

Blocking and async features are mutually exclusive and cause a compile-time error. This also means that cargo … --all-features will fail. Within each section, features can be combined.

Blocking

The backends are mutually exclusive, e.g. choose either curl or request.

Use blocking client networking.

Enables blocking-client of gitoxide-core

Affects options::fetch, options::clone, options::remote…

http-client-curl lean? max

Support synchronous 'http' and 'https' transports (e.g. for clone, fetch and push) using **curl**.

Enables blocking-http-transport-curl of gix

http-client-curl-rustls

Implies http-client-curl and configures curl to use the rust-tls backend.

Enables blocking-http-transport-curl-rustls of gix

http-client-reqwest max-pure?

Support synchronous 'http' and 'https' transports (e.g. for clone, fetch and push) using **reqwest**.

Enables blocking-http…reqwest-rust-tls of gix

gitoxide-core-async-client lean-async? = futures-lite

Async

Use async client networking.

Enables async-client of gitoxide-core

Affects main::async_util, options::remote…

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.

prodash max-control? pretty-cli? prodash-render-line? prodash-render-line-crossterm? prodash-render-tui?
is-terminal prodash-render-line-crossterm? small?
crosstermion prodash-render-line-crossterm?
futures-lite gitoxide-core-async-client? prodash-render-tui?
document-features implicit feature

Enables document-features

document-features:

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