docs: Clarify git sources vs git registries in source replacement documentation #15974

Anshumancanrock · 2025-09-16T18:40:32Z

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

rustbot · 2025-09-16T18:40:37Z

r? @epage

rustbot has assigned @epage.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

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

epage · 2025-09-16T19:20:45Z

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

+# Git sources are only used to identify git-based dependencies
+# to replace when vendoring
+[source."git+https://example.com/project/crate"]


While this doesn't fit within the literal intent of the document (see https://github.com/rust-lang/cargo/pull/15974/files#r2353426174), I think it can fit within the spirit of it but we should probably update the comment for the-source-name to clarify that that is for registry sources

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

Anshumancanrock · 2025-09-16T19:35:18Z

@epage Thanks for the detailed feedback! I’ve addressed all the issues to the best of my knowledge. Please let me know if you’d like any other changes.

epage · 2025-09-16T19:44:16Z

This PR has two commits just titled "fix". Could you make them clearer in what they do?

As heads up, we tend to prefer a clean, atomic commit history and are fine having commits edited in response to review feedback

epage · 2025-09-16T19:45:28Z

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

 replace-with = "my-vendor-source"

 # Each source has its own table where the key is the name of the source
+# This example shows a registry source configuration


My intention for something being said was for if you kept [source."git+https://example.com/project/crate"]. Without it, this becomes misleading and should be removed

epage · 2025-09-16T19:47:08Z

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

+# HTTPS git protocol (legacy)
+registry = "https://example.com/path/to/index"


Looking at https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols, I'm not seeing anything about this being legacy

epage · 2025-09-16T19:52:03Z

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

 Git sources represent repositories used by [git-based dependencies]. They're
-used by `cargo vendor` to replace git-based dependencies with local directories.
+used to replace git-based dependencies with alternative sources during vendoring.


Isn't this for specifying the git dependency to then replace it with another source, like directory?

Anshumancanrock · 2025-09-16T20:00:47Z

@epage Thanks sir for the additional feedback! I've addressed latest suggestions please let me know if you would like any other changes.

epage · 2025-09-16T20:17:35Z

This PR has two commits just titled "fix". Could you make them clearer in what they do?

As heads up, we tend to prefer a clean, atomic commit history and are fine having commits edited in response to review feedback

@Anshumancanrock wanted to make sure you saw my message earlier

Anshumancanrock · 2025-09-16T20:42:31Z

@Anshumancanrock wanted to make sure you saw my message earlier

Thanks for the reminder! I saw your earlier message and I’m updating the commits accordingly. I’ll make sure to keep this in mind for future commits and PRs. Please let me know if you’d like any other changes.

Update cargo submodule 17 commits in 966f94733bbc94ca51ff9f1e4c49ad250ebbdc50..f2932725b045d361ff5f18ba02b1409dd1f44e71 2025-09-16 17:24:45 +0000 to 2025-09-24 11:31:26 +0000 - fix: use `host-tuple` for host target subsitution (rust-lang/cargo#16003) - test(build-std): move away from panic_immediate_abort (rust-lang/cargo#16006) - fix: Sparse URLs in `TomlLockfileSourceId` (rust-lang/cargo#15990) - refactor(gctx): extract toml dotted keys validation (rust-lang/cargo#15998) - feat: Add lint for global use of `hint-mostly-unused` (rust-lang/cargo#15995) - Make GlobalContext Sync (rust-lang/cargo#15967) - chore(deps): update cargo-semver-checks to v0.44.0 (rust-lang/cargo#15993) - fix(frontatter): Only allow horizontal whitespace after fences (rust-lang/cargo#15975) - docs: Add Lockfile schemas docs (rust-lang/cargo#15989) - Add parallel frontend to the build performance guide (rust-lang/cargo#15970) - chore(deps): update msrv (3 versions) to v1.88 (rust-lang/cargo#15988) - chore(deps): update msrv (1 version) to v1.90 (rust-lang/cargo#15984) - feat(cargo-util-schemas): Move lockfile schemas (rust-lang/cargo#15980) - Clarify multiple version requirement behavior (rust-lang/cargo#15979) - Adds ghostty as supported terminal for term integration (OSC 9;4) (rust-lang/cargo#15977) - docs(team): Fixed broken office hours link (rust-lang/cargo#15976) - docs: Clarify git sources vs git registries in source replacement documentation (rust-lang/cargo#15974) r? ghost

rustbot assigned epage Sep 16, 2025

rustbot added A-documenting-cargo-itself Area: Cargo's documentation S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Sep 16, 2025