1## Source Replacement
2
3This document is about replacing the crate index. You can read about overriding
4dependencies in the [overriding dependencies] section of this
5documentation.
6
7A *source* is a provider that contains crates that may be included as
8dependencies for a package. Cargo supports the ability to **replace one source
9with another** to express strategies such as:
10
11* Vendoring - custom sources can be defined which represent crates on the local
12  filesystem. These sources are subsets of the source that they're replacing and
13  can be checked into packages if necessary.
14
15* Mirroring - sources can be replaced with an equivalent version which acts as a
16  cache for crates.io itself.
17
18Cargo has a core assumption about source replacement that the source code is
19exactly the same from both sources. Note that this also means that
20a replacement source is not allowed to have crates which are not present in the
21original source.
22
23As a consequence, source replacement is not appropriate for situations such as
24patching a dependency or a private registry. Cargo supports patching
25dependencies through the usage of [the `[patch]` key][overriding
26dependencies], and private registry support is described in [the Registries
27chapter][registries].
28
29[overriding dependencies]: overriding-dependencies.md
30[registries]: registries.md
31
32### Configuration
33
34Configuration of replacement sources is done through [`.cargo/config.toml`][config]
35and the full set of available keys are:
36
37```toml
38# The `source` table is where all keys related to source-replacement
39# are stored.
40[source]
41
42# Under the `source` table are a number of other tables whose keys are a
43# name for the relevant source. For example this section defines a new
44# source, called `my-vendor-source`, which comes from a directory
45# located at `vendor` relative to the directory containing this `.cargo/config.toml`
46# file
47[source.my-vendor-source]
48directory = "vendor"
49
50# The crates.io default source for crates is available under the name
51# "crates-io", and here we use the `replace-with` key to indicate that it's
52# replaced with our source above.
53[source.crates-io]
54replace-with = "my-vendor-source"
55
56# Each source has its own table where the key is the name of the source
57[source.the-source-name]
58
59# Indicate that `the-source-name` will be replaced with `another-source`,
60# defined elsewhere
61replace-with = "another-source"
62
63# Several kinds of sources can be specified (described in more detail below):
64registry = "https://example.com/path/to/index"
65local-registry = "path/to/registry"
66directory = "path/to/vendor"
67
68# Git sources can optionally specify a branch/tag/rev as well
69git = "https://example.com/path/to/repo"
70# branch = "master"
71# tag = "v1.0.1"
72# rev = "313f44e8"
73```
74
75[config]: config.md
76
77### Registry Sources
78
79A "registry source" is one that is the same as crates.io itself. That is, it has
80an index served in a git repository which matches the format of the
81[crates.io index](https://github.com/rust-lang/crates.io-index). That repository
82then has configuration indicating where to download crates from.
83
84Currently there is not an already-available project for setting up a mirror of
85crates.io. Stay tuned though!
86
87### Local Registry Sources
88
89A "local registry source" is intended to be a subset of another registry
90source, but available on the local filesystem (aka vendoring). Local registries
91are downloaded ahead of time, typically sync'd with a `Cargo.lock`, and are
92made up of a set of `*.crate` files and an index like the normal registry is.
93
94The primary way to manage and create local registry sources is through the
95[`cargo-local-registry`][cargo-local-registry] subcommand,
96[available on crates.io][cargo-local-registry] and can be installed with
97`cargo install cargo-local-registry`.
98
99[cargo-local-registry]: https://crates.io/crates/cargo-local-registry
100
101Local registries are contained within one directory and contain a number of
102`*.crate` files downloaded from crates.io as well as an `index` directory with
103the same format as the crates.io-index project (populated with just entries for
104the crates that are present).
105
106### Directory Sources
107
108A "directory source" is similar to a local registry source where it contains a
109number of crates available on the local filesystem, suitable for vendoring
110dependencies. Directory sources are primarily managed by the `cargo vendor`
111subcommand.
112
113Directory sources are distinct from local registries though in that they contain
114the unpacked version of `*.crate` files, making it more suitable in some
115situations to check everything into source control. A directory source is just a
116directory containing a number of other directories which contain the source code
117for crates (the unpacked version of `*.crate` files). Currently no restriction
118is placed on the name of each directory.
119
120Each crate in a directory source also has an associated metadata file indicating
121the checksum of each file in the crate to protect against accidental
122modifications.
123