Struct GitSource

pub struct GitSource<'gctx> { /* private fields */ }

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.

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.

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.