Source Replacement documentation is very confusing about git sources

[kornelski]

The documentation is unclear about the purpose of git sources, and doesn't even mention they're not usable for replacing registries. The git sources can be easily confused with registries using the git protocol. Such mistaken assumption causes a lot of frustrating problems and misleading errors in Cargo.

I have a suggested update to the docs, but it's a very bikesheddable thing, so I assume you will want to revise it. Github's PR workflow is a poor fit for document editing (where I'd end up copypasting your edits), so maybe it'll be easier if I just drop a starting point here:

From 3406777efcdb2e8aa39551080cdfaa630cd721e6 Mon Sep 17 00:00:00 2001
From: Kornel <kornelski@users.noreply.github.com>
Date: Tue, 16 Sep 2025 15:27:36 +0100
Subject: [PATCH] Clarify docs for git-based sources

---
 src/doc/src/reference/source-replacement.md | 43 +++++++++++++++------
 1 file changed, 31 insertions(+), 12 deletions(-)

diff --git a/src/doc/src/reference/source-replacement.md b/src/doc/src/reference/source-replacement.md
index 990c9a65d..652e99615 100644
--- a/src/doc/src/reference/source-replacement.md
+++ b/src/doc/src/reference/source-replacement.md
@@ -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
@@ -72,12 +76,16 @@ replace-with = "my-vendor-source"
 replace-with = "another-source"
 
 # Several kinds of sources can be specified (described in more detail below):
-registry = "https://example.com/path/to/index"
+registry = "ssh://git@example.com/path/to/index.git"
+registry = "sparse+https://example.com/path/to/index"
 local-registry = "path/to/registry"
 directory = "path/to/vendor"
 
-# Git sources can optionally specify a branch/tag/rev as well
-git = "https://example.com/path/to/repo"
+# Git sources are only used to identify git-based dependencies
+# to replace when vendoring
+[source."git+https://example.com/project/crate"]
+git = "https://example.com/project/crate"
+# Specify the same branch/tag/rev as the git dependency in `Cargo.toml`
 # branch = "master"
 # tag = "v1.0.1"
 # rev = "313f44e8"
@@ -87,13 +95,13 @@ 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
+which matches the format of the [crates.io index] 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].
+
+[crates.io index]: https://github.com/rust-lang/crates.io-index
 
 ## Local Registry Sources
 
@@ -131,3 +139,14 @@ 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 by `cargo vendor` to replace git-based dependencies with local directories.
+
+Git sources are *not* related to the [git registries][protocols],
+and can't be used to replace registry sources.
+
+[protocols]: registries.md#registry-protocols
+[git-based dependencies]: specifying-dependencies.md#specifying-dependencies-from-git-repositories
--