itsscb/cargo
1
0
Fork 0
mirror of https://github.com/rust-lang/cargo.git synced 2025-09-25 11:14:46 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: clarify git sources vs git registries in source-replacement.md

Browse Source
This commit is contained in:
anshumancanrock 2025-09-17 02:07:33 +05:30
parent 966f94733b
commit c440e216a8
1 changed files with 36 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

45
src/doc/src/reference/source-replacement.md
View File

@ -1,8 +1,12 @@
# Source Replacement
This document is about replacing the crate index. You can read about overriding
dependencies in the [overriding dependencies] section of this
documentation.
This document is about redirecting communication with [registries]
or repositories of [git-based dependencies] to another data source, such as a
server mirroring the original registry or an exact local copy.
If you want to patch individual dependencies, see [overriding dependencies] section of this
documentation. If you want to control how Cargo makes network requests, see [`[http]`](config.md#http)
and [`[net]`](config.md#net) configuration.
A *source* is a provider that contains crates that may be included as
dependencies for a package. Cargo supports the ability to **replace one source
@ -87,13 +91,26 @@ git = "https://example.com/path/to/repo"
## Registry Sources
A "registry source" is one that is the same as crates.io itself. That is, it has
an index served in a git repository which matches the format of the
[crates.io index](https://github.com/rust-lang/crates.io-index). That repository
then has configuration indicating where to download crates from.
A "registry source" is one that works like crates.io itself. It's an index
that conforms to the specification at https://doc.rust-lang.org/cargo/reference/registry-index.html
with a configuration file indicating where to download crates from.
Currently there is not an already-available project for setting up a mirror of
crates.io. Stay tuned though!
Registry sources can use [either git or sparse HTTP protocol][protocols]:
```toml
# Git protocol
registry = "ssh://git@example.com/path/to/index.git"
# Sparse HTTP protocol
registry = "sparse+https://example.com/path/to/index"
# HTTPS git protocol
registry = "https://example.com/path/to/index"
```
[protocols]: registries.md#registry-protocols
[crates.io index]: https://doc.rust-lang.org/cargo/reference/registry-index.html
## Local Registry Sources
@ -131,3 +148,13 @@ is placed on the name of each directory.
Each crate in a directory source also has an associated metadata file indicating
the checksum of each file in the crate to protect against accidental
modifications.
## Git sources
Git sources represent repositories used by [git-based dependencies]. They're
used to specify which git-based dependencies should be replaced with alternative sources.
Git sources are *not* related to the [git registries][protocols],
and can't be used to replace registry sources.
[git-based dependencies]: specifying-dependencies.md#specifying-dependencies-from-git-repositories