github.com/GitoxideLabs/gitoxide @gix-tempfile-v23.0.2

gitoxide is an implementation of git written in Rust for developing future-proof applications which strive for correctness and performance while providing a pleasant and unsurprising developer experience.

There are two primary ways to use gitoxide:

1. As Rust library: Use the gix crate as a Cargo dependency for API access.
2. As command-line tool: The gix binary as development tool to help testing the API in real repositories, and the ein binary with workflow-enhancing tools. Both binaries may forever be unstable, do not rely on them in scripts.

Development Status

The command-line tools as well as the status of each crate is described in the crate status document.

For use in applications, look for the gix crate, which serves as entrypoint to the functionality provided by various lower-level plumbing crates like gix-config.

Feature Discovery

Can gix do what I need it to do?

The above can be hard to answer and this paragraph is here to help with feature discovery.

Look at crate-status.md for a rather exhaustive document that contains both implemented and planned features.

Further, the gix crate documentation with the git2 search term helps to find all currently known git2 equivalent method calls. Please note that this list is definitely not exhaustive yet, but might help if you are coming from git2.

What follows is a high-level list of features and those which are planned:

• [x] clone
• [x] fetch
• [ ] push
• [x] blame (plumbing)
• [x] status
• [x] blob and tree-diff
• [ ] merge
  • [x] blobs
  • [x] trees
  • [ ] commits
• [x] commit
  • [ ] hooks
• [x] commit-graph traversal
• [ ] rebase
• [x] worktree checkout and worktree stream
• [ ] reset
• [x] reading and writing of objects
• [x] reading and writing of refs
• [x] reading and writing of .git/index
• [x] reading and writing of git configuration
• [x] pathspecs
• [x] revspecs
• [x] .gitignore and .gitattributes

Crates

Follow linked crate name for detailed status. Please note that all crates follow semver as well as the stability guide.

Production Grade

• Stability Tier 1

• gix-lock

• Stability Tier 2

• gix-tempfile

Stabilization Candidates

Crates that seem feature complete and need to see some more use before they can be released as 1.0. Documentation is complete and was reviewed at least once.

• gix-mailmap
• gix-chunk
• gix-ref
• gix-config
• gix-config-value
• gix-glob
• gix-actor
• gix-hash

Initial Development

These crates may be missing some features and thus are somewhat incomplete, but what's there is usable to some extent.

• usable (with rough but complete docs, possibly incomplete functionality)
• gix (⬅ entrypoint)
• gix-object
• gix-validate
• gix-url
• gix-packetline
• gix-packetline-blocking
• gix-transport
• gix-protocol
• gix-pack
• gix-odb
• gix-commitgraph
• gix-diff
• gix-traverse
• gix-features
• gix-credentials
• gix-sec
• gix-quote
• gix-discover
• gix-path
• gix-attributes
• gix-ignore
• gix-pathspec
• gix-index
• gix-revision
• gix-revwalk
• gix-command
• gix-prompt
• gix-refspec
• gix-fs
• gix-utils
• gix-hashtable
• gix-worktree
• gix-bitmap
• gix-negotiate
• gix-filter
• gix-worktree-stream
• gix-archive
• gix-submodule
• gix-status
• gix-worktree-state
• gix-date
• gix-dir
• gix-merge
• gix-shallow
• gix-error
• gitoxide-core
• very early (possibly without any documentation and many rough edges)
• gix-blame
• idea (just a name placeholder)
• gix-note
• gix-fetchhead
• gix-lfs
• gix-rebase
• gix-sequencer
• gix-tui
• gix-tix
• gix-bundle
• gix-fsck

Stress Testing

• [x] Verify huge packs
• [x] Explode a pack to disk
• [x] Generate and verify large commit graphs
• [ ] Generate huge pack from a lot of loose objects

Stability and MSRV

Our stability guide helps to judge how much churn can be expected when depending on crates in this workspace.

Installation

Download a Binary Release

Using cargo binstall, one is able to fetch binary releases. You can install it via cargo install cargo-binstall, assuming the [rust toolchain][rustup] is present.

Then install gitoxide with cargo binstall gitoxide.

See the releases section for manual installation and various alternative builds that are slimmer or smaller, depending on your needs, for Linux, MacOS and Windows.

Install with Homebrew

For macOS and Linux, gitoxide can be installed from Homebrew:

brew install gitoxide

Download from Arch Linux repository

For Arch Linux you can download gitoxide from community repository:

pacman -S gitoxide

Download from Exherbo Linux Rust repository

For Exherbo Linux you can download gitoxide from the Rust repository:

cave resolve -x repository/rust
cave resolve -x gitoxide

From Source via Cargo

cargo is the Rust package manager which can easily be obtained through [rustup]. With it, you can build your own binary effortlessly and for your particular CPU for additional performance gains.

The minimum supported Rust version is documented in the Cargo package, the latest stable one will work as well.

There are various build configurations, all of them are documented here. The documentation should also be useful for packagers who need to tune external dependencies.

# A way to install `gitoxide` with just Rust and a C compiler installed.
# If there are problems with SSL certificates during clones, try to omit `--locked`.
cargo install gitoxide --locked --no-default-features --features max-pure

# The default installation, 'max', is the fastest, but also needs `cmake` to build successfully.
# Installing it is platform-dependent.
cargo install gitoxide

# For smaller binaries and even faster build times that are traded for a less fancy CLI implementation,
# use the `lean` feature.
cargo install gitoxide --locked --no-default-features --features lean

The following installs the latest unpublished max release directly from git:

cargo install --git https://github.com/GitoxideLabs/gitoxide gitoxide

How to deal with build failures

On some platforms, installation may fail due to lack of tools required by C toolchains. This can generally be avoided by installation with:

cargo install gitoxide --no-default-features --features max-pure

What follows is a list of known failures.

• On Fedora, perl needs to be installed for OpenSSL to build properly. This can be done with the following command (see issue #592):

sh dnf install perl

Using Docker

Some CI/CD pipelines leverage repository cloning. Below is a copy-paste-able example to build docker images for such workflows. As no official image exists (at this time), an image must first be built.

[!NOTE] The dockerfile isn't continuously tested as it costs too much time and thus might already be broken. PRs are welcome.

Building the most compatible base image

docker build -f etc/docker/Dockerfile.alpine -t gitoxide:latest --compress . --target=pipeline

Basic usage in a Pipeline

For example, if a Dockerfile currently uses something like RUN git clone https://github.com/GitoxideLabs/gitoxide, first build the image:

docker build -f etc/docker/Dockerfile.alpine -t gitoxide:latest --compress .

Then copy the binaries into your image an