Crates.io | gitoxide |
lib.rs | gitoxide |
version | 0.36.0 |
source | src |
created_at | 2020-07-12 04:39:30.797583 |
updated_at | 2024-05-22 11:53:35.924616 |
description | A command-line application for interacting with git repositories |
homepage | |
repository | https://github.com/Byron/gitoxide |
max_upload_size | |
id | 264300 |
size | 327,647 |
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.
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
.
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:
.git/index
.gitignore
and .gitattributes
Follow linked crate name for detailed status. Please note that all crates follow semver as well as the stability guide.
Stability Tier 1
Stability Tier 2
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.
These crates may be missing some features and thus are somewhat incomplete, but what's there is usable to some extent.
gitoxide-core
Our stability guide helps to judge how much churn can be expected when depending on crates in this workspace.
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.
For Arch Linux you can download gitoxide
from community
repository:
pacman -S gitoxide
For Exherbo Linux you can download gitoxide
from the Rust repository:
cave resolve -x repository/rust
cave resolve -x gitoxide
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
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.
perl
needs to be installed for OpenSSL
to build properly. This can be done with the following command:
dnf install perl
(see this issue).Once installed, there are two binaries:
Project goals can change over time as we learn more, and they can be challenged.
GitPython
and libgit2 in the process.anyhow::Error
exhaustively, knowing these errors are solely user-facing.quick-error
or thiserror
.Project non-goals can change over time as we learn more, and they can be challenged.
git
command functionality perfectly
git
is git
, and there is no reason to not use it. Our path is the one of simplicity to make
getting started with git easy.blocking
as well as gix-features::interrupt
to bring operations into the async world and to control
long running operations.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.
gitoxide
.gitoxide
itself which should be a good foundation for any contribution, but isn't a requirement for contributions either.Provide a CLI to for the most basic user journey:
gix tool open-remote
open the URL of the remote, possibly after applying known transformations to go from ssh
to https
.tix
as example implementation of tig
, displaying a version of the commit graph, useful for practicing how highly responsive GUIs can be made.git-sizer
, but leveraging extreme decompression speeds of indexed packs.gix-tui
should learn a lot from fossil-scm regarding the presentation of data. Maybe this can be used for prompts. Probably magit has a lot to offer, too.gix-lfs
to allow a multi-tier architecture so that assets can be stored in git and are accessible quickly from an intranet location
(for example by accessing the storage read-only over the network) while changes are pushed immediately by the server to other edge locations, like the cloud or backups. Sparse checkouts along with explorer/finder integrations
make it convenient to only work on a small subset of files locally. Clones can contain all configuration somebody would need to work efficiently from their location,
and authentication for the git history as well as LFS resources make the system secure. One could imagine encryption support for untrusted locations in the cloud
even though more research would have to be done to make it truly secure.sqlite
database.Please take a look at the SHORTCOMINGS.md
file for details.
izip!
macro in codeminiz_oxide
crateAt 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 😌.
This project is licensed under either of
at your option.
gitoxide
it will be possible to provide the fastest solution for it.git
from the first time he experienced git more than 13 years ago, and
tried to implement it in various shapes and forms
multiple times. Now with Rust @Byron finally feels to have found the right tool for the job!