The [bans]
section
Contains all of the configuration for cargo deny check bans
Example Config
[bans]
multiple-versions = "deny"
wildcards = "deny"
allow-wildcard-paths = true
highlight = "simplest-path"
workspace-default-features = "warn"
external-default-features = "deny"
allow = [
{ name = "all-versionsa" },
{ name = "specific-versiona", version = "<0.1.1" },
]
skip-tree = [{ name = "blah", depth = 20 }]
[[bans.deny]]
name = "all-versionsd"
wrappers = ["specific-versiona"]
[[bans.deny]]
name = "specific-versiond"
version = "=0.1.9"
[[bans.skip]]
name = "rand"
version = "=0.6.5"
[[bans.features]]
name = "featured-krate"
version = "1.0"
deny = ["bad-feature"]
allow = ["good-feature"]
exact = true
The multiple-versions
field (optional)
Determines what happens when multiple versions of the same crate are encountered.
deny
- Will emit an error for each crate with duplicates and fail the check.warn
(default) - Prints a warning for each crate with duplicates, but does not fail the check.allow
- Ignores duplicate versions of the same crate.
The wildcards
field (optional)
Determines what happens when a dependency is specified with the *
(wildcard) version.
deny
- Will emit an error for each crate specified with a wildcard version.warn
(default) - Prints a warning for each crate with a wildcard version, but does not fail the check.allow
- Ignores all wildcard version specifications.
The allow-wildcard-paths
field (optional)
If specified, alters how the wildcard
field behaves:
- path
dependencies
in private crates will no longer emit a warning or error. - path
dev-dependencies
in both public and private crates will no longer emit a warning or error. - path
dependencies
andbuild-dependencies
in public crates will continue to produce warnings and errors.
Being limited to private crates is due to crates.io not allowing packages to be published with path
dependencies except for dev-dependencies
.
The highlight
field (optional)
When multiple versions of the same crate are encountered and multiple-versions
is set to warn
or deny
, using the -g <dir>
option will print out a dotgraph of each of the versions and how they were included into the graph. This field determines how the graph is colored to help you quickly spot good candidates for removal or updating.
lowest-version
- Highlights the path to the lowest duplicate version. Highlighted insimplest-path
- Highlights the path to the duplicate version with the fewest number of total edges to the root of the graph, which will often be the best candidate for removal and/or upgrading. Highlighted in.
all
- Highlights both thelowest-version
andsimplest-path
. If they are the same, they are only highlighted in.
Crate specifier
The allow
, deny
, features
, skip
, and skip-tree
fields all use a crate identifier to specify what crate(s) they want to match against.
{ name = "some-crate-name-here", version = "<= 0.7.0" }
The name
field
The name of the crate.
The version
field (optional)
An optional version constraint specifying the range of crate versions that will match. Defaults to any version.
The deny
field (optional)
deny = [{ name = "crate-you-don't-want", version = "<= 0.7.0" }]
Determines specific crates that are denied.
The wrappers
field (optional)
deny = [{ name = "crate-you-don't-want", version = "<= 0.7.0", wrappers = ["this-can-use-it"] }]
This field allows specific crates to have a direct dependency on the banned crate but denies all transitive dependencies on it.
The deny-multiple-versions
field (optional)
multiple-versions = 'allow'
deny = [{ name = "crate-you-want-only-one-version-of", deny-multiple-versions = true }]
This field allows specific crates to deny multiple versions of themselves, but allowing or warning on multiple versions for all other crates. This field cannot be set simultaneously with wrappers
.
The allow
field (optional)
Determines specific crates that are allowed. If the allow
list has one or more entries, then any crate not in that list will be denied, so use with care.
The external-default-features
field (optional)
Determines the lint level used for when the default
feature is enabled on a crate not in the workspace. This lint level will can then be overridden on a per-crate basis if desired.
For example, if an-external-crate
had the default
feature enabled it could be explicitly allowed.
[bans]
external-default-features = "deny"
[[bans.features]]
name = "an-external-crate"
allow = ["default"]
The workspace-default-features
field (optional)
The workspace version of external-default-features
.
[bans]
external-default-features = "allow"
[[bans.features]]
name = "a-workspace-crate"
deny = ["default"]
The features
field (optional)
[[bans.features]]
name = "featured-krate"
version = "1.0"
deny = ["bad-feature"]
allow = ["good-feature"]
exact = true
Allows specification of crate specific allow/deny lists of features.
The features.deny
field (optional)
Denies specific features for the crate.
The features.allow
field (optional)
Allows specific features for the crate, enabled features not in this list are denied.
The features.exact
field (optional)
If specified, requires that the features in allow
exactly match the features enabled on the crate, and will fail if features are allowed that are not enabled.
The skip
field (optional)
When denying duplicate versions, it's often the case that there is a window of time where you must wait for, for example, PRs to be accepted and new version published, before 1 or more duplicates are gone. The skip
field allows you to temporarily ignore a crate during duplicate detection so that no errors are emitted, until it is no longer need.
It is recommended to use specific version constraints for crates in the skip
list, as cargo-deny will emit warnings when any entry in the skip
list no longer matches a crate in your graph so that you can cleanup your configuration.
The skip-tree
field (optional)
When dealing with duplicate versions, it's often the case that a particular crate acts as a nexus point for a cascade effect, by either using bleeding edge versions of certain crates while in alpha or beta, or on the opposite end of the spectrum, a crate is using severely outdated dependencies while much of the rest of the ecosystem has moved to more recent versions. In both cases, it can be quite tedious to explicitly skip
each transitive dependency pulled in by that crate that clashes with your other dependencies, which is where skip-tree
comes in.
skip-tree
entries are similar to skip
in that they are used to specify a crate name and version range that will be skipped, but they also have an additional depth
field used to specify how many levels from the crate will also be skipped. A depth of 0
would be the same as specifying the crate in the skip
field.
Note that by default, the depth
is infinite.
NOTE: skip-tree
is a very big hammer at the moment, and should be used with care.
The allow-build-scripts
field (optional)
Specifies all the crates that are allowed to have a build script. If this option is omitted, all crates are allowed to have a build script, and if this option is set to an empty list, no crate is allowed to have a build script.