README

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



[gix]: https://docs.rs/gix

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

[semver]: https://semver.org

 Production Grade

 gix-lock
 gix-tempfile
 gix-fs

 Stabilization Candidates

Crates whose chosen supported public API is nearly ready for a 1.0 compatibility commitment.
Remaining experimental public APIs can stay behind a non-default unstable feature.
Documentation for the supported API 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

 Major-Zero Crates

A _major-zero crate_ (0.x) may introduce breaking API changes in minor releases. This says nothing about its
quality, completeness, or suitability for production use. Crates used only as implementation details, without
exposing their APIs through public crates, may remain _major-zero crates_ indefinitely.

 usable _(with rough but complete docs, possibly incomplete functionality)_
   gix (⬅ entrypoint)
   gix-object
   gix-validate
   gix-url