Skip to content

Commit c440e21

Browse files
docs: clarify git sources vs git registries in source-replacement.md
1 parent 966f947 commit c440e21

File tree

1 file changed

+36
-9
lines changed

1 file changed

+36
-9
lines changed

src/doc/src/reference/source-replacement.md

Lines changed: 36 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,12 @@
11
# Source Replacement
22

3-
This document is about replacing the crate index. You can read about overriding
4-
dependencies in the [overriding dependencies] section of this
5-
documentation.
3+
This document is about redirecting communication with [registries]
4+
or repositories of [git-based dependencies] to another data source, such as a
5+
server mirroring the original registry or an exact local copy.
6+
7+
If you want to patch individual dependencies, see [overriding dependencies] section of this
8+
documentation. If you want to control how Cargo makes network requests, see [`[http]`](config.md#http)
9+
and [`[net]`](config.md#net) configuration.
610

711
A *source* is a provider that contains crates that may be included as
812
dependencies for a package. Cargo supports the ability to **replace one source
@@ -87,13 +91,26 @@ git = "https://example.com/path/to/repo"
8791

8892
## Registry Sources
8993

90-
A "registry source" is one that is the same as crates.io itself. That is, it has
91-
an index served in a git repository which matches the format of the
92-
[crates.io index](https://github.com/rust-lang/crates.io-index). That repository
93-
then has configuration indicating where to download crates from.
94+
A "registry source" is one that works like crates.io itself. It's an index
95+
that conforms to the specification at https://doc.rust-lang.org/cargo/reference/registry-index.html
96+
with a configuration file indicating where to download crates from.
97+
98+
Registry sources can use [either git or sparse HTTP protocol][protocols]:
99+
100+
```toml
101+
# Git protocol
102+
registry = "ssh://git@example.com/path/to/index.git"
94103

95-
Currently there is not an already-available project for setting up a mirror of
96-
crates.io. Stay tuned though!
104+
# Sparse HTTP protocol
105+
registry = "sparse+https://example.com/path/to/index"
106+
107+
# HTTPS git protocol
108+
registry = "https://example.com/path/to/index"
109+
```
110+
111+
[protocols]: registries.md#registry-protocols
112+
113+
[crates.io index]: https://doc.rust-lang.org/cargo/reference/registry-index.html
97114

98115
## Local Registry Sources
99116

@@ -131,3 +148,13 @@ is placed on the name of each directory.
131148
Each crate in a directory source also has an associated metadata file indicating
132149
the checksum of each file in the crate to protect against accidental
133150
modifications.
151+
152+
## Git sources
153+
154+
Git sources represent repositories used by [git-based dependencies]. They're
155+
used to specify which git-based dependencies should be replaced with alternative sources.
156+
157+
Git sources are *not* related to the [git registries][protocols],
158+
and can't be used to replace registry sources.
159+
160+
[git-based dependencies]: specifying-dependencies.md#specifying-dependencies-from-git-repositories

0 commit comments

Comments
 (0)