Struct GitIndex

pub struct GitIndex { /* private fields */ }

Available on crate feature git only.

Wrapper around managing the crates.io-index git repository

Uses a “bare” git index that fetches files directly from the repo instead of local checkout. Uses Cargo’s cache.

Instantiation

When creating an instance of this type, the crates-index will be cloned automatically should it not be present. If a repository is present at the location but the remote doesn’t match the desired index URL, a new remote will be added and fetched from.

Please note that concurrent calls to GitIndex::new_cargo_default() (and related) will automatically block and wait for each other, so only one instance will try to clone the index while the others will wait for completion.

This, however, only protects from itself and cargo cloning the index at the same time might interfere.

Implementations

impl GitIndex

pub fn new_cargo_default() -> Result<Self, Error>

Creates an index for the default crates.io registry, using the same disk location as Cargo itself.

This is the recommended way to access Cargo’s index. *Note that this clones a new index if none is present yet.

Note this function takes the CARGO_HOME environment variable into account

Concurrency

Concurrent invocations may fail if the index needs to be cloned. To prevent that, use synchronization mechanisms like mutexes or file locks as needed by the application.

pub fn try_new_cargo_default() -> Result<Option<Self>, Error>

Like Self::new_cargo_default(), but read-only without auto-cloning the cargo default git index.

pub fn from_url(url: &str) -> Result<Self, Error>

Creates a bare index from a provided URL, opening the same location on disk that Cargo uses for that registry index.

*Note that this clones a new index if none is present yet.

It can be used to access custom registries.

Concurrency

Concurrent invocations may fail if the index needs to be cloned. To prevent that, use synchronization mechanisms like mutexes or file locks as needed by the application.

pub fn try_from_url(url: &str) -> Result<Option<Self>, Error>

Like Self::from_url(), but read-only without auto-cloning the index at url.

pub fn with_path<P: Into<PathBuf>, S: Into<String>>( path: P, url: S, ) -> Result<Self, Error>

Creates a bare index at the provided path with the specified repository URL.

*Note that this clones a new index to path if none is present there yet.

Concurrency

Concurrent invocations may fail if the index needs to be cloned. To prevent that, use synchronization mechanisms like mutexes or file locks as needed by the application.

pub fn try_with_path<P: Into<PathBuf>, S: Into<String>>( path: P, url: S, ) -> Result<Option<Self>, Error>

Like Self::with_path(), but read-only without auto-cloning the index at url if it’s not already present at path.

pub fn path(&self) -> &Path

Get the index directory.

pub fn url(&self) -> &str

Get the index url.

pub fn changes(&self) -> Result<Changes<'_>, Error>

List crates that have changed (published or yanked), in reverse chronological order.

This iterator is aware of periodic index squashing crates.io performs, and will perform (slow and blocking) network requests to fetch the additional history from https://github.com/rust-lang/crates.io-index-archive if needed.

If you want to track newly added/changed crates over time, make a note of the last commit or timestamp you’ve processed, and stop iteration on it next time.

Crates will be reported multiple times, once for each publish/yank/unyank event that happened.

If you like to know publication dates of all crates, consider https://crates.io/data-access instead.

pub fn update(&mut self) -> Result<(), Error>

Fetches latest from the remote index repository. Note that using this method will mean no cache entries will be used, if a new commit is fetched from the repository, as their commit version will no longer match.

pub fn crate_(&self, name: &str) -> Option<Crate>

Reads a crate from the index, it will attempt to use a cached entry if one is available, otherwise it will fallback to reading the crate directly from the git blob containing the crate information.

Use this only if you need to get very few crates. If you’re going to read majority of crates, prefer the GitIndex::crates() iterator.

pub fn crates(&self) -> Crates<'_>

Single-threaded iterator over all the crates in the index.

GitIndex::crates_parallel is typically 4 times faster.

Skips crates that can not be parsed (but there shouldn’t be any such crates in the crates-io index). Also consider to enable git-index-performance feature toggle for better performance.

pub fn crates_parallel( &self, ) -> impl ParallelIterator<Item = Result<Crate, CratesIterError>> + '_

Available on crate feature parallel only.

Iterate over all crates using rayon.

This method is available only if the “parallel” feature is enabled. Also consider to enable git-index-performance feature toggle for better performance.

pub fn index_config(&self) -> Result<IndexConfig, Error>

Get the global configuration of the index.