Cargo FAQ, Glossary, and Git Authentication
Purpose and Scope
This page groups three Cargo support topics that readers usually need after they already know the basic cargo build, cargo test, and Cargo.toml workflow: the Cargo FAQ, the Cargo glossary, and Git authentication. The FAQ explains why Cargo uses crates.io as the central registry while still supporting Git dependencies. The glossary gives precise meanings for words such as package, crate, manifest, feature, artifact, index, and lock file. The Git authentication appendix explains how Cargo authenticates when a dependency or registry requires private access.
The Rust repository is useful evidence for these topics because it contains many real manifests rather than only tutorial examples. The requested source files show package metadata, path dependencies, optional dependencies, feature sets, a proc-macro library target, an explicit binary target, workspace membership, lint inheritance, and repository metadata. These examples are not the implementation of Cargo itself, but they show how Cargo terminology appears in first-party Rust projects that are built, checked, and distributed as part of the Rust source tree. Sources: compiler/rustc_index_macros/Cargo.toml, compiler/rustc_index/Cargo.toml, src/tools/error_index_generator/Cargo.toml, src/tools/rust-analyzer/lib/line-index/Cargo.toml
Use this page as a reference when a Cargo support question is really a terminology question. For example, an error about a feature may refer to a named dependency feature in a manifest, an unstable Cargo feature, a compiler feature gate, or a CPU target feature. Likewise, the word index can mean Cargo's registry index in the Cargo Book, but in compiler internals it can also name a typed indexing data structure. Disambiguating the term first often makes the next command or configuration change clear. Sources: compiler/rustc_ast_lowering/src/index.rs, compiler/rustc_index_macros/src/lib.rs
Relevant Source Files
compiler/rustc_index_macros/Cargo.toml— Defines therustc_index_macrospackage, uses edition 2024, declares a proc-macro library, lists external dependencies, and exposes anightlyfeature.compiler/rustc_index/Cargo.toml— Defines therustc_indexpackage, shows local path dependencies, optional dependencies, a default feature, and feature forwarding torustc_index_macros/nightly.src/tools/error_index_generator/Cargo.toml— Defines theerror_index_generatorpackage, places it in the../rustbookworkspace, and declares an explicit binary target namederror_index_generator.src/tools/rust-analyzer/lib/line-index/Cargo.toml— Defines theline-indexpackage with public package metadata such as description, license, repository URL, edition, dependencies, dev-dependencies, and workspace lint inheritance.compiler/rustc_ast_lowering/src/index.rs— Usesrustc_index::IndexVecwhile building a HIR map, demonstrating that Rust compiler internals also use the word index for typed compiler data structures.compiler/rustc_index_macros/src/lib.rs— Exposes thenewtype_indexproc macro and documents the generated index newtype contract used withIndexVecand related structures.
Cargo Support Topics in Context
The Cargo FAQ frames Cargo's package-source model. The official answer is that Cargo is not trying to use GitHub as the package repository; crates.io is the central registry model, while Git repositories remain supported for early development, temporary patches, and other workflows that should not require publishing a package. That distinction matters when debugging a dependency problem. A dependency fetched from a registry follows registry metadata and lock-file rules, while a Git dependency may involve network credentials, branch or revision selection, and repository access.
The glossary supplies the vocabulary needed to read manifests in this repository. A package is described by a manifest named Cargo.toml; a crate is the library or executable target produced by a package; an artifact is the output of compilation; a feature is a named conditional-compilation or dependency-selection flag in one context, but can mean something else in Cargo, rustc, rustdoc, or CPU targeting contexts. The rustc_index_macros manifest is a compact package example: it names the package, declares edition 2024, marks the library as a proc macro, and lists dependencies on proc-macro2, quote, and syn. Sources: compiler/rustc_index_macros/Cargo.toml
Git authentication belongs with FAQ and glossary material because many private dependency failures look like Cargo syntax problems until the dependency source is identified. The official Git authentication appendix says Cargo supports authentication for Git dependencies and registries, can use Git credential helpers for HTTPS, expects SSH authentication through an agent and keys, and can delegate fetching to the system Git executable with net.git-fetch-with-cli or the CARGO_NET_GIT_FETCH_WITH_CLI=true environment variable. Public Git dependencies should not need authentication, so an authentication failure for a public URL is often a sign of an incorrect URL rather than a missing password.
Glossary Terms Mapped to Repository Manifests
A manifest is the Cargo.toml file that tells Cargo what package or workspace member it is handling. The requested manifests show several useful shapes. compiler/rustc_index/Cargo.toml names a compiler crate package and records dependencies. Some dependencies are local path dependencies, such as rustc_index_macros = { path = "../rustc_index_macros" }, which tells Cargo to resolve that dependency from the repository tree rather than from crates.io. Other dependencies are optional, such as rustc_macros, rustc_serialize, and smallvec, which means they are activated through features instead of always being compiled. Sources: compiler/rustc_index/Cargo.toml
A feature is visible in these manifests as a named switch that expands to dependency activations or other feature activations. In rustc_index, the default feature list includes nightly. The nightly feature then activates optional dependencies through dep: entries and forwards a feature to rustc_index_macros/nightly. That is a concrete example of glossary language: a feature can refer to optional dependencies, and a feature in one package can enable a feature in another package. It also shows why feature names are part of a package contract, even when the package version is 0.0.0 inside the compiler tree. Sources: compiler/rustc_index/Cargo.toml, compiler/rustc_index_macros/Cargo.toml
A crate target is the library or executable unit Cargo builds from a package. compiler/rustc_index_macros/Cargo.toml declares [lib] proc-macro = true, so the package's library crate is a procedural macro crate. src/tools/error_index_generator/Cargo.toml instead uses a [[bin]] table with name = "error_index_generator" and path = "main.rs", so Cargo has an explicit executable target to build. The glossary distinction between package and crate is practical here: one manifest describes the package, while one or more targets in that manifest produce compiled artifacts. Sources: compiler/rustc_index_macros/Cargo.toml, src/tools/error_index_generator/Cargo.toml
Workspace membership is another glossary-adjacent concept. src/tools/error_index_generator/Cargo.toml sets workspace = "../rustbook", which indicates that the package participates in a workspace rooted outside the package directory. src/tools/rust-analyzer/lib/line-index/Cargo.toml uses [lints] workspace = true, inheriting lint configuration from its workspace. These two examples show that a package manifest can be local to one crate while still relying on workspace-level policy for dependency resolution, build coordination, or lint configuration. Sources: src/tools/error_index_generator/Cargo.toml, src/tools/rust-analyzer/lib/line-index/Cargo.toml
Git Authentication Reference
When a manifest uses registry dependencies such as text-size = "1.1.1", nohash-hasher = "0.2.0", mdbook-driver = "0.5.1", or syn = { version = "2.0.9", features = ["full", "extra-traits"] }, Cargo normally resolves them through a registry. If the registry is public crates.io, no Git authentication is part of the ordinary fetch path. If a project uses a private registry or Git dependency, authentication enters the workflow. In that case, treat the source kind as the first debugging branch: registry credentials, HTTPS Git credentials, SSH agent setup, and command-line Git delegation are different fixes.
For HTTPS Git authentication, the official Cargo Book points to Git's credential.helper mechanism. Cargo does not prompt for passwords interactively in the way a manual git clone might, so credentials often need to be primed before running Cargo. For SSH authentication, Cargo expects an agent such as ssh-agent to have the correct keys loaded, with environment variables such as SSH_AUTH_SOCK set on Unix-like systems. On Windows, Git for Windows, GCM, Pageant, or ssh-agent may be involved depending on the chosen setup.
A practical troubleshooting sequence is: confirm whether the dependency is from a registry, a path, or Git; verify that a public URL is spelled correctly before adding credentials; run a direct Git operation if you need to initialize a credential helper; and set CARGO_NET_GIT_FETCH_WITH_CLI=true when Cargo's built-in Git support is not compatible with the authentication method your environment requires. The repository manifests in this page mostly show registry and path dependencies, so they are good contrast cases for understanding when Git authentication is not expected. Sources: compiler/rustc_index/Cargo.toml, src/tools/rust-analyzer/lib/line-index/Cargo.toml
Implementation Signals from Index-Related Crates
The requested sources include packages with index in their names, and they are a useful reminder that Cargo's glossary term index is not the only meaning of the word. In the Cargo glossary, the index is the searchable list of crates in a registry. In the compiler sources, rustc_index is a package providing typed index-oriented data structures, and compiler/rustc_ast_lowering/src/index.rs uses IndexVec<ItemLocalId, ParentedNode<'hir>> while collecting HIR nodes into a map. That source file is about compiler representation, not registry metadata. Sources: compiler/rustc_ast_lowering/src/index.rs, compiler/rustc_index/Cargo.toml
The rustc_index_macros crate deepens that distinction. Its public proc macro newtype_index creates a struct type usable as an index with IndexVec and related structures. The macro documentation describes conversions from usize or u32, conversion back to u32, the new and index methods, a u32 internal representation, default derived traits, and customization attributes such as #[stable_hash], #[encodable], #[orderable], #[debug_format = "Foo({})"], #[max = 0xFFFF_FFFD], and #[gate_rustc_only]. Sources: compiler/rustc_index_macros/src/lib.rs
That source-level contract matters for Cargo terminology because package names are not definitions. A package named rustc_index is still described by a Cargo manifest and participates in Cargo dependency and feature resolution. Separately, the code inside that package can define compiler indexes, typed IDs, and HIR maps. When reading errors, documentation, or manifests, first identify whether the term is being used by Cargo, the compiler implementation, or the project domain. That simple classification prevents confusing a registry index problem with a compiler data-structure type or a package name. Sources: compiler/rustc_ast_lowering/src/index.rs, compiler/rustc_index_macros/src/lib.rs
Compact Reference
| Topic | Concrete name or setting | Meaning in this page | Source |
|---|---|---|---|
| Package | name = "rustc_index" | Cargo package identity for the compiler index crate | compiler/rustc_index/Cargo.toml |
| Package | name = "rustc_index_macros" | Cargo package identity for the proc-macro support crate | compiler/rustc_index_macros/Cargo.toml |
| Library target | proc-macro = true | Builds a procedural macro crate rather than an ordinary library | compiler/rustc_index_macros/Cargo.toml |
| Binary target | [[bin]] name = "error_index_generator" | Declares an executable target with path = "main.rs" | src/tools/error_index_generator/Cargo.toml |
| Path dependency | rustc_index_macros = { path = "../rustc_index_macros" } | Resolves a dependency from the local repository tree | compiler/rustc_index/Cargo.toml |
| Optional dependency | smallvec = { version = "1.8.1", optional = true } | Dependency activated by a feature rather than always enabled | compiler/rustc_index/Cargo.toml |
| Feature | default = ["nightly"] | Default feature activation for the package | compiler/rustc_index/Cargo.toml |
| Workspace | workspace = "../rustbook" | Package participates in a workspace rooted at another path | src/tools/error_index_generator/Cargo.toml |
| Lint inheritance | [lints] workspace = true | Uses workspace-defined lint settings | src/tools/rust-analyzer/lib/line-index/Cargo.toml |
| Proc macro API | newtype_index(input: TokenStream) -> TokenStream | Generates typed index newtypes for IndexVec-style use | compiler/rustc_index_macros/src/lib.rs |
Next Steps
When you encounter a Cargo support issue, start by translating the error into glossary terms. Ask whether the failing item is a package, target, crate, feature, artifact, lock-file entry, registry index lookup, path dependency, or Git dependency. Then inspect the relevant Cargo.toml fields before changing global configuration. The manifests on this page give concrete patterns for local path dependencies, optional dependencies, feature forwarding, binary targets, proc-macro crates, workspace membership, and lint inheritance.
If the issue mentions private repositories, SSH, HTTPS credentials, or registry authentication, follow the Git authentication path instead of changing unrelated manifest fields. Confirm whether Cargo should be using built-in Git support or the system Git executable, and only add credentials when the dependency source actually requires them. For broader Cargo workflows, continue with the pages on Cargo getting started, manifests and workspaces, Cargo commands, and publishing to crates.io.