Struct crates_index_diff::Index

pub struct Index {
    pub seen_ref_name: &'static str,
    // some fields omitted
}

A wrapper for a repository of the crates.io index.

Fields

seen_ref_name: &'static str

The name and path of the reference used to keep track of the last seen state of the crates.io repository. The default value is refs/heads/crates-index-diff_last-seen.

Implementations

impl Index

pub fn repository(&self) -> &Repository

Return the crates.io repository.

pub fn last_seen_reference(&self) -> Result<Reference<'_>, GitError>

Return the reference pointing to the state we have seen after calling fetch_changes().

pub fn from_path_or_cloned_with_options(
    path: impl AsRef<Path>,
    _: CloneOptions<'_>
) -> Result<Index, GitError>

Return a new Index instance from the given path, which should contain a bare or non-bare clone of the crates.io index. If the directory does not contain the repository or does not exist, it will be cloned from the official location automatically (with complete history).

An error will occour if the repository exists and the remote URL does not match the given repository URL.

Examples

use crates_index_diff::{CloneOptions, Index};

let mut options = CloneOptions {
  repository_url: "https://github.com/rust-lang/staging.crates.io-index".into(),
  ..Default::default()
};


let index = Index::from_path_or_cloned_with_options(path, options)?;

Or to access a private repository, use fetch options.

use crates_index_diff::{CloneOptions, Index};
let fo = {
    let mut fo = git2::FetchOptions::new();
    fo.remote_callbacks({
        let mut callbacks = git2::RemoteCallbacks::new();
        callbacks.credentials(|_url, username_from_url, _allowed_types| {
            git2::Cred::ssh_key_from_memory(
                username_from_url.unwrap(),
                None,
                &std::env::var("PRIVATE_KEY").unwrap(),
                None,
            )
        });
        callbacks
    });
    fo
};
Index::from_path_or_cloned_with_options(
    "index",
    CloneOptions {
        repository_url: "git@github.com:private-index/goes-here.git".into(),
        fetch_options: Some(fo),
    },
).unwrap();

pub fn from_path_or_cloned(path: impl AsRef<Path>) -> Result<Index, GitError>

Return a new Index instance from the given path, which should contain a bare or non-bare clone of the crates.io index. If the directory does not contain the repository or does not exist, it will be cloned from the official location automatically (with complete history).

pub fn peek_changes(&self) -> Result<(Vec<CrateVersion>, Oid), GitError>

As peek_changes_with_options, but without the options.

pub fn peek_changes_with_options(
    &self,
    options: Option<&mut FetchOptions<'_>>
) -> Result<(Vec<CrateVersion>, Oid), GitError>

Return all CrateVersions that are observed between the last time fetch_changes(…) was called and the latest state of the crates.io index repository, which is obtained by fetching the remote called origin. The last_seen_reference() will not be created or updated. The second field in the returned tuple is the commit object to which the changes were provided. If one would set the last_seen_reference() to that object, the effect is exactly the same as if fetch_changes(…) had been called.

Resource Usage

As this method fetches the git repository, loose objects or small packs may be created. Over time, these will accumulate and either slow down subsequent operations, or cause them to fail due to exhaustion of the maximum number of open file handles as configured with ulimit.

Thus it is advised for the caller to run git gc occasionally based on their own requirements and usage patterns.

pub fn fetch_changes(&self) -> Result<Vec<CrateVersion>, GitError>

As fetch_changes_with_options, but without the options.

pub fn fetch_changes_with_options(
    &self,
    options: Option<&mut FetchOptions<'_>>
) -> Result<Vec<CrateVersion>, GitError>

Return all CrateVersions that are observed between the last time this method was called and the latest state of the crates.io index repository, which is obtained by fetching the remote called origin. The last_seen_reference() will be created or adjusted to point to the latest fetched state, which causes this method to have a different result each time it is called.

Resource Usage

As this method fetches the git repository, loose objects or small packs may be created. Over time, these will accumulate and either slow down subsequent operations, or cause them to fail due to exhaustion of the maximum number of open file handles as configured with ulimit.

Thus it is advised for the caller to run git gc occasionally based on their own requirements and usage patterns.

pub fn set_last_seen_reference(&self, to: Oid) -> Result<(), GitError>

Set the last seen reference to the given Oid. It will be created if it does not yet exists.

pub fn changes(
    &self,
    from: impl AsRef<str>,
    to: impl AsRef<str>
) -> Result<Vec<CrateVersion>, GitError>

Return all CreateVersions observed between from and to. Both parameter are ref-specs pointing to either a commit or a tree. Learn more about specifying revisions in the official documentation

pub fn changes_from_objects(
    &self,
    from: &Object<'_>,
    to: &Object<'_>
) -> Result<Vec<CrateVersion>, GitError>

Similar to changes(), but requires from and to objects to be provided. They may point to either Commits or Trees.