diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 003e5001..885ecd4f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,7 +4,6 @@ Contents * [Config parsing](#config-parsing) * [Lower layer](#lower-layer) * [Higher layer](#higher-layer) - * [Precedence](#precedence) * [Variable resolution](#variable-resolution) * [Rules](#rules) * [Ignore pattern](#ignore-pattern) @@ -96,21 +95,9 @@ example) won't be *seen* by the higher layer until the config is reloaded. Consi `dirty` flag as a sign the file needs to be written and its representation in higher levels in not accurate anymore. -## Precedence - -* `dynvariables` > `variables` -* Profile `(dyn)variables` > any other `(dyn)variables` -* Profile `(dyn)variables` > profile's included `(dyn)variables` -* Imported `variables`/`dynvariables` > `(dyn)variables` - -When `import_configs` importing config's elements except the `(dyn)variables` -will take precedence in case of name clash -(see ). - ## Variable resolution -How variables are resolved (through Jinja2's -templating) in the config file. +How variables are resolved (through Jinja2's templating) in the config file. * Resolve main config file variables * Merge `variables` and `dynvariables` (allowing cyclic references) diff --git a/docs/config/config-profiles.md b/docs/config/config-profiles.md index 3ea99a0a..e830dd55 100644 --- a/docs/config/config-profiles.md +++ b/docs/config/config-profiles.md @@ -1,6 +1,8 @@ # Profiles entry -The **profiles** entry (mandatory) contains a YAML object with sub-objects for the profiles for the different dotfiles that need to be managed. The entries in the sub-objects are as follows: +The mandatory `profiles` entry contains a YAML object with sub-objects defining +each profile and its related dotfiles, variables, actions, and other configurations. +The entries in the sub-objects are as follows: Entry | Description -------- | ------------- @@ -9,7 +11,7 @@ Entry | Description `include` | Include all elements (dotfiles, actions, (dyn)variables, etc) from another profile (See [Include dotfiles from another profile](config-profiles.md#profile-include-entry) and [meta profiles](../howto/group-hosts.md)) `variables` | Profile-specific variables (See [Variables](config-file.md#variables)) `dynvariables` | Profile-specific interpreted variables (See [Interpreted variables](config-dynvars.md)) -`actions` | List of action keys that need to be defined in the **actions** entry below (See [actions](config-actions.md)) +`actions` | List of action keys defined in the [actions](config-actions.md) entry (See [actions](config-actions.md)) ```yaml : diff --git a/docs/config/config-variables.md b/docs/config/config-variables.md index e9d63c72..0e3ea46b 100644 --- a/docs/config/config-variables.md +++ b/docs/config/config-variables.md @@ -1,13 +1,14 @@ # Variables entry -The **variables** entry (optional) contains a variables mapping (See [variables](config-file.md#variables)). +The optional **variables** entry contains a variables mapping (See [variables](config-file.md#variables)). ```yaml variables: : ``` -Variables defined in the `variables` entry are made available within the config file. +Variables defined in the `variables` entry are made available +within the config file and to the [templates](../template/templating.md). For example ```yaml @@ -53,4 +54,54 @@ variables: ``` Where the above would be referenced using `{{@@ rofi.background_color @@}}` -and `{{@@ polybar.background_color @@}}`. \ No newline at end of file +and `{{@@ polybar.background_color @@}}`. + +## Variables precedence + +* `dynvariables` > `variables` +* Profile `(dyn)variables` > any other `(dyn)variables` +* Profile `(dyn)variables` > profile's included `(dyn)variables` +* Imported `(dyn)variables` > `(dyn)variables` (except for `import_configs`) + +When including profiles with `include`, the value of a variable present in multiple +included profiles will come from the last profile graph in the order of the include list. + +In the below example, the variable value is `1`: +```yaml + top: + variables: + foo: 1 + include: + - left + - right + left: + variables: + foo: 2 + right: + variables: + foo: 3 + include: + - bottom + bottom: + variables: + foo: 4 +``` + +In this example, its value is `4` +```yaml + top: + include: + - left + - right + left: + variables: + foo: 2 + right: + include: + - bottom + bottom: + variables: + foo: 4 +``` + +See also [CONTRIBUTING doc](/CONTRIBUTING.md) diff --git a/docs/howto/sharing-content.md b/docs/howto/sharing-content.md index 55ede6e6..027bcdf6 100644 --- a/docs/howto/sharing-content.md +++ b/docs/howto/sharing-content.md @@ -72,7 +72,7 @@ solution consists of using 2. Adding some variables in the merged dotfile via templating. 3. Overriding them with different values in each profile via profile variables. 4. Typically, making the dotfile `dst` dynamic, as different profiles need - usually to deploy the dotfiles in different locations. + usually to deploy their dotfiles to different locations. **NOTE**: This technique does *not* require two different `dotfiles` entry in `config.yaml`.