Crate gitoxide 

This is the documentation of the binaries that come with gitoxide. These are called gix and ein.

gix

A developer tool to allow using gitoxide algorithms and functionality outside of the test suite. It will be unstable as long as the gix crate is unstable and is explicitly not to be understood as git replacement.

ein

A program to eventually become the most convenient way to do typical operations on git repositories, with all tooling one typically needs built right into it. For now, it’s most useful for its assorted set of tools which help to build automations or learn something about git repositories.

Feature Flags

Feature configuration can be complex and this document seeks to provide an overview.

Build Configuration

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

• max (enabled by default) — 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 — 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. Thanks to zlib-rs, you don’t have to trade off between compatibility and performance.

  This 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.

• max-control (enabled by default) — Like max, but with more control for configuration. See the Package Maintainers headline for more information.

• lean — All 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 — The smallest possible build, best suitable for small single-core machines.

  This build is essentially limited to local operations without any fanciness. It does not have gix clone.

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

• lean-async — 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.

Package Maintainers

*-control features leave it to you to configure C libraries, involving choices for HTTP transport implementation.

Additional features can be provided with --features and are handled by the gix-features crate. Note that only one HTTP transport can be enabled at a time. See the Building Blocks for mutually exclusive networking headline.

Building Blocks

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

• fast (enabled by default) — Makes the crate execute as fast as possible by supporting parallel computation of otherwise long-running functions. If disabled, the binary will be visibly smaller.
• fast-safe — Deprecated: identical to fast, as the fastest zlib backend is now the pure-Rust zlib-rs.
• tracing (enabled by default) — Enable tracing in gitoxide-core.
• pretty-cli (enabled by default) — 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.
• prodash-render-line-crossterm (enabled by default) — 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.
• prodash-render-tui (enabled by default) — Progress reporting with a TUI, can then be enabled with the --progress flag.
• prodash-render-line (enabled by default) — Progress reporting by visually drawing lines into the terminal without switching to an alternate window.
• 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 yields.
• gitoxide-core-tools (enabled by default) — A way to enable most gitoxide-core tools found in ein tools, namely organize and estimate hours.
• gitoxide-core-tools-query (enabled by default) — A program to perform analytics on a git repository, using an auto-maintained sqlite database
• gitoxide-core-tools-corpus (enabled by default) — A program to run algorithms on a corpus of repositories, recording each run for later comparison.
• gitoxide-core-tools-archive (enabled by default) — A sub-command to generate archive from virtual worktree checkouts.
• gitoxide-core-tools-clean (enabled by default) — A sub-command to clean the worktree from untracked and ignored files.

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.

• gitoxide-core-blocking-client (enabled by default) — Use blocking client networking.
• http-client-curl (enabled by default) — Support synchronous ‘http’ and ‘https’ transports (e.g. for clone, fetch and push) using curl.
• http-client-curl-rustls — Implies http-client-curl and configures curl to use the rust-tls backend.
• http-client-reqwest — Support synchronous ‘http’ and ‘https’ transports (e.g. for clone, fetch and push) using reqwest.

Async

• gitoxide-core-async-client — Use async client networking.

Experimental Features

• blame-experimental — An experimental use of the v0.2 branch of imara-diff in gix-diff and gix-blame, to allow trying the new diff algorithm.

Modules

plumbing

porcelain

shared

everything in common between the gix and ein binaries.