mirror of
https://github.com/rust-lang/cargo
synced 2024-10-03 22:43:59 +00:00
Update documentation for include/exclude.
This commit is contained in:
parent
6b6ddaa597
commit
4c35895b86
|
@ -342,10 +342,57 @@ links = "foo"
|
||||||
<a id="the-exclude-and-include-fields-optional"></a>
|
<a id="the-exclude-and-include-fields-optional"></a>
|
||||||
#### The `exclude` and `include` fields
|
#### The `exclude` and `include` fields
|
||||||
|
|
||||||
You can explicitly specify that a set of file patterns should be ignored or
|
The `exclude` and `include` fields can be used to explicitly specify which
|
||||||
included for the purposes of packaging. The patterns specified in the
|
files are included when packaging a project to be [published][publishing],
|
||||||
`exclude` field identify a set of files that are not included, and the
|
and certain kinds of change tracking (described below).
|
||||||
patterns in `include` specify files that are explicitly included.
|
The patterns specified in the `exclude` field identify a set of files that are
|
||||||
|
not included, and the patterns in `include` specify files that are explicitly
|
||||||
|
included.
|
||||||
|
You may run [`cargo package --list`][`cargo package`] to verify which files will
|
||||||
|
be included in the package.
|
||||||
|
|
||||||
|
```toml
|
||||||
|
[package]
|
||||||
|
# ...
|
||||||
|
exclude = ["/ci", "images/", ".*"]
|
||||||
|
```
|
||||||
|
|
||||||
|
```toml
|
||||||
|
[package]
|
||||||
|
# ...
|
||||||
|
include = ["/src", "COPYRIGHT", "/examples", "!/examples/big_example"]
|
||||||
|
```
|
||||||
|
|
||||||
|
The default if neither field is specified is to include all files from the
|
||||||
|
root of the package, except for the exclusions listed below.
|
||||||
|
|
||||||
|
If `include` is not specified, then the following files will be excluded:
|
||||||
|
|
||||||
|
* If the package is not in a git repository, all "hidden" files starting with
|
||||||
|
a dot will be skipped.
|
||||||
|
* If the package is in a git repository, any files that are ignored by the
|
||||||
|
[gitignore] rules of the repository and global git configuration will be
|
||||||
|
skipped.
|
||||||
|
|
||||||
|
Regardless of whether `exclude` or `include` is specified, the following files
|
||||||
|
are always excluded:
|
||||||
|
|
||||||
|
* Any sub-packages will be skipped (any subdirectory that contains a
|
||||||
|
`Cargo.toml` file).
|
||||||
|
* A directory named `target` in the root of the package will be skipped.
|
||||||
|
|
||||||
|
The following files are always included:
|
||||||
|
|
||||||
|
* The `Cargo.toml` file of the package itself is always included, it does not
|
||||||
|
need to be listed in `include`.
|
||||||
|
* A minimized `Cargo.lock` is automatically included if the package contains a
|
||||||
|
binary or example target, see [`cargo package`] for more information.
|
||||||
|
* If a [`license-file`](#the-license-and-license-file-fields) is specified, it
|
||||||
|
is always included.
|
||||||
|
|
||||||
|
The options are mutually exclusive; setting `include` will override an
|
||||||
|
`exclude`. If you need to have exclusions to a set of `include` files, use the
|
||||||
|
`!` operator described below.
|
||||||
|
|
||||||
The patterns should be [gitignore]-style patterns. Briefly:
|
The patterns should be [gitignore]-style patterns. Briefly:
|
||||||
|
|
||||||
|
@ -373,26 +420,6 @@ The patterns should be [gitignore]-style patterns. Briefly:
|
||||||
`!foo.rs` would match all files with the `.rs` extension inside the `src`
|
`!foo.rs` would match all files with the `.rs` extension inside the `src`
|
||||||
directory, except for any file named `foo.rs`.
|
directory, except for any file named `foo.rs`.
|
||||||
|
|
||||||
If git is being used for a package, the `exclude` field will be seeded with
|
|
||||||
the `gitignore` settings from the repository.
|
|
||||||
|
|
||||||
```toml
|
|
||||||
[package]
|
|
||||||
# ...
|
|
||||||
exclude = ["build/**/*.o", "doc/**/*.html"]
|
|
||||||
```
|
|
||||||
|
|
||||||
```toml
|
|
||||||
[package]
|
|
||||||
# ...
|
|
||||||
include = ["src/**/*", "Cargo.toml"]
|
|
||||||
```
|
|
||||||
|
|
||||||
The options are mutually exclusive: setting `include` will override an
|
|
||||||
`exclude`. Note that `include` must be an exhaustive list of files as otherwise
|
|
||||||
necessary source files may not be included. The package's `Cargo.toml` is
|
|
||||||
automatically included.
|
|
||||||
|
|
||||||
The include/exclude list is also used for change tracking in some situations.
|
The include/exclude list is also used for change tracking in some situations.
|
||||||
For targets built with `rustdoc`, it is used to determine the list of files to
|
For targets built with `rustdoc`, it is used to determine the list of files to
|
||||||
track to determine if the target should be rebuilt. If the package has a
|
track to determine if the target should be rebuilt. If the package has a
|
||||||
|
@ -518,6 +545,7 @@ more detail.
|
||||||
|
|
||||||
[`cargo init`]: ../commands/cargo-init.md
|
[`cargo init`]: ../commands/cargo-init.md
|
||||||
[`cargo new`]: ../commands/cargo-new.md
|
[`cargo new`]: ../commands/cargo-new.md
|
||||||
|
[`cargo package`]: ../commands/cargo-package.md
|
||||||
[`cargo run`]: ../commands/cargo-run.md
|
[`cargo run`]: ../commands/cargo-run.md
|
||||||
[crates.io]: https://crates.io/
|
[crates.io]: https://crates.io/
|
||||||
[docs.rs]: https://docs.rs/
|
[docs.rs]: https://docs.rs/
|
||||||
|
|
Loading…
Reference in a new issue