diff --git a/docs/config.md b/docs/config.md index e2015da..1d343ea 100644 --- a/docs/config.md +++ b/docs/config.md @@ -33,7 +33,7 @@ The **config** entry (mandatory) contains settings for the deployment * `create`: create directory hierarchy when installing dotfiles if it doesn't exist (default *true*) * `default_actions`: list of action's keys to execute for all installed dotfile - (see [Use actions](#actions)) + (see [actions](#entry-actions)) * `diff_command`: the diff command to use for diffing files (default `diff -r -u {0} {1}`) * `dotpath`: path to the directory containing the dotfiles to be managed (default `dotfiles`) by dotdrop (absolute path or relative to the config file location) @@ -44,22 +44,22 @@ The **config** entry (mandatory) contains settings for the deployment * `ignoreempty`: do not deploy template if empty (default *false*) * `import_actions`: list of paths to load actions from (absolute path or relative to the config file location, - see [Import actions from file](#import-actions-from-file)) + see [Import actions from file](#entry-import_actions)) * `import_configs`: list of config file paths to be imported in the current config (absolute path or relative to the current config file location, - see [Import config files](#import-config-files)) + see [Import config files](#entry-import_configs)) * `import_variables`: list of paths to load variables from (absolute path or relative to the config file location, - see [Import variables from file](#import-variables-from-file)) + see [Import variables from file](#entry-import_variables)) * `instignore`: list of patterns to ignore when installing, apply to all dotfiles (enclose in quotes when using wildcards, see [ignore patterns](#ignore-patterns)) * `keepdot`: preserve leading dot when importing hidden file in the `dotpath` (default *false*) * `link_dotfile_default`: set dotfile's `link` attribute to this value when undefined. Possible values: *nolink*, *link*, *link_children* (default: *nolink*, - see [Symlinking dotfiles](#symlinking-dotfiles)) + see [Symlinking dotfiles](#symlink-dotfiles)) * `link_on_import`: set dotfile's `link` attribute to this value when importing. Possible values: *nolink*, *link*, *link_children* (default: *nolink*, - see [Symlinking dotfiles](#symlinking-dotfiles)) + see [Symlinking dotfiles](#symlink-dotfiles)) * `longkey`: use long keys for dotfiles when importing (default *false*, see [Import dotfiles](usage.md#import-dotfiles)) * `minversion`: (*for internal use, do not modify*) provides the minimal dotdrop version to use @@ -83,18 +83,18 @@ The **dotfiles** entry (mandatory) contains a list of dotfiles managed by dotdro can use `variables` and `dynvariables`, make sure to quote) * `link`: define how this dotfile is installed. Possible values: *nolink*, *link*, *link_children* (default: `link_dotfile_default`, - see [Symlinking dotfiles](#symlinking-dotfiles)) + see [Symlinking dotfiles](#symlink-dotfiles)) * `actions`: list of action keys that need to be defined in the **actions** entry below - (see [Use actions](#actions)) + (see [actions](#entry-actions)) * `cmpignore`: list of patterns to ignore when comparing (enclose in quotes when using wildcards, see [ignore patterns](#ignore-patterns)) * `ignoreempty`: if true empty template will not be deployed (defaults to the value of `ignoreempty` above) * `instignore`: list of patterns to ignore when installing (enclose in quotes when using wildcards, see [ignore patterns](#ignore-patterns)) * `trans_read`: transformation key to apply when installing this dotfile - (must be defined in the **trans_read** entry below, see [Use transformations](#transformations)) + (must be defined in the **trans_read** entry below, see [transformations](#entry-transformations)) * `trans_write`: transformation key to apply when updating this dotfile - (must be defined in the **trans_write** entry below, see [Use transformations](#transformations)) + (must be defined in the **trans_write** entry below, see [transformations](#entry-transformations)) * `upignore`: list of patterns to ignore when updating (enclose in quotes when using wildcards, see [ignore patterns](#ignore-patterns)) * *DEPRECATED* `link_children`: replaced by `link: link_children` @@ -127,15 +127,15 @@ The **profiles** entry (mandatory) contains a list of profiles with the differen * `dotfiles`: the dotfiles associated to this profile * `import`: list of paths containing dotfiles keys for this profile (absolute path or relative to the config file location, - see [Import profile dotfiles from file](#import-profile-dotfiles-from-file)). + see [Import profile dotfiles from file](#entry-profile-import)). * `include`: include all elements (dotfiles, actions, (dyn)variables, etc) from another profile - (see [Include dotfiles from another profile](#include-dotfiles-from-another-profile)) + (see [Include dotfiles from another profile](#entry-profile-include)) * `variables`: profile specific variables (see [Variables](#variables)) * `dynvariables`: profile specific interpreted variables - (see [Interpreted variables](#interpreted-variables)) + (see [Interpreted variables](#entry-dynvariables)) * `actions`: list of action keys that need to be defined in the **actions** entry below - (see [Use actions](#actions)) + (see [actions](#entry-actions)) ```yaml : @@ -161,7 +161,7 @@ The **profiles** entry (mandatory) contains a list of profiles with the differen ### actions entry -The **actions** entry (optional) contains a list of actions (see [actions](#actions)) +The **actions** entry (optional) contains a list of actions (see [actions](#entry-actions)) ```yaml actions: @@ -170,7 +170,7 @@ actions: ### trans_read entry -The **trans_read** entry (optional) contains a list of transformations (see [transformations](#transformations)) +The **trans_read** entry (optional) contains a list of transformations (see [transformations](#entry-transformations)) ```yaml trans_read: @@ -179,7 +179,7 @@ trans_read: ### trans_write entry -The **trans_write** entry (optional) contains a list of write transformations (see [transformations](#transformations)) +The **trans_write** entry (optional) contains a list of write transformations (see [transformations](#entry-transformations)) ```yaml trans_write: @@ -198,14 +198,52 @@ variables: ### dynvariables entry The **dynvariables** entry (optional) contains a list of interpreted variables -(see [Interpreted variables](#interpreted-variables)) +(see [Interpreted variables](#entry-dynvariables)) ```yaml dynvariables: : ``` -## Actions +## Variables + +Multiple variables can be used within the config file to +parametrize following elements of the config: + +* dotfiles `src` and `dst` paths (see [Dynamic dotfile paths](#dynamic-dotfile-paths)) +* external path specifications + * `import_variables` + * `import_actions` + * `import_configs` + * profiles's `import` + +`actions` and `transformations` also support the use of variables +but those are resolved when the action/transformation is executed +(see [Dynamic actions](#dynamic-actions), +[Dynamic transformations](#dynamic-transformations) and [Templating](templating.md)). + +Following variables are available in the config files: + +* [variables defined in the config](#entry-variables) +* [interpreted variables defined in the config](#entry-dynvariables) +* [profile variables defined in the config](#profile-variables) +* environment variables: `{{@@ env['MY_VAR'] @@}}` +* dotdrop header: `{{@@ header() @@}}` (see [Dotdrop header](templating.md#dotdrop-header)) + +As well as all template methods (see [Available methods](templating.md#available-methods)) + +## Symlink dotfiles + +Dotdrop is able to install dotfiles in three different ways +which are controlled by the `link` config attribute of each dotfile: + +* `link: nolink`: the dotfile (file or directory) is copied to its destination +* `link: link`: the dotfile (file or directory) is symlinked to its destination +* `link: link_children`: the files/directories found under the dotfile (directory) are symlinked to their destination + +For more see [this how-to](howto/symlink-dotfiles.md) + +## Entry actions **Note**: any action with a key starting with an underscore (`_`) won't be shown in output. This can be useful when working with sensitive data containing passwords for example. @@ -368,7 +406,7 @@ dotfiles: - always_action ``` -## Transformations +## Entry transformations For examples of transformation uses, see @@ -394,7 +432,7 @@ There are two types of transformations available: * **{1}** will be replaced with a temporary file to store the result of the transformation A typical use-case for transformations is when dotfiles need to be -stored encrypted or compressed. For more see below [the howto](howto/README.md). +stored encrypted or compressed. For more see [the howto](howto/README.md). Note that transformations cannot be used if the dotfiles is to be linked (when `link: link` or `link: link_children`). @@ -417,34 +455,7 @@ profiles: will result in `abc; f_abc; p1; lastarg` -## Variables - -Multiple variables can be used within the config file to -parametrize following elements of the config: - -* dotfiles `src` and `dst` paths (see [Dynamic dotfile paths](#dynamic-dotfile-paths)) -* external path specifications - * `import_variables` - * `import_actions` - * `import_configs` - * profiles's `import` - -`actions` and `transformations` also support the use of variables -but those are resolved when the action/transformation is executed -(see [Dynamic actions](#dynamic-actions), -[Dynamic transformations](#dynamic-transformations) and [Templating](templating.md)). - -Following variables are available in the config files: - -* [variables defined in the config](#variables) -* [interpreted variables defined in the config](#interpreted-variables) -* [profile variables defined in the config](#profile-variables) -* environment variables: `{{@@ env['MY_VAR'] @@}}` -* dotdrop header: `{{@@ header() @@}}` (see [Dotdrop header](templating.md#dotdrop-header)) - -As well as all template methods (see [Available methods](templating.md#available-methods)) - -### config variables +## Entry variables Variables defined in the `variables` entry are made available within the config file. @@ -464,6 +475,7 @@ dynvariables: ``` will result in the following available variables: + * var1: `var1` * var2: `var1 var2` * var3: `var1 var2 var3` @@ -495,7 +507,7 @@ profiles: - f_gitconfig ``` -### Interpreted variables +## Entry dynvariables It is also possible to have *dynamic* variables in the sense that their content will be interpreted by the shell before being substituted. @@ -517,41 +529,7 @@ variables: They have the same properties as [Variables](#variables). -## Symlinking dotfiles - -Dotdrop is able to install dotfiles in three different ways -which are controlled by the `link` attribute of each dotfile: - -* `link: nolink`: the dotfile (file or directory) is copied to its destination -* `link: link`: the dotfile (file or directory) is symlinked to its destination -* `link: link_children`: the files/directories found under the dotfile (directory) are symlinked to their destination - -For more see [this how-to](howto/symlinked-dotfiles.md) - -## All dotfiles for a profile - -To use all defined dotfiles for a profile, simply use -the keyword `ALL`. - -For example: -```yaml -dotfiles: - f_xinitrc: - dst: ~/.xinitrc - src: xinitrc - f_vimrc: - dst: ~/.vimrc - src: vimrc -profiles: - host1: - dotfiles: - - ALL - host2: - dotfiles: - - f_vimrc -``` - -## Include dotfiles from another profile +## Entry profile include If one profile is using the entire set of another profile, one can use the `include` entry to avoid redundancy. @@ -574,7 +552,7 @@ profiles: Here profile *host1* contains all the dotfiles defined for *host2* plus `f_xinitrc`. For more advanced use-cases variables -([variables](#variables) and [dynvariables](#interpreted-variables)) +([variables](#variables) and [dynvariables](#entry-dynvariables)) can be used to specify the profile to include in a profile For example: @@ -598,7 +576,7 @@ profiles: - "profile_{{@@ var1 @@}}" ``` -## Import profile dotfiles from file +## Entry profile import Profile's dotfiles list can be loaded from external files by specifying their paths in the config entry `import` under the specific profile. @@ -638,7 +616,7 @@ import: - profiles.d/{{@@ profile @@}}.yaml ``` -## Import variables from file +## Entry import_variables It is possible to load variables/dynvariables from external files by providing their paths in the config entry `import_variables`. @@ -670,7 +648,7 @@ import_variables: - variables.d/myvars.yaml:optional ``` -## Import actions from file +## Entry import_actions It is possible to load actions from external files by providing their paths in the config entry `import_actions`. @@ -709,10 +687,10 @@ import_actions: - actions.d/myactions.yaml:optional ``` -## Import config files +## Entry import_configs -Entire config files can be imported. This means making the following available -from the imported config file in the original config file: +Entire config files can be imported using the `import_configs` entry. +This means making the following available from the imported config file in the original config file: * dotfiles * profiles @@ -872,6 +850,30 @@ dotfiles: trans_write: w_echo_var ``` +## All dotfiles for a profile + +To use all defined dotfiles for a profile, simply use +the keyword `ALL`. + +For example: +```yaml +dotfiles: + f_xinitrc: + dst: ~/.xinitrc + src: xinitrc + f_vimrc: + dst: ~/.vimrc + src: vimrc +profiles: + host1: + dotfiles: + - ALL + host2: + dotfiles: + - f_vimrc +``` + + ## Ignore patterns It is possible to ignore specific patterns when using dotdrop. For example for `compare` when temporary @@ -910,8 +912,6 @@ dotfiles: ... ``` -examples - To completely ignore comparison of a specific dotfile: ```yaml dotfiles: diff --git a/docs/howto/README.md b/docs/howto/README.md index 887613d..9971fd1 100644 --- a/docs/howto/README.md +++ b/docs/howto/README.md @@ -34,4 +34,4 @@ ## Symlink dotfiles -[Symlink dotfiles](symlinked-dotfiles.md) +[Symlink dotfiles](symlink-dotfiles.md) diff --git a/docs/howto/append.md b/docs/howto/append.md index 6b07fb3..fcd41f6 100644 --- a/docs/howto/append.md +++ b/docs/howto/append.md @@ -1,7 +1,6 @@ Sometimes it might be useful to be able to append some text to a file. Dotdrop is able to do that with the help of -[actions](../config.md#actions). -and a temporary file. +[actions](../config.md#entry-actions) and a temporary file. Below is a config example to append to a file: ```yaml diff --git a/docs/howto/create-special-files.md b/docs/howto/create-special-files.md index 903ca68..3557548 100644 --- a/docs/howto/create-special-files.md +++ b/docs/howto/create-special-files.md @@ -1,5 +1,5 @@ One way for creating symlinks (or any other special files) is to use a combination of -[actions](../config.md#actions) and a *fake* dotfile. +[actions](../config.md#entry-actions) and a *fake* dotfile. Let's say for example you have a list of directories you want to link from under `~/.original` to `~/symlinks`. @@ -19,6 +19,7 @@ dir3 ``` The config file would contain different elements + * a `dynvariables` that will read the above text file * a few `variables` for the source and destination * an action that will create the destination directory and symlink those directories diff --git a/docs/howto/merge-files-when-installing.md b/docs/howto/merge-files-when-installing.md index 4968cd8..a2a8d40 100644 --- a/docs/howto/merge-files-when-installing.md +++ b/docs/howto/merge-files-when-installing.md @@ -46,12 +46,12 @@ Dotdrop will then automagically include the files into your vimrc when handling # Merge all files in a directory To include all files in a directory, a combination of -[dynvariables](../config.md#interpreted-variables) +[dynvariables](../config.md#entry-dynvariables) and [jinja2 directives](http://jinja.pocoo.org/docs/2.10/) have to be used. Let's say all files in `/toinclude` need to be included into a dotfile. -First define a [dynvariables](../config.md#interpreted-variables) +First define a [dynvariables](../config.md#entry-dynvariables) in the config file which will look for files to include in the above directory: ```yaml dynvariables: diff --git a/docs/howto/sensitive-dotfiles.md b/docs/howto/sensitive-dotfiles.md index 608869a..be68da0 100644 --- a/docs/howto/sensitive-dotfiles.md +++ b/docs/howto/sensitive-dotfiles.md @@ -1,16 +1,11 @@ # Sensitive dotfiles -* [Available solutions](#available-solutions) -* [Store encrypted dotfiles](#store-encrypted-dotfiles) -* [Load passphrase from file](#load-passphrase-from-file) - ---- - -# Available solutions - Two solutions exist, the first one using an unversioned file (see [Environment variables](../templating.md#environment-variables)) and the second using transformations (see [Store encrypted dotfiles](#store-encrypted-dotfiles)). +* [Store encrypted dotfiles](#store-encrypted-dotfiles) +* [Load passphrase from file](#load-passphrase-from-file) + # Store encrypted dotfiles Here's an example of part of a config file to use gpg encrypted dotfiles: diff --git a/docs/howto/special-chars.md b/docs/howto/special-chars.md index 19c9cd8..af042d2 100644 --- a/docs/howto/special-chars.md +++ b/docs/howto/special-chars.md @@ -31,15 +31,15 @@ This is due to Jinja2 stripping CRLF. One solution is to use `dos2unix` to re-format the dotfiles before adding them to dotdrop. -See https://github.com/deadc0de6/dotdrop/issues/42. +See . ## Non-unicode chars -Jinja2 is not able to process non-unicode chars (http://jinja.pocoo.org/docs/2.10/api/). This means that dotfiles using non-unicode chars can still be fully managed by dotdrop however when comparing the local file with the one stored in dotdrop, `compare` will return a difference even if there is none. +Jinja2 is not able to process non-unicode chars (). This means that dotfiles using non-unicode chars can still be fully managed by dotdrop however when comparing the local file with the one stored in dotdrop, `compare` will return a difference even if there is none. Either replace the non-unicode chars (see below [Re-encode](#re-encode)) or accept the fact the comparison shows a difference while there's none. -See https://github.com/deadc0de6/dotdrop/issues/42. +See . # Re-encode diff --git a/docs/howto/symlinked-dotfiles.md b/docs/howto/symlink-dotfiles.md similarity index 96% rename from docs/howto/symlinked-dotfiles.md rename to docs/howto/symlink-dotfiles.md index ba2d016..125de34 100644 --- a/docs/howto/symlinked-dotfiles.md +++ b/docs/howto/symlink-dotfiles.md @@ -13,11 +13,6 @@ Note that if the dotfile is using template directives, it will be symlinked into `~/.config/dotdrop` instead of directly into your *dotpath* (see [Templating symlinked dotfiles](#templating-symlinked-dotfiles)) -* [Link children](#link-children) -* [Templating symlinked dotfiles](#templating-symlinked-dotfiles) - ---- - # Link children This feature can be very useful for dotfiles when you don't want the entire diff --git a/docs/installation.md b/docs/installation.md index 4095ad9..7ca7790 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -96,8 +96,8 @@ Then follow the instructions under [With pypi](#with-pypi). ## Aur packages Dotdrop is available on aur: -* stable: https://aur.archlinux.org/packages/dotdrop/ -* git version: https://aur.archlinux.org/packages/dotdrop-git/ +* stable: +* git version: Then follow the [doc to setup your repository](#setup-your-repository). diff --git a/docs/misc/migrate-from-submodule.md b/docs/misc/migrate-from-submodule.md index 382b246..b81b298 100644 --- a/docs/misc/migrate-from-submodule.md +++ b/docs/misc/migrate-from-submodule.md @@ -1,4 +1,3 @@ - **WARNING** Only do the following if you are using dotdrop version `< 0.7.1` or if you encounter an issue when running dotdrop that redirects you here. @@ -67,4 +66,4 @@ $ git commit -m 'remove dotdrop.sh script' * push upstream ```bash $ git push -``` \ No newline at end of file +``` diff --git a/docs/templating.md b/docs/templating.md index 1f96ba0..3aabe34 100644 --- a/docs/templating.md +++ b/docs/templating.md @@ -30,7 +30,7 @@ Following variables are available in templates: * `{{@@ _dotdrop_workdir @@}}` contains the [workdir](config.md) absolute path. * dotfile specific variables (see [Dotfile variables](#dotfile-variables)) * config variables (see [Variables](config.md#variables)). -* config interpreted variables (see [Interpreted variables](config.md#interpreted-variables)). +* config interpreted variables (see [Interpreted variables](config.md#entry-dynvariables)). ## Dotfile variables diff --git a/mkdocs.yml b/mkdocs.yml index 49a652c..55c30a8 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -6,6 +6,7 @@ theme: highlightjs: true hljs_languages: - yaml + collapse_navigation: false use_directory_urls: true nav: - Home: 'README.md'