Struct crates_index_diff::Index

source · [−]

pub struct Index {
    pub seen_ref_name: &'static str,
    pub branch_name: &'static str,
    pub remote_name: &'static str,
    /* private fields */
}

Expand description

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.

branch_name: &'static str

The name of the branch to fetch. This value also affects the tracking branch.

remote_name: &'static str

The name of the symbolic name of the remote to fetch from.

Implementations

source

impl Index

Find changes without modifying the underling repository

source

pub fn peek_changes(&self) -> Result<(Vec<Change>, ObjectId), Error>

As peek_changes_with_options, but without the options.

source

pub fn peek_changes_with_options(
&self,
options: Option<&mut FetchOptions<'_>>
) -> Result<(Vec<Change>, ObjectId), Error>

Return all Changes 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.

source

pub fn changes_between_commits(
 &self,
 from: impl Into<ObjectId>,
 to: impl Into<ObjectId>
) -> Result<Vec<Change>, Error>

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

source

impl Index

Find changes while changing the underlying repository in one way or another.

source

pub fn fetch_changes(&self) -> Result<Vec<Change>, Error>

As fetch_changes_with_options, but without the options.

source

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

Return all Changes 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.

source

pub fn set_last_seen_reference(&self, to: ObjectId) -> Result<(), Error>

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

source

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

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

source

impl Index

Initialization

source

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

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::{Index, index};

let mut options = index::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::{index, 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",
    index::CloneOptions {
        repository_url: "git@github.com:private-index/goes-here.git".into(),
        fetch_options: Some(fo),
    },
).unwrap();

source

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

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

source