Struct GitSource

pub struct GitSource<'gctx> {
    remote: GitRemote,
    locked_rev: Revision,
    source_id: SourceId,
    path_source: Option<RecursivePathSource<'gctx>>,
    short_id: Option<InternedString>,
    ident: InternedString,
    gctx: &'gctx GlobalContext,
    quiet: bool,
}

GitSource contains one or more packages gathering from a Git repository. Under the hood it uses RecursivePathSource to discover packages inside the repository.

Filesystem layout

During a successful GitSource download, at least two Git repositories are created: one is the shared Git database of this remote, and the other is the Git checkout to a specific revision, which contains the actual files to be compiled. Multiple checkouts can be cloned from a single Git database.

Those repositories are located at Cargo’s Git cache directory $CARGO_HOME/git. The file tree of the cache directory roughly looks like:

$CARGO_HOME/git/
├── checkouts/
│  ├── gimli-a0d193bd15a5ed96/
│  │  ├── 8e73ef0/     # Git short ID for a certain revision
│  │  ├── a2a4b78/
│  │  └── e33d1ac/
│  ├── log-c58e1db3de7c154d-shallow/
│  │  └── 11eda98/
└── db/
   ├── gimli-a0d193bd15a5ed96/
   └── log-c58e1db3de7c154d-shallow/

For more on Git cache directory, see “Cargo Home” in The Cargo Book.

For more on the directory format <pkg>-<hash>[-shallow], see ident and ident_shallow.

Locked to a revision

Once a GitSource is fetched, it will resolve to a specific commit revision. This is often mentioned as “locked revision” (locked_rev) throughout the codebase. The revision is written into Cargo.lock. This is essential since we want to ensure a package can compiles with the same set of files when a Cargo.lock is present. With the locked_rev provided, GitSource can precisely fetch the same revision from the Git repository.

Fields

remote: GitRemote

The git remote which we’re going to fetch from.

locked_rev: Revision

The revision which a git source is locked to.

Expected to always be Revision::Locked after the Git repository is fetched.

source_id: SourceId

The unique identifier of this source.

path_source: Option<RecursivePathSource<'gctx>>

The underlying path source to discover packages inside the Git repository.

This gets set to Some after the git repo has been checked out (automatically handled via GitSource::block_until_ready).

short_id: Option<InternedString>

A short string that uniquely identifies the version of the checkout.

This is typically a 7-character string of the OID hash, automatically increasing in size if it is ambiguous.

This is set to Some after the git repo has been checked out (automatically handled via GitSource::block_until_ready).

ident: InternedString

The identifier of this source for Cargo’s Git cache directory. See ident for more.

gctx: &'gctx GlobalContext

quiet: bool

Disables status messages.

Implementations

impl<'gctx> GitSource<'gctx>

pub fn new( source_id: SourceId, gctx: &'gctx GlobalContext, ) -> CargoResult<GitSource<'gctx>>

Creates a git source for the given SourceId.

pub fn url(&self) -> &Url

Gets the remote repository URL.

pub fn read_packages(&mut self) -> CargoResult<Vec<Package>>

Returns the packages discovered by this source. It may fetch the Git repository as well as walk the filesystem if package information haven’t yet updated.

fn mark_used(&self) -> CargoResult<()>

Trait Implementations

impl<'gctx> Debug for GitSource<'gctx>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'gctx> Source for GitSource<'gctx>

fn query( &mut self, dep: &Dependency, kind: QueryKind, f: &mut dyn FnMut(IndexSummary), ) -> Poll<CargoResult<()>>

Attempts to find the packages that match a dependency request.

fn supports_checksums(&self) -> bool

Returns whether or not this source will return IndexSummary items with checksums listed.

fn requires_precise(&self) -> bool

Returns whether or not this source will return IndexSummary items with the precise field in the SourceId listed.

fn source_id(&self) -> SourceId

Returns the SourceId corresponding to this source.

fn block_until_ready(&mut self) -> CargoResult<()>

Block until all outstanding Poll::Pending requests are Poll::Ready.

fn download(&mut self, id: PackageId) -> CargoResult<MaybePackage>

Starts the process to fetch a Package for the given PackageId.

fn finish_download( &mut self, _id: PackageId, _data: Vec<u8>, ) -> CargoResult<Package>

Gives the source the downloaded .crate file.

fn fingerprint(&self, _pkg: &Package) -> CargoResult<String>

Generates a unique string which represents the fingerprint of the current state of the source.

fn describe(&self) -> String

Describes this source in a human readable fashion, used for display in resolver error messages currently.

fn add_to_yanked_whitelist(&mut self, _pkgs: &[PackageId])

Add a number of crates that should be whitelisted for showing up during queries, even if they are yanked. Currently only applies to registry sources.

fn is_yanked(&mut self, _pkg: PackageId) -> Poll<CargoResult<bool>>

Query if a package is yanked. Only registry sources can mark packages as yanked. This ignores the yanked whitelist.

fn invalidate_cache(&mut self)

Ensure that the source is fully up-to-date for the current session on the next query.

fn set_quiet(&mut self, quiet: bool)

If quiet, the source should not display any progress or status messages.

fn replaced_source_id(&self) -> SourceId

Returns the replaced SourceId corresponding to this source.

fn query_vec( &mut self, dep: &Dependency, kind: QueryKind, ) -> Poll<CargoResult<Vec<IndexSummary>>>

Gathers the result from Source::query as a list of IndexSummary items when they become available.

fn download_now( self: Box<Self>, package: PackageId, gctx: &GlobalContext, ) -> CargoResult<Package>

where Self: Sized,

Convenience method used to immediately fetch a Package for the given PackageId.

fn verify(&self, _pkg: PackageId) -> CargoResult<()>

If this source supports it, verifies the source of the package specified.

fn is_replaced(&self) -> bool

Returns whether a source is being replaced by another here.

Layout

Note: Most layout information is completely unstable and may even differ between compilations. The only exception is types with certain repr(...) attributes. Please see the Rust Reference's “Type Layout” chapter for details on type layout guarantees.

Size: 320 bytes