Skip to content

Commit e0e1a6e

Browse files
authored
docs: Clarify git sources vs git registries in source replacement documentation (#15974)
### What does this PR try to resolve? This PR addresses confusion in the documentation around git sources and git registries that has been causing frustrating user experiences. The current documentation is unclear about the purpose of git sources and doesn't mention that they're not usable for replacing registries, leading users to mistakenly assume git sources can replace registries using the git protocol. Fixes #15971 ### How to test and review this PR? - Documentation build verification: Ensure the markdown renders correctly and all cross-references work - Link validation: Verify all new reference links point to existing documentation sections - Content accuracy: Confirm technical explanations are correct and align with Cargo's actual behavior
2 parents 966f947 + c440e21 commit e0e1a6e

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)