Struct crates_index_diff::Index

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

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: Option<BString>

The name of the symbolic name of the remote to fetch from. If None, obtain the remote name from the configuration of the currently checked-out branch.

Implementations

impl Index

Find changes without modifying the underling repository

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

As peek_changes_with_options(), but without the options.

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

As peek_changes() but provides changes similar to those in the crates index.

pub fn peek_changes_with_options<P>( &self, progress: P, should_interrupt: &AtomicBool, order: Order ) -> Result<(Vec<Change>, ObjectId), Error>

where P: NestedProgress, P::SubProgress: 'static,

Return all Changes that are observed between the last time peek_changes*(…) was called and the latest state of the crates.io index repository, which is obtained by fetching the remote called origin or whatever is configured for the current HEAD branch and lastly what it should be based on knowledge about he crates index. The Self::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 Self::last_seen_reference() to that object, the effect is exactly the same as if Self::fetch_changes() had been called.

The progress and should_interrupt parameters are used to provide progress for fetches and allow these operations to be interrupted gracefully.

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 changes_between_commits( &self, from: impl Into<ObjectId>, to: impl Into<ObjectId> ) -> Result<Vec<Change>, Error>

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

Returns

A list of atomic changes that were performed on the index between the two revisions.

Grouping and Ordering

The changes are grouped by the crate they belong to. The order of the changes for each crate is deterministic as they are ordered by line number, ascending. The order of crates is non-deterministic.

If a specific order is required, the changes must be sorted by the caller.

pub fn changes_between_ancestor_commits( &self, ancestor_commit: impl Into<ObjectId>, current_commit: impl Into<ObjectId> ) -> Result<(Vec<Change>, Order), Error>

Similar to Self::changes(), but requires ancestor_commit and current_commit objects to be provided with ancestor_commit being in the ancestry of current_commit.

If the invariants regarding ancestor_commit and current_commit are not upheld, we fallback to changes_between_commits() which doesn’t have such restrictions. This can happen if the crates-index was squashed for instance.

Returns

A list of atomic changes that were performed on the index between the two revisions, but looking at it one commit at a time, along with the Order that the changes are actually in in case one of the invariants wasn’t met.

Grouping and Ordering

Note that the order of the changes for each crate is deterministic, should they happen within one commit, as the ordering is imposed to be by line number, ascending. Typically one commit does not span multiple crates, but if it does, for instance when rollups happen, then the order of crates is also non-deterministic.

impl Index

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

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

As fetch_changes_with_options(), but without the options.

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

As fetch_changes(), but returns an ordered result.

pub fn fetch_changes_with_options<P>( &self, progress: P, should_interrupt: &AtomicBool, order: Order ) -> Result<Vec<Change>, Error>

where P: NestedProgress, P::SubProgress: 'static,

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 Self::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.

The progress and should_interrupt parameters are used to provide progress for fetches and allow these operations to be interrupted gracefully.

order configures how changes should be ordered.

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: ObjectId) -> Result<(), Error>

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

Returns

A list of atomic chanes that were performed on the index between the two revisions.

Grouping and Ordering

The changes are grouped by the crate they belong to. The order of the changes for each crate is deterministic as they are ordered by line number, ascending. The order of crates is also non-deterministic.

If a specific order is required, the changes must be sorted by the caller.

impl Index

Initialization

pub fn from_path_or_cloned_with_options<P>( path: impl AsRef<Path>, progress: P, should_interrupt: &AtomicBool, _: CloneOptions ) -> Result<Index, Error>

where P: NestedProgress, P::SubProgress: 'static,

Return a new Index instance from the given path, which should contain a 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 std::sync::atomic::AtomicBool;
use crates_index_diff::{Index, index, git};

// Note that credentials are automatically picked up from the standard git configuration.
let mut options = index::CloneOptions {
  url: "https://github.com/rust-lang/staging.crates.io-index".into(),
};


let index = Index::from_path_or_cloned_with_options(path, gix::progress::Discard, &AtomicBool::default(), options)?;

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

impl Index

Access

pub fn repository(&self) -> &Repository

Return the crates.io repository.

pub fn repository_mut(&mut self) -> &mut Repository

Return the crates.io repository, mutably.

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

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