search

Byron / gitoxide

An idiomatic, lean, fast & safe pure Rust implementation of Git
Apache License 2.0
8.4k stars 275 forks source link
blazingly-fast built-with-rust cli git version-control

readme

CI Crates.io

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.

gitoxide provides the gix and ein binaries for use on the command-line to allow experimentation with key features like fetch and clone, and to validate the usability and control of the API offered by the gix crate.

gitoxide aspires to be a production-grade server implementation and the ein binary aspires to become the default way to interact with git repositories.

asciicast

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:

Crates

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

Production Grade

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.

Initial Development

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

Stress Testing

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

Download from Arch-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 CI configuration, 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 certain 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 some libraries available to build successfully.
# Installing these is platform-dependent and thus can't be explained here.
cargo install gitoxide

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

The following installs the latest unpublished release directly from git:

cargo install --git https://github.com/Byron/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.

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/Byron/gitoxide, first build the image:

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

Then copy the binaries into your image and replace the git directive with a gix equivalent.

COPY --from gitoxide:latest /bin/gix /usr/local/bin/
COPY --from gitoxide:latest /bin/ein /usr/local/bin/

RUN /usr/local/bin/gix clone --depth 1 https://github.com/Byron/gitoxide gitoxide

Usage

Once installed, there are two binaries:

Project Goals

Project goals can change over time as we learn more, and they can be challenged.

Non-Goals

Project non-goals can change over time as we learn more, and they can be challenged.

Contributions

If what you have seen so far sparked your interest to contribute, then let us say: We are happy to have you and help you to get started.

We recommend running just test check-size during the development process to assure CI is green before pushing.

A backlog for work ready to be picked up is available in the Project's Kanban board, which contains instructions on how to pick a task. If it's empty or you have other questions, feel free to start a discussion or reach out to @Byron privately.

For additional details, also take a look at the collaboration guide.

Getting started with Video Tutorials

Other Media

Roadmap

Features for 1.0

Provide a CLI to for the most basic user journey:

Ideas for Examples

Ideas for Spin-Offs

Shortcomings & Limitations

Please take a look at the SHORTCOMINGS.md file for details.

Credits

🙏 Special Thanks 🙏

At least for now this section is exclusive to highlight the incredible support that Josh Triplett has provided to me in the form of advice, sponsorship and countless other benefits that were incredibly meaningful. Going full time with gitoxide would hardly have been feasible without his involvement, and I couldn't be more grateful 😌.

License

This project is licensed under either of

at your option.

Fun facts