update doc

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.

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:
   <variable-name>: <shell-oneliner>
 ```
+
+## 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:
+  <variable-name>: <prompt>
+```

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
 

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)

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.