From adc35c432886dc9a35c2f048517ec5bc83e76a25 Mon Sep 17 00:00:00 2001 From: deadc0de6 <8973919+deadc0de6@users.noreply.github.com.> Date: Wed, 20 May 2026 23:05:54 +0200 Subject: [PATCH 1/3] refactor doc for #469 --- CONTRIBUTING.md | 64 ++++++++++++++------------------- docs/config/config-profiles.md | 6 ++-- docs/config/config-variables.md | 57 +++++++++++++++++++++++++++-- docs/howto/sharing-content.md | 2 +- 4 files changed, 85 insertions(+), 44 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 003e5001c..b95397391 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -96,44 +96,6 @@ 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. - -* Resolve main config file variables - * Merge `variables` and `dynvariables` (allowing cyclic references) - * Recursively template merged `variables` and `dynvariables` - * `dynvariables` are executed - * Profile's `variables` and `dynvariables` are merged -* Resolve *included* entries (see below) - * Paths and entries are templated - (allows using something like `include {{@@ os @@}}.variables.yaml`) -* *included* entries are processed - * dyn-/variables are all resolved in their own file - -Potential *included* entries: - -* Entry *import_actions* -* Entry *import_configs* -* Entry *import_variables* -* Profile's *import* -* Profile's *include* - -Variables are then used to resolve different elements in the config file: -see [this](docs/config/config-file.md#variables). - ## Rules * `dynvariables` are executed in their own config file @@ -209,6 +171,32 @@ for a match with the ignore patterns. * patterns are matched against both files (in dotpath and in filesystem) +## Variable resolution + +How variables are resolved (through Jinja2's templating) in the config file. + +* Resolve main config file variables + * Merge `variables` and `dynvariables` (allowing cyclic references) + * Recursively template merged `variables` and `dynvariables` + * `dynvariables` are executed + * Profile's `variables` and `dynvariables` are merged +* Resolve *included* entries (see below) + * Paths and entries are templated + (allows using something like `include {{@@ os @@}}.variables.yaml`) +* *included* entries are processed + * dyn-/variables are all resolved in their own file + +Potential *included* entries: + +* Entry *import_actions* +* Entry *import_configs* +* Entry *import_variables* +* Profile's *import* +* Profile's *include* + +Variables are then used to resolve different elements in the config file: +see [this](docs/config/config-file.md#variables). + # Testing Dotdrop is tested with the use of the [tests.sh](/tests.sh) script. diff --git a/docs/config/config-profiles.md b/docs/config/config-profiles.md index 3ea99a0ac..520dccccc 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 configuration. +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 that are 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 e9d63c729..0e3ea46b9 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 55ede6e6e..027bcdf63 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`. From 7ff29d2e14a9540f67eb503f22bd1de4da238922 Mon Sep 17 00:00:00 2001 From: deadc0de6 <8973919+deadc0de6@users.noreply.github.com.> Date: Sat, 23 May 2026 22:06:27 +0200 Subject: [PATCH 2/3] fix doc --- CONTRIBUTING.md | 1 - 1 file changed, 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b95397391..fff3c563a 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) From 63246cbc606d924d49a86de36baf95286e8cfc7a Mon Sep 17 00:00:00 2001 From: deadc0de6 <8973919+deadc0de6@users.noreply.github.com.> Date: Sat, 23 May 2026 22:43:42 +0200 Subject: [PATCH 3/3] update doc --- CONTRIBUTING.md | 52 +++++++++++++++++----------------- docs/config/config-profiles.md | 6 ++-- 2 files changed, 29 insertions(+), 29 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fff3c563a..885ecd4f2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -95,6 +95,32 @@ 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. +## Variable resolution + +How variables are resolved (through Jinja2's templating) in the config file. + +* Resolve main config file variables + * Merge `variables` and `dynvariables` (allowing cyclic references) + * Recursively template merged `variables` and `dynvariables` + * `dynvariables` are executed + * Profile's `variables` and `dynvariables` are merged +* Resolve *included* entries (see below) + * Paths and entries are templated + (allows using something like `include {{@@ os @@}}.variables.yaml`) +* *included* entries are processed + * dyn-/variables are all resolved in their own file + +Potential *included* entries: + +* Entry *import_actions* +* Entry *import_configs* +* Entry *import_variables* +* Profile's *import* +* Profile's *include* + +Variables are then used to resolve different elements in the config file: +see [this](docs/config/config-file.md#variables). + ## Rules * `dynvariables` are executed in their own config file @@ -170,32 +196,6 @@ for a match with the ignore patterns. * patterns are matched against both files (in dotpath and in filesystem) -## Variable resolution - -How variables are resolved (through Jinja2's templating) in the config file. - -* Resolve main config file variables - * Merge `variables` and `dynvariables` (allowing cyclic references) - * Recursively template merged `variables` and `dynvariables` - * `dynvariables` are executed - * Profile's `variables` and `dynvariables` are merged -* Resolve *included* entries (see below) - * Paths and entries are templated - (allows using something like `include {{@@ os @@}}.variables.yaml`) -* *included* entries are processed - * dyn-/variables are all resolved in their own file - -Potential *included* entries: - -* Entry *import_actions* -* Entry *import_configs* -* Entry *import_variables* -* Profile's *import* -* Profile's *include* - -Variables are then used to resolve different elements in the config file: -see [this](docs/config/config-file.md#variables). - # Testing Dotdrop is tested with the use of the [tests.sh](/tests.sh) script. diff --git a/docs/config/config-profiles.md b/docs/config/config-profiles.md index 520dccccc..e830dd555 100644 --- a/docs/config/config-profiles.md +++ b/docs/config/config-profiles.md @@ -1,7 +1,7 @@ # Profiles entry -The mandatory profiles entry contains a YAML object with sub-objects defining -each profile and its related dotfiles, variables, actions, and other configuration. +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 @@ -11,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 are defined in the [actions](config-actions.md) entry (See [actions](config-actions.md)) +`actions` | List of action keys defined in the [actions](config-actions.md) entry (See [actions](config-actions.md)) ```yaml :