From 3b7d290f4ad2520d1d46a42bb407eb64baadbc47 Mon Sep 17 00:00:00 2001 From: deadc0de6 Date: Fri, 24 Sep 2021 20:54:20 +0200 Subject: [PATCH] update doc --- docs/config-details.md | 31 +++++++++++++++++++++++++ docs/config-format.md | 15 ++++++++++-- docs/config.md | 3 +++ docs/howto/howto.md | 4 ++++ docs/howto/prompt-user-for-variables.md | 26 +++++++++++++++++++++ 5 files changed, 77 insertions(+), 2 deletions(-) create mode 100644 docs/howto/prompt-user-for-variables.md diff --git a/docs/config-details.md b/docs/config-details.md index efe2cea..82a4f7f 100644 --- a/docs/config-details.md +++ b/docs/config-details.md @@ -287,6 +287,37 @@ variables: They have the same properties as [Variables](config.md#variables). +## Entry uservariables + +If you want to manually enter variables values, you can use the +`uservariables` entry. Each variable will be prompted to the user. + +For example +```yaml +uservariables: + emailvar: "email" +``` + +will prompt the user to enter a value for the variable `emailvar`: +``` +Please provide the value for "email": +``` + +And store the entered text as the value for the variable `email`. +The variable can then be used as any other [variables](config.md#variables). + +`uservariables` are eventually saved to `uservariables.yaml` (relatively to the +config file). +This allow to use the following construct to prompt once for some specific variables and +then store them in a file. You might also want to add `uservariables.yaml` to your `.gitignore`. +```yaml +uservariables: + emailvar: "email" +config: + import_variables: + - uservariables.yaml:optional +``` + ## Entry profile variables Profile variables will take precedence over globally defined variables. diff --git a/docs/config-format.md b/docs/config-format.md index d30bd92..17c7aa9 100644 --- a/docs/config-format.md +++ b/docs/config-format.md @@ -45,8 +45,8 @@ The **dotfiles** entry (mandatory) contains a list of dotfiles managed by dotdro Entry | Description -------- | ------------- -`dst` | where this dotfile needs to be deployed (dotfile with empty `dst` are ignored and considered installed, can use `variables` and `dynvariables`, make sure to quote) -`src` | dotfile path within the `dotpath` (dotfile with empty `src` are ignored and considered installed, can use `variables` and `dynvariables`, make sure to quote) +`dst` | where this dotfile needs to be deployed (dotfile with empty `dst` are ignored and considered installed, can use `variables`, make sure to quote) +`src` | dotfile path within the `dotpath` (dotfile with empty `src` are ignored and considered installed, can use `variables`, make sure to quote) `link` | define how this dotfile is installed. Possible values: *nolink*, *link*, *link_children* (see [Symlinking dotfiles](config.md#symlink-dotfiles)) (defaults to value of `link_dotfile_default`) `actions` | list of action keys that need to be defined in the **actions** entry below (see [actions](config-details.md#entry-actions)) `chmod` | defines the file permissions in octal notation to apply during installation (see [permissions](config.md#permissions)) @@ -177,3 +177,14 @@ The **dynvariables** entry (optional) contains a list of interpreted variables dynvariables: : ``` + +## uservariables entry + +The **uservariables** entry (optional) contains a list of variables +to be queried to the user for their values. +(see [User variables](config-details.md#entry-uservariables)) + +```yaml +uservariables: + : +``` diff --git a/docs/config.md b/docs/config.md index d1a1758..7990b33 100644 --- a/docs/config.md +++ b/docs/config.md @@ -39,6 +39,7 @@ Following variables are available in the config files: * [variables defined in the config](config-details.md#entry-variables) * [interpreted variables defined in the config](config-details.md#entry-dynvariables) +* [user variables defined in the config](config-details.md#entry-uservariables) * [profile variables defined in the config](config-details.md#entry-profile-variables) * environment variables: `{{@@ env['MY_VAR'] @@}}` * dotdrop header: `{{@@ header() @@}}` (see [Dotdrop header](templating.md#dotdrop-header)) @@ -60,6 +61,8 @@ Here are some rules on the use of variables in configs: * profile `(dyn)variables` take precedence over profile's included `(dyn)variables` * external/imported `(dyn)variables` take precedence over `(dyn)variables` defined inside the main config file +* [user variables](config-details.md#entry-uservariables) are ignored if + any other variable with the same key is defined ## Permissions diff --git a/docs/howto/howto.md b/docs/howto/howto.md index 5218664..bf066a2 100644 --- a/docs/howto/howto.md +++ b/docs/howto/howto.md @@ -43,3 +43,7 @@ ## Symlink dotfiles [Symlink dotfiles](symlink-dotfiles.md) + +## Prompt user for variables + +[Prompt user for variables](prompt-user-for-variables.md) diff --git a/docs/howto/prompt-user-for-variables.md b/docs/howto/prompt-user-for-variables.md new file mode 100644 index 0000000..fbc3db9 --- /dev/null +++ b/docs/howto/prompt-user-for-variables.md @@ -0,0 +1,26 @@ +# Prompt user for variables + +With the use of [uservariables](config-details.md#entry-uservariables), +one can define specific variables that need to be initially filled in manually +by the user on first run. + +The provided values are then automatically saved by dotdrop to `uservariables.yaml`, +which can be included in the main config as a file from which variables are imported +using [import_variables](config-details.md#entry-import_variables). + +Let's say for example that you want to provide manually the email value +on new hosts you deploy your dotfiles to. + +You'd add the following elements to your config: +```yaml +uservariables: + emailvar: "email" +config: + import_variables: + - uservariables.yaml:optional +``` + +On first run, the `emailvar` is prompted to the user and then saved +to `uservariables.yaml`. Since this file is imported, the value for +`emailvar` will automatically be filled in without prompting the +user on subsequent calls.