From 3d668e8f69f614172bcd720af4e8bf5ca162ece9 Mon Sep 17 00:00:00 2001 From: Jeremy Fitzhardinge Date: Sat, 22 Feb 2020 00:05:35 -0800 Subject: [PATCH] Document `CARGO_CONFIG_PATH` --- src/doc/src/reference/config.md | 24 ++++++++++++++++++++---- 1 file changed, 20 insertions(+), 4 deletions(-) diff --git a/src/doc/src/reference/config.md b/src/doc/src/reference/config.md index 6fafaecc962..b3f236bbd7d 100644 --- a/src/doc/src/reference/config.md +++ b/src/doc/src/reference/config.md @@ -4,10 +4,12 @@ This document explains how Cargo’s configuration system works, as well as available keys or configuration. For configuration of a package through its manifest, see the [manifest format](manifest.md). -### Hierarchical structure +### How configuration files are found Cargo allows local configuration for a particular package as well as global -configuration. It looks for configuration files in the current directory and +configuration. It has two mechanisms for this. + +By default, it looks for configuration files in the current directory and all parent directories. If, for example, Cargo were invoked in `/projects/foo/bar/baz`, then the following configuration files would be probed for and unified in this order: @@ -25,10 +27,24 @@ With this structure, you can specify configuration per-package, and even possibly check it into version control. You can also specify personal defaults with a configuration file in your home directory. +Alternatively, if the `CARGO_CONFIG_PATH` environment variable is set, it is +used as a `:`-delimited path of directories. Each of these directories is used +in the order they appear in `CARGO_CONFIG_PATH`. For example the path +`CARGO_CONFIG_PATH=.:..:/projects/common:/home/me` will search in: + +* `./.cargo/config` +* `../.cargo/config` +* `/projects/common/.cargo/config` +* `/home/me/.cargo/config` + +No other directories are searched, including `CARGO_HOME`. + If a key is specified in multiple config files, the values will get merged -together. Numbers, strings, and booleans will use the value in the deeper +together. Numbers, strings, and booleans will use the value in the first +resolved config file - when using heirarchical search, the deeper config directory taking precedence over ancestor directories, where the -home directory is the lowest priority. Arrays will be joined together. +home directory is the lowest priority, and the earlier directory in `CARGO_CONFIG_PATH` +when it is used. Arrays will be joined together. > **Note:** Cargo also reads config files without the `.toml` extension, such as > `.cargo/config`. Support for the `.toml` extension was added in version 1.39