diff --git a/completion/README.md b/completion/README.md index 5ba805e..788c73e 100644 --- a/completion/README.md +++ b/completion/README.md @@ -1,5 +1,5 @@ -Here are the completion files for `bash`, `zsh` and `fish`. -for the use of dotdrop either through the bash script `dotdrop.sh` +Here are completion files for `bash`, `zsh` and `fish` +for the use of dotdrop through the bash script `dotdrop.sh` or through the python script `dotdrop` (pypi, snap, setup.py, etc). `bash` and `zsh` scripts are generated using diff --git a/docs/README.md b/docs/README.md index 690883d..ac198e3 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,18 +1,21 @@ # Dotdrop documentation [Dotdrop](https://deadc0de.re/dotdrop/) is a dotfiles manager that provides efficient ways of managing your dotfiles. -It is especially powerful when it comes to managing those across different hosts.. +It is especially powerful when it comes to managing those across different hosts. -The idea of dotdrop is to have the ability to store each dotfile only once and deploy them with a different content on different hosts/setups. +The idea of dotdrop is to have the ability to store each dotfile only once and deploy them with a different +content on different hosts/setups. To achieve this, it uses [jinja2](http://jinja.pocoo.org/) which is a templating engine that allows to specify during the dotfile installation how (with what content) each dotfile will be installed based on a selected profile. -Most information on using dotdrop are described in this wiki and in the [readme](https://github.com/deadc0de6/dotdrop/blob/master/README.md). +Most information on using dotdrop are described in this documentation +and in the [readme](https://github.com/deadc0de6/dotdrop/blob/master/README.md). + For more check * [a quick overview of dotdrop features](https://deadc0de.re/dotdrop/) * [the blogpost on dotdrop](https://deadc0de.re/articles/dotfiles.html) * [an example](https://github.com/deadc0de6/dotdrop#getting-started) -* [how people are using dotdrop](meta/people-using-dotdrop.md) +* [how people are using dotdrop](misc/people-using-dotdrop.md) For more examples of config file, [search github](https://github.com/search?q=filename%3Aconfig.yaml+dotdrop&type=Code). diff --git a/docs/config.md b/docs/config.md new file mode 100644 index 0000000..e2015da --- /dev/null +++ b/docs/config.md @@ -0,0 +1,934 @@ +# Config + +The config file used by dotdrop is +[config.yaml](https://github.com/deadc0de6/dotdrop/blob/master/config.yaml). + +## Location + +Unless specified dotdrop will look in following places for the config file (`config.yaml`) +and use the first one found + +* current/working directory or the directory where [dotdrop.sh](https://github.com/deadc0de6/dotdrop/blob/master/dotdrop.sh) is located if used +* `${XDG_CONFIG_HOME}/dotdrop/` +* `~/.config/dotdrop/` +* `/etc/xdg/dotdrop/` +* `/etc/dotdrop/` + +You can force dotdrop to use a different file either by using the `-c --cfg` cli switch +or by defining the `DOTDROP_CONFIG` environment variable. + +## Format + +Dotdrop config file uses [yaml](https://yaml.org/) syntax. + +### config entry + +The **config** entry (mandatory) contains settings for the deployment + +* `backup`: create a backup of the dotfile in case it differs from the + one that will be installed by dotdrop (default *true*) +* `banner`: display the banner (default *true*) +* `cmpignore`: list of patterns to ignore when comparing, apply to all dotfiles + (enclose in quotes when using wildcards, see [ignore patterns](#ignore-patterns)) +* `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)) +* `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) +* `filter_file`: list of paths to load templating filters from + (see [Templating available filters](templating.md#available-filters)) +* `func_file`: list of paths to load templating functions from + (see [Templating available methods](templating.md#available-methods)) +* `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)) +* `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)) +* `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)) +* `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)) +* `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)) +* `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 +* `showdiff`: on install show a diff before asking to overwrite (see `--showdiff`) (default *false*) +* `upignore`: list of patterns to ignore when updating, apply to all dotfiles + (enclose in quotes when using wildcards, see [ignore patterns](#ignore-patterns)) +* `workdir`: path to the directory where templates are installed before being symlinked + when using `link:link` or `link:link_children` + (absolute path or relative to the config file location, defaults to *~/.config/dotdrop*) +* *DEPRECATED* `link_by_default`: when importing a dotfile set `link` to that value per default (default *false*) + +### dotfiles entry + +The **dotfiles** entry (mandatory) contains a list of dotfiles managed by dotdrop + +* `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) +* `link`: define how this dotfile is installed. + Possible values: *nolink*, *link*, *link_children* (default: `link_dotfile_default`, + see [Symlinking dotfiles](#symlinking-dotfiles)) +* `actions`: list of action keys that need to be defined in the **actions** entry below + (see [Use actions](#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)) +* `trans_write`: transformation key to apply when updating this dotfile + (must be defined in the **trans_write** entry below, see [Use transformations](#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` +* *DEPRECATED* `trans`: replaced by `trans_read` + +```yaml +: + dst: + src: + ## Optional + link: (nolink|link|link_children) + ignoreempty: (true|false) + cmpignore: + - "" + upignore: + - "" + instignore: + - "" + actions: + - + trans_read: + trans_write: +``` + +### profiles entry + +The **profiles** entry (mandatory) contains a list of profiles with the different dotfiles that + need to be managed + +* `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)). +* `include`: include all elements (dotfiles, actions, (dyn)variables, etc) from another profile + (see [Include dotfiles from another profile](#include-dotfiles-from-another-profile)) +* `variables`: profile specific variables + (see [Variables](#variables)) +* `dynvariables`: profile specific interpreted variables + (see [Interpreted variables](#interpreted-variables)) +* `actions`: list of action keys that need to be defined in the **actions** entry below + (see [Use actions](#actions)) + +```yaml +: + dotfiles: + - + - + - ... + ## Optional + include: + - + - ... + variables: + : + dynvariables: + : + actions: + - + - ... + import: + - + - ... +``` + +### actions entry + +The **actions** entry (optional) contains a list of actions (see [actions](#actions)) + +```yaml +actions: + : +``` + +### trans_read entry + +The **trans_read** entry (optional) contains a list of transformations (see [transformations](#transformations)) + +```yaml +trans_read: + : +``` + +### trans_write entry + +The **trans_write** entry (optional) contains a list of write transformations (see [transformations](#transformations)) + +```yaml +trans_write: + : +``` + +### variables entry + +The **variables** entry (optional) contains a list of variables (see [variables](#variables)) + +```yaml +variables: + : +``` + +### dynvariables entry + +The **dynvariables** entry (optional) contains a list of interpreted variables +(see [Interpreted variables](#interpreted-variables)) + +```yaml +dynvariables: + : +``` + +## 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. + +### Dotfile actions + +It is sometimes useful to execute some kind of action +when deploying a dotfile. + +Note that dotfile actions are only +executed when the dotfile is installed. + +For example let's consider +[Vundle](https://github.com/VundleVim/Vundle.vim) is used +to manage vim's plugins, the following action could +be set to update and install the plugins when `vimrc` is +deployed: + +```yaml +actions: + vundle: vim +VundleClean! +VundleInstall +VundleInstall! +qall +config: + backup: true + create: true + dotpath: dotfiles +dotfiles: + f_vimrc: + dst: ~/.vimrc + src: vimrc + actions: + - vundle +profiles: + home: + dotfiles: + - f_vimrc +``` + +Thus when `f_vimrc` is installed, the command +`vim +VundleClean! +VundleInstall +VundleInstall! +qall` will +be executed. + +Sometimes, you may even want to execute some action prior to deploying a dotfile. +Let's take another example with +[vim-plug](https://github.com/junegunn/vim-plug): + +```yaml +actions: + pre: + vim-plug-install: test -e ~/.vim/autoload/plug.vim || (mkdir -p ~/.vim/autoload; curl + -fLo ~/.vim/autoload/plug.vim https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim) + vim-plug: vim +PlugInstall +qall +config: + backup: true + create: true + dotpath: dotfiles +dotfiles: + f_vimrc: + dst: ~/.vimrc + src: vimrc + actions: + - vim-plug-install + - vim-plug +profiles: + home: + dotfiles: + - f_vimrc +``` + +This way, we make sure [vim-plug](https://github.com/junegunn/vim-plug) +is installed prior to deploying the `~/.vimrc` dotfile. + +You can also define `post` actions like this: + +```yaml +actions: + post: + some-action: echo "Hello, World!" >/tmp/log +``` + +If you don't specify neither `post` nor `pre`, the action will be executed +after the dotfile deployment (which is equivalent to `post`). +Actions cannot obviously be named `pre` or `post`. + +Actions can even be parameterized. For example: +```yaml +actions: + echoaction: echo '{0}' > {1} +config: + backup: true + create: true + dotpath: dotfiles +dotfiles: + f_vimrc: + dst: ~/.vimrc + src: vimrc + actions: + - echoaction "vim installed" /tmp/mydotdrop.log + f_xinitrc: + dst: ~/.xinitrc + src: xinitrc + actions: + - echoaction "xinitrc installed" /tmp/myotherlog.log +profiles: + home: + dotfiles: + - f_vimrc + - f_xinitrc +``` + +The above will execute `echo 'vim installed' > /tmp/mydotdrop.log` when +vimrc is installed and `echo 'xinitrc installed' > /tmp/myotherlog.log'` +when xinitrc is installed. + +### Default actions + +Dotdrop allows to execute an action for any dotfile installation. These actions work as any other action (*pre* or *post*). + +For example, the below action will log each dotfile installation to a file. + +```yaml +actions: + post: + loginstall: "echo {{@@ _dotfile_abs_src @@}} installed to {{@@ _dotfile_abs_dst @@}} >> {0}" +config: + backup: true + create: true + dotpath: dotfiles + default_actions: + - loginstall "/tmp/dotdrop-installation.log" +dotfiles: + f_vimrc: + dst: ~/.vimrc + src: vimrc +profiles: + hostname: + dotfiles: + - f_vimrc +``` + +### Profile actions + +Profile can be either `pre` or `post` actions. Those are executed before +any dotfile installation (for `pre`) and after all dotfiles installation (for `post`) +only if at least one dotfile has been installed. + +### Fake dotfile and actions + +*Fake* dotfile can be created by specifying no `dst` and no `src` (see [config format](#format)). +By binding an action to such a *fake* dotfile, you make sure the action is always executed since +*fake* dotfile are always considered installed. + +```yaml +actions: + always_action: 'date > ~/.dotdrop.log' +dotfiles: + fake: + src: + dst: + actions: + - always_action +``` + +## Transformations + +For examples of transformation uses, see + +* [Store compressed directories](howto/store-compressed-directories.md) +* [Sensitive dotfiles](howto/sensitive-dotfiles.md) + +**Note**: any transformation 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. + +There are two types of transformations available: + +* **read transformations**: used to transform dotfiles before they are installed ([format](#format) key `trans_read`) + * Used for commands `install` and `compare` + * They have two arguments: + * **{0}** will be replaced with the dotfile to process + * **{1}** will be replaced with a temporary file to store the result of the transformation + * Happens **before** the dotfile is templated with jinja2 (see [templating](templating.md)) + +* **write transformations**: used to transform files before updating a dotfile ([format](#format) key `trans_write`) + * Used for command `update` + * They have two arguments: + * **{0}** will be replaced with the file path to update the dotfile with + * **{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). + +Note that transformations cannot be used if the dotfiles is to be linked (when `link: link` or `link: link_children`). + +Transformations also support additional positional arguments that must start from 2 (since `{0}` and `{1}` are added automatically). The transformations itself as well as its arguments can also be templated. + +For example +```yaml +trans_read: + targ: echo "$(basename {0}); {{@@ _dotfile_key @@}}; {2}; {3}" > {1} +dotfiles: + f_abc: + dst: /tmp/abc + src: abc + trans_read: targ "{{@@ profile @@}}" lastarg +profiles: + p1: + dotfiles: + - f_abc +``` + +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 + +Variables defined in the `variables` entry are made available within the config file. + +Config variables are recursively evaluated what means that +a config like the below +```yaml +variables: + var1: "var1" + var2: "{{@@ var1 @@}} var2" + var3: "{{@@ var2 @@}} var3" + var4: "{{@@ dvar4 @@}}" +dynvariables: + dvar1: "echo dvar1" + dvar2: "{{@@ dvar1 @@}} dvar2" + dvar3: "{{@@ dvar2 @@}} dvar3" + dvar4: "echo {{@@ var3 @@}}" +``` + +will result in the following available variables: +* var1: `var1` +* var2: `var1 var2` +* var3: `var1 var2 var3` +* var4: `echo var1 var2 var3` +* dvar1: `dvar1` +* dvar2: `dvar1 dvar2` +* dvar3: `dvar1 dvar2 dvar3` +* dvar4: `var1 var2 var3` + +### Profile variables + +Profile variables will take precedence over globally defined variables. +This means that you could do something like this: +```yaml +variables: + git_email: home@email.com +dotfiles: + f_gitconfig: + dst: ~/.gitconfig + src: gitconfig +profiles: + work: + dotfiles: + - f_gitconfig + variables: + git_email: work@email.com + private: + dotfiles: + - f_gitconfig +``` + +### Interpreted variables + +It is also possible to have *dynamic* variables in the sense that their +content will be interpreted by the shell before being substituted. + +These need to be defined in the config file under the entry `dynvariables`. + +For example: +```yaml +dynvariables: + dvar1: head -1 /proc/meminfo + dvar2: "echo 'this is some test' | rev | tr ' ' ','" + dvar3: /tmp/my_shell_script.sh + user: "echo $USER" + config_file: test -f "{{@@ user_config @@}}" && echo "{{@@ user_config @@}}" || echo "{{@@ dfl_config @@}}" +variables: + user_config: "profile_{{@@ user @@}}_uid.yaml" + dfl_config: "profile_default.yaml" +``` + +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 + +If one profile is using the entire set of another profile, one can use +the `include` entry to avoid redundancy. + +Note that everything from the included profile is made available +(actions, variables/dynvariables, etc). + +For example: +```yaml +profiles: + host1: + dotfiles: + - f_xinitrc + include: + - host2 + host2: + dotfiles: + - f_vimrc +``` +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)) +can be used to specify the profile to include in a profile + +For example: +```yaml +variables: + var1: "john" +dynvariables: + d_user: "echo $USER" +profiles: + profile_john: + dotfiles: + - f_john_dotfile + profile_bill: + dotfiles: + - f_bill_dotfile + p1: + include: + - "profile_{{@@ d_user @@}}" + p2: + include: + - "profile_{{@@ var1 @@}}" +``` + +## Import profile dotfiles from file + +Profile's dotfiles list can be loaded from external files +by specifying their paths in the config entry `import` under the specific profile. + +The paths can be absolute or relative to the config file location. + +`config.yaml` +```yaml +dotfiles: + f_abc: + dst: ~/.abc + src: abc + f_def: + dst: ~/.def + src: def + f_xyz: + dst: ~/.xyz + src: xyz +profiles: + p1: + dotfiles: + - f_abc + import: + - somedotfiles.yaml +``` + +`somedotfiles.yaml` +``` +dotfiles: + - f_def + - f_xyz +``` + +Variables can be used in `import` and would allow to do something like +```yaml +import: +- profiles.d/{{@@ profile @@}}.yaml +``` + +## Import variables from file + +It is possible to load variables/dynvariables from external files by providing their +paths in the config entry `import_variables`. + +The paths can be absolute or relative to the config file location. + +`config.yaml` +```yaml +config: + backup: true + create: true + dotpath: dotfiles + import_variables: + - variables.d/myvars.yaml +``` + +`variables.d/myvars.yaml` +```yaml +variables: + var1: "extvar1" +dynvariables: + dvar1: "echo extdvar1" +``` + +Dotdrop will fail if an imported path points to a non-existing file. +It is possible to make non-existing paths not fatal by appending the path with `:optional` +```yaml +import_variables: +- variables.d/myvars.yaml:optional +``` + +## Import actions from file + +It is possible to load actions from external files by providing their +paths in the config entry `import_actions`. + +The paths can be absolute or relative to the config file location. + +`config.yaml` +```yaml +config: + backup: true + create: true + dotpath: dotfiles + import_actions: + - actions.d/myactions.yaml +dotfiles: + f_abc: + dst: ~/.abc + src: abc + actions: + - dateme +``` + +`actions.d/myactions.yaml` +```yaml +actions: + dateme: date > /tmp/timestamp +``` + +External variables will take precedence over variables defined within +the source config file. + +Dotdrop will fail if an imported path points to a non-existing file. +It is possible to make non-existing paths not fatal by appending the path with `:optional` +```yaml +import_actions: +- actions.d/myactions.yaml:optional +``` + +## Import config files + +Entire config files can be imported. This means making the following available +from the imported config file in the original config file: + +* dotfiles +* profiles +* actions +* read/write transformations +* variables/dynvariables + +Paths to import can be absolute or relative to the importing config file +location. + +`config.yaml` +```yaml +config: + backup: true + create: true + dotpath: dotfiles + import_configs: + - other-config.yaml +dotfiles: + f_abc: + dst: ~/.abc + src: abc + actions: + - show +profiles: + my-host: + dotfiles: + - f_abc + - f_def + my-haskell: + include: + - other-host +``` + +`other-config.yaml` +```yaml +config: + backup: true + create: true + dotpath: dotfiles-other + import_actions: + - actions.yaml +dotfiles: + f_def: + dst: ~/.def + src: def + f_ghci: + dst: ~/.ghci + src: ghci +profiles: + other-host: + dotfiles: + - f_gchi +``` + +`actions.yaml` +```yaml +actions: + post: + show: less +``` + +In this example `config.yaml` imports `other-config.yaml`. The dotfile `f_def` +used in the profile `my-host` is defined in `other-config.yaml`, and so is the +profile `other-host` included from `my-haskell`. The action `show` is defined +in `actions.yaml`, which is in turn imported by `other-config.yaml`. + +Dotdrop will fail if an imported path points to a non-existing file. +It is possible to make non-existing paths not fatal by appending the path with `:optional` +```yaml +import_configs: +- other-config.yaml:optional +``` + +## Dynamic dotfile paths + +Dotfile source (`src`) and destination (`dst`) can be dynamically constructed using +defined variables ([variables and dynvariables](#variables)). + +For example to have a dotfile deployed on the unique firefox profile where the +profile path is dynamically found using a shell oneliner stored in a dynvariable: +```yaml +dynvariables: + mozpath: find ~/.mozilla/firefox -name '*.default' +dotfiles: + f_somefile: + dst: "{{@@ mozpath @@}}/somefile" + src: firefox/somefile +profiles: + home: + dotfiles: + - f_somefile +``` + +Make sure to quote the path in the config file. + +## Dynamic actions + +Variables ([config variables and dynvariables](#variables) +and [template variables](templating.md#template-variables)) can be used +in actions for more advanced use-cases. + +```yaml +dotfiles: + f_test: + dst: ~/.test + src: test + actions: + - cookie_mv_somewhere "/tmp/moved-cookie" +variables: + cookie_dir_available: (test -d /tmp/cookiedir || mkdir -p /tmp/cookiedir) + cookie_header: "{{@@ cookie_dir_available @@}} && echo 'header' > /tmp/cookiedir/cookie" + cookie_mv: "{{@@ cookie_header @@}} && mv /tmp/cookiedir/cookie" +actions: + cookie_mv_somewhere: "{{@@ cookie_mv @@}} {0}" +``` + +or even something like this: +```yaml +actions: + log: "echo {0} >> {1}" +config: + default_actions: + - preaction '{{@@ _dotfile_key @@}} installed' "/tmp/log" +... +``` + +Make sure to quote the actions using variables. + +## Dynamic transformations + +As for [dynamic actions](#dynamic-actions), transformations support +the use of variables ([variables and dynvariables](#variables) +and [template variables](templating.md#template-variables)). + +A very dumb example: +```yaml +trans_read: + r_echo_abs_src: echo "{0}: {{@@ _dotfile_abs_src @@}}" > {1} + r_echo_var: echo "{0}: {{@@ r_var @@}}" > {1} +trans_write: + w_echo_key: echo "{0}: {{@@ _dotfile_key @@}}" > {1} + w_echo_var: echo "{0}: {{@@ w_var @@}}" > {1} +variables: + r_var: readvar + w_var: writevar +dotfiles: + f_abc: + dst: ${tmpd}/abc + src: abc + trans_read: r_echo_abs_src + trans_write: w_echo_key + f_def: + dst: ${tmpd}/def + src: def + trans_read: r_echo_var + trans_write: w_echo_var +``` + +## Ignore patterns + +It is possible to ignore specific patterns when using dotdrop. For example for `compare` when temporary +files don't need to appear in the output. + +* for [install](usage.md#install-dotfiles) + * using `instignore` in the config file +* for [compare](usage.md#compare-dotfiles) + * using `cmpignore` in the config file + * using the command line switch `-i --ignore` +* for [update](usage.md#update-dotfiles) + * using `upignore` in the config file + * using the command line switch `-i --ignore` + +The ignore pattern must follow Unix shell-style wildcards like for example `*/path/to/file`. +Make sure to quote those when using wildcards in the config file. + +Patterns used on a specific dotfile can be specified relative to the dotfile destination (`dst`). + +```yaml +config: + cmpignore: + - '*/README.md' + upignore: + - '*/README.md' + instignore: + - '*/README.md' +... +dotfiles: + d_vim + dst: ~/.vim + src: vim + upignore: + - "*/undo-dir" + - "*/plugged" +... +``` + +examples + +To completely ignore comparison of a specific dotfile: +```yaml +dotfiles: + d_vim + dst: ~/.vim + src: vim + cmpignore: + - "*" +``` + +To ignore specific directory when updating +```yaml +dotfiles: + d_colorpicker: + src: config/some_directory + dst: ~/.config/some_directory + upignore: + - '*sub_directory_to_ignore' +``` + diff --git a/docs/config/config-variables.md b/docs/config/config-variables.md deleted file mode 100644 index 8a8762b..0000000 --- a/docs/config/config-variables.md +++ /dev/null @@ -1,126 +0,0 @@ -# Config variables - -* [Config available variables](#available-variables) - * [Variables entry](#variables-entry) - * [Profile variables](#profile-variables) - * [Config variables in templates](#config-variables-in-templates) - * [Interpreted variables entry](#interpreted-variables-entry) - ---- - -# Available 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](config.md#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](config.md#dynamic-actions), -[Dynamic transformations](config.md#dynamic-transformations) and [Templating](../template/templating.md)). - -Following variables are available in the config files: - -* [variables defined in the config](#variables-entry) -* [interpreted variables defined in the config](#interpreted-variables-entry) -* [profile variables defined in the config](#profile-variables) -* environment variables: `{{@@ env['MY_VAR'] @@}}` -* dotdrop header: `{{@@ header() @@}}` (see [Dotdrop header](../template/templating.md#dotdrop-header)) - -As well as all template methods (see [Available methods](../template/templating.md#available-methods)) - -# Variables entry - -Variables defined in the `variables` entry are made available within the config file. - -Config variables are recursively evaluated what means that -a config like the below -```yaml -variables: - var1: "var1" - var2: "{{@@ var1 @@}} var2" - var3: "{{@@ var2 @@}} var3" - var4: "{{@@ dvar4 @@}}" -dynvariables: - dvar1: "echo dvar1" - dvar2: "{{@@ dvar1 @@}} dvar2" - dvar3: "{{@@ dvar2 @@}} dvar3" - dvar4: "echo {{@@ var3 @@}}" -``` - -will result in the following available variables: -* var1: `var1` -* var2: `var1 var2` -* var3: `var1 var2 var3` -* var4: `echo var1 var2 var3` -* dvar1: `dvar1` -* dvar2: `dvar1 dvar2` -* dvar3: `dvar1 dvar2 dvar3` -* dvar4: `var1 var2 var3` - -# Profile variables - -Profile variables will take precedence over globally defined variables. -This means that you could do something like this: -```yaml -variables: - git_email: home@email.com -dotfiles: - f_gitconfig: - dst: ~/.gitconfig - src: gitconfig -profiles: - work: - dotfiles: - - f_gitconfig - variables: - git_email: work@email.com - private: - dotfiles: - - f_gitconfig -``` - -# Config variables in templates - -`variables` and `dynvariables` are also made available in templates -(see [Template variables](../template/templating.md#template-variables)). - -Variables in the config file -```yaml -variables: - var1: some variable content - var2: some other content -``` - -Can be used in any templates like this -``` -var1 value is: {{@@ var1 @@}} -``` - -# Interpreted variables entry - -It is also possible to have *dynamic* variables in the sense that their -content will be interpreted by the shell before being substituted. - -These need to be defined in the config file under the entry `dynvariables`. - -For example: -```yaml -dynvariables: - dvar1: head -1 /proc/meminfo - dvar2: "echo 'this is some test' | rev | tr ' ' ','" - dvar3: /tmp/my_shell_script.sh - user: "echo $USER" - config_file: test -f "{{@@ user_config @@}}" && echo "{{@@ user_config @@}}" || echo "{{@@ dfl_config @@}}" -variables: - user_config: "profile_{{@@ user @@}}_uid.yaml" - dfl_config: "profile_default.yaml" -``` - -They have the same properties as [Variables](#variables-entry). diff --git a/docs/config/config.md b/docs/config/config.md deleted file mode 100644 index f1e0971..0000000 --- a/docs/config/config.md +++ /dev/null @@ -1,560 +0,0 @@ -# Config - -The config file used by dotdrop is -[config.yaml](https://github.com/deadc0de6/dotdrop/blob/master/config.yaml). - -## Location - -Unless specified dotdrop will look in following places for the config file (`config.yaml`) -and use the first one found - -* current/working directory or the directory where [dotdrop.sh](https://github.com/deadc0de6/dotdrop/blob/master/dotdrop.sh) is located if used -* `${XDG_CONFIG_HOME}/dotdrop/` -* `~/.config/dotdrop/` -* `/etc/xdg/dotdrop/` -* `/etc/dotdrop/` - -You can force dotdrop to use a different file either by using the `-c --cfg` cli switch -or by defining the `DOTDROP_CONFIG` environment variable. - -## Format - -Dotdrop config file uses [yaml](https://yaml.org/) syntax. - -Content Format: - -* **config** entry (mandatory): contains settings for the deployment - * `backup`: create a backup of the dotfile in case it differs from the - one that will be installed by dotdrop (default *true*) - * `banner`: display the banner (default *true*) - * `cmpignore`: list of patterns to ignore when comparing, apply to all dotfiles - (enclose in quotes when using wildcards, see [ignore patterns](ignore-pattern.md)) - * `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](usage-actions.md)) - * `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) - * `filter_file`: list of paths to load templating filters from - (see [Templating available filters](../template/templating.md#available-filters)) - * `func_file`: list of paths to load templating functions from - (see [Templating available methods](../template/templating.md#available-methods)) - * `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)) - * `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)) - * `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)) - * `instignore`: list of patterns to ignore when installing, apply to all dotfiles - (enclose in quotes when using wildcards, see [ignore patterns](ignore-pattern.md)) - * `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)) - * `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)) - * `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 - * `showdiff`: on install show a diff before asking to overwrite (see `--showdiff`) (default *false*) - * `upignore`: list of patterns to ignore when updating, apply to all dotfiles - (enclose in quotes when using wildcards, see [ignore patterns](ignore-pattern.md)) - * `workdir`: path to the directory where templates are installed before being symlinked - when using `link:link` or `link:link_children` - (absolute path or relative to the config file location, defaults to *~/.config/dotdrop*) - * DEPRECATED `link_by_default`: when importing a dotfile set `link` to that value per default (default *false*) - -* **dotfiles** entry (mandatory): a list of dotfiles - * `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) - * `link`: define how this dotfile is installed. - Possible values: *nolink*, *link*, *link_children* (default: `link_dotfile_default`, - see [Symlinking dotfiles](#symlinking-dotfiles)) - * `actions`: list of action keys that need to be defined in the **actions** entry below - (see [Use actions](usage-actions.md)) - * `cmpignore`: list of patterns to ignore when comparing (enclose in quotes when using wildcards, - see [ignore patterns](ignore-pattern.md)) - * `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-pattern.md)) - * `trans_read`: transformation key to apply when installing this dotfile - (must be defined in the **trans_read** entry below, see [Use transformations](usage-transformations.md)) - * `trans_write`: transformation key to apply when updating this dotfile - (must be defined in the **trans_write** entry below, see [Use transformations](usage-transformations.md)) - * `upignore`: list of patterns to ignore when updating (enclose in quotes when using wildcards, - see [ignore patterns](ignore-pattern.md)) - * DEPRECATED `link_children`: replaced by `link: link_children` - * DEPRECATED `trans`: replaced by `trans_read` - -```yaml - : - dst: - src: - ## Optional - link: (nolink|link|link_children) - ignoreempty: (true|false) - cmpignore: - - "" - upignore: - - "" - instignore: - - "" - actions: - - - trans_read: - trans_write: -``` - -* **profiles** entry (mandatory): a list of profiles with the different dotfiles that - need to be managed - * `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)). - * `include`: include all elements (dotfiles, actions, (dyn)variables, etc) from another profile - (see [Include dotfiles from another profile](#include-dotfiles-from-another-profile)) - * `variables`: profile specific variables - (see [Variables](#variables)) - * `dynvariables`: profile specific interpreted variables - (see [Interpreted variables](#interpreted-variables)) - * `actions`: list of action keys that need to be defined in the **actions** entry below - (see [Use actions](usage-actions.md)) - -```yaml - : - dotfiles: - - - - - - ... - ## Optional - include: - - - - ... - variables: - : - dynvariables: - : - actions: - - - - ... - import: - - - - ... -``` - -* **actions** entry (optional): a list of actions (see [Use actions](usage-actions.md)) - -```yaml -actions: - : -``` - -* **trans_read** entry (optional): a list of transformations (see [Use transformations](usage-transformations.md)) - -```yaml -trans_read: - : -``` - -* **trans_write** entry (optional): a list of write transformations (see [Use transformations](usage-transformations.md)) - -```yaml -trans_write: - : -``` - -* **variables** entry (optional): a list of variables (see [Variables](#variables)) - -```yaml -variables: - : -``` - -* **dynvariables** entry (optional): a list of interpreted variables - (see [Interpreted variables](#interpreted-variables)) - -```yaml -dynvariables: - : -``` - -## Actions - -see [Actions](usage-actions.md) - -## Transformations - -see [Transformations](usage-transformations.md) - -## Variables - -see [Variables](config-variables.md) - -## Interpreted variables - -see [Interpreted variables](config-variables.md) - -## 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 - -If one profile is using the entire set of another profile, one can use -the `include` entry to avoid redundancy. - -Note that everything from the included profile is made available -(actions, variables/dynvariables, etc). - -For example: -```yaml -profiles: - host1: - dotfiles: - - f_xinitrc - include: - - host2 - host2: - dotfiles: - - f_vimrc -``` -Here profile *host1* contains all the dotfiles defined for *host2* plus `f_xinitrc`. - -For more advanced use-cases variables -([variables](config-variables.md) and [dynvariables](config-variables.md)) -can be used to specify the profile to include in a profile - -For example: -```yaml -variables: - var1: "john" -dynvariables: - d_user: "echo $USER" -profiles: - profile_john: - dotfiles: - - f_john_dotfile - profile_bill: - dotfiles: - - f_bill_dotfile - p1: - include: - - "profile_{{@@ d_user @@}}" - p2: - include: - - "profile_{{@@ var1 @@}}" -``` - -## Import profile dotfiles from file - -Profile's dotfiles list can be loaded from external files -by specifying their paths in the config entry `import` under the specific profile. - -The paths can be absolute or relative to the config file location. - -`config.yaml` -```yaml -dotfiles: - f_abc: - dst: ~/.abc - src: abc - f_def: - dst: ~/.def - src: def - f_xyz: - dst: ~/.xyz - src: xyz -profiles: - p1: - dotfiles: - - f_abc - import: - - somedotfiles.yaml -``` - -`somedotfiles.yaml` -``` -dotfiles: - - f_def - - f_xyz -``` - -Variables can be used in `import` and would allow to do something like -```yaml -import: -- profiles.d/{{@@ profile @@}}.yaml -``` - -## Import variables from file - -It is possible to load variables/dynvariables from external files by providing their -paths in the config entry `import_variables`. - -The paths can be absolute or relative to the config file location. - -`config.yaml` -```yaml -config: - backup: true - create: true - dotpath: dotfiles - import_variables: - - variables.d/myvars.yaml -``` - -`variables.d/myvars.yaml` -```yaml -variables: - var1: "extvar1" -dynvariables: - dvar1: "echo extdvar1" -``` - -Dotdrop will fail if an imported path points to a non-existing file. -It is possible to make non-existing paths not fatal by appending the path with `:optional` -```yaml -import_variables: -- variables.d/myvars.yaml:optional -``` - -## Import actions from file - -It is possible to load actions from external files by providing their -paths in the config entry `import_actions`. - -The paths can be absolute or relative to the config file location. - -`config.yaml` -```yaml -config: - backup: true - create: true - dotpath: dotfiles - import_actions: - - actions.d/myactions.yaml -dotfiles: - f_abc: - dst: ~/.abc - src: abc - actions: - - dateme -``` - -`actions.d/myactions.yaml` -```yaml -actions: - dateme: date > /tmp/timestamp -``` - -External variables will take precedence over variables defined within -the source config file. - -Dotdrop will fail if an imported path points to a non-existing file. -It is possible to make non-existing paths not fatal by appending the path with `:optional` -```yaml -import_actions: -- actions.d/myactions.yaml:optional -``` - -## Import config files - -Entire config files can be imported. This means making the following available -from the imported config file in the original config file: - -* dotfiles -* profiles -* actions -* read/write transformations -* variables/dynvariables - -Paths to import can be absolute or relative to the importing config file -location. - -`config.yaml` -```yaml -config: - backup: true - create: true - dotpath: dotfiles - import_configs: - - other-config.yaml -dotfiles: - f_abc: - dst: ~/.abc - src: abc - actions: - - show -profiles: - my-host: - dotfiles: - - f_abc - - f_def - my-haskell: - include: - - other-host -``` - -`other-config.yaml` -```yaml -config: - backup: true - create: true - dotpath: dotfiles-other - import_actions: - - actions.yaml -dotfiles: - f_def: - dst: ~/.def - src: def - f_ghci: - dst: ~/.ghci - src: ghci -profiles: - other-host: - dotfiles: - - f_gchi -``` - -`actions.yaml` -```yaml -actions: - post: - show: less -``` - -In this example `config.yaml` imports `other-config.yaml`. The dotfile `f_def` -used in the profile `my-host` is defined in `other-config.yaml`, and so is the -profile `other-host` included from `my-haskell`. The action `show` is defined -in `actions.yaml`, which is in turn imported by `other-config.yaml`. - -Dotdrop will fail if an imported path points to a non-existing file. -It is possible to make non-existing paths not fatal by appending the path with `:optional` -```yaml -import_configs: -- other-config.yaml:optional -``` - -## Dynamic dotfile paths - -Dotfile source (`src`) and destination (`dst`) can be dynamically constructed using -defined variables ([variables and dynvariables](config-variables.md)). - -For example to have a dotfile deployed on the unique firefox profile where the -profile path is dynamically found using a shell oneliner stored in a dynvariable: -```yaml -dynvariables: - mozpath: find ~/.mozilla/firefox -name '*.default' -dotfiles: - f_somefile: - dst: "{{@@ mozpath @@}}/somefile" - src: firefox/somefile -profiles: - home: - dotfiles: - - f_somefile -``` - -Make sure to quote the path in the config file. - -## Dynamic actions - -Variables ([config variables and dynvariables](config-variables.md) -and [template variables](../template/templating.md#template-variables)) can be used -in actions for more advanced use-cases. - -```yaml -dotfiles: - f_test: - dst: ~/.test - src: test - actions: - - cookie_mv_somewhere "/tmp/moved-cookie" -variables: - cookie_dir_available: (test -d /tmp/cookiedir || mkdir -p /tmp/cookiedir) - cookie_header: "{{@@ cookie_dir_available @@}} && echo 'header' > /tmp/cookiedir/cookie" - cookie_mv: "{{@@ cookie_header @@}} && mv /tmp/cookiedir/cookie" -actions: - cookie_mv_somewhere: "{{@@ cookie_mv @@}} {0}" -``` - -or even something like this: -```yaml -actions: - log: "echo {0} >> {1}" -config: - default_actions: - - preaction '{{@@ _dotfile_key @@}} installed' "/tmp/log" -... -``` - -Make sure to quote the actions using variables. - -## Dynamic transformations - -As for [dynamic actions](#dynamic-actions), transformations support -the use of variables ([variables and dynvariables](config-variables.md) -and [template variables](../template/templating.md#template-variables)). - -A very dumb example: -```yaml -trans_read: - r_echo_abs_src: echo "{0}: {{@@ _dotfile_abs_src @@}}" > {1} - r_echo_var: echo "{0}: {{@@ r_var @@}}" > {1} -trans_write: - w_echo_key: echo "{0}: {{@@ _dotfile_key @@}}" > {1} - w_echo_var: echo "{0}: {{@@ w_var @@}}" > {1} -variables: - r_var: readvar - w_var: writevar -dotfiles: - f_abc: - dst: ${tmpd}/abc - src: abc - trans_read: r_echo_abs_src - trans_write: w_echo_key - f_def: - dst: ${tmpd}/def - src: def - trans_read: r_echo_var - trans_write: w_echo_var -``` diff --git a/docs/config/ignore-pattern.md b/docs/config/ignore-pattern.md deleted file mode 100644 index f6488f8..0000000 --- a/docs/config/ignore-pattern.md +++ /dev/null @@ -1,59 +0,0 @@ -# Ignore patterns - -It is possible to ignore specific patterns when using dotdrop. For example for `compare` when temporary -files don't need to appear in the output. - -* for [install](../usage.md#install-dotfiles) - * using `instignore` in [the config file](config.md) -* for [compare](../usage.md#compare-dotfiles) - * using `cmpignore` in [the config file](config.md) - * using the command line switch `-i --ignore` -* for [update](../usage.md#update-dotfiles) - * using `upignore` in [the config file](config.md) - * using the command line switch `-i --ignore` - -The ignore pattern must follow Unix shell-style wildcards like for example `*/path/to/file`. -Make sure to quote those when using wildcards in the config file. - -Patterns used on a specific dotfile can be specified relative to the dotfile destination (`dst`). - -```yaml -config: - cmpignore: - - '*/README.md' - upignore: - - '*/README.md' - instignore: - - '*/README.md' -... -dotfiles: - d_vim - dst: ~/.vim - src: vim - upignore: - - "*/undo-dir" - - "*/plugged" -... -``` - -## examples - -To completely ignore comparison of a specific dotfile: -```yaml -dotfiles: - d_vim - dst: ~/.vim - src: vim - cmpignore: - - "*" -``` - -To ignore specific directory when updating -```yaml -dotfiles: - d_colorpicker: - src: config/some_directory - dst: ~/.config/some_directory - upignore: - - '*sub_directory_to_ignore' -``` diff --git a/docs/config/usage-actions.md b/docs/config/usage-actions.md deleted file mode 100644 index 9ac129b..0000000 --- a/docs/config/usage-actions.md +++ /dev/null @@ -1,165 +0,0 @@ -* [Dotfile actions](#dotfile-actions) -* [Default actions](#default-actions) -* [Profile actions](#profile-actions) -* [Fake dotfile and actions](#fake-dotfile-and-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. - -# Dotfile actions - -It is sometimes useful to execute some kind of action -when deploying a dotfile. - -Note that dotfile actions are only -executed when the dotfile is installed. - -For example let's consider -[Vundle](https://github.com/VundleVim/Vundle.vim) is used -to manage vim's plugins, the following action could -be set to update and install the plugins when `vimrc` is -deployed: - -```yaml -actions: - vundle: vim +VundleClean! +VundleInstall +VundleInstall! +qall -config: - backup: true - create: true - dotpath: dotfiles -dotfiles: - f_vimrc: - dst: ~/.vimrc - src: vimrc - actions: - - vundle -profiles: - home: - dotfiles: - - f_vimrc -``` - -Thus when `f_vimrc` is installed, the command -`vim +VundleClean! +VundleInstall +VundleInstall! +qall` will -be executed. - -Sometimes, you may even want to execute some action prior to deploying a dotfile. -Let's take another example with -[vim-plug](https://github.com/junegunn/vim-plug): - -```yaml -actions: - pre: - vim-plug-install: test -e ~/.vim/autoload/plug.vim || (mkdir -p ~/.vim/autoload; curl - -fLo ~/.vim/autoload/plug.vim https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim) - vim-plug: vim +PlugInstall +qall -config: - backup: true - create: true - dotpath: dotfiles -dotfiles: - f_vimrc: - dst: ~/.vimrc - src: vimrc - actions: - - vim-plug-install - - vim-plug -profiles: - home: - dotfiles: - - f_vimrc -``` - -This way, we make sure [vim-plug](https://github.com/junegunn/vim-plug) -is installed prior to deploying the `~/.vimrc` dotfile. - -You can also define `post` actions like this: - -```yaml -actions: - post: - some-action: echo "Hello, World!" >/tmp/log -``` - -If you don't specify neither `post` nor `pre`, the action will be executed -after the dotfile deployment (which is equivalent to `post`). -Actions cannot obviously be named `pre` or `post`. - -Actions can even be parameterized. For example: -```yaml -actions: - echoaction: echo '{0}' > {1} -config: - backup: true - create: true - dotpath: dotfiles -dotfiles: - f_vimrc: - dst: ~/.vimrc - src: vimrc - actions: - - echoaction "vim installed" /tmp/mydotdrop.log - f_xinitrc: - dst: ~/.xinitrc - src: xinitrc - actions: - - echoaction "xinitrc installed" /tmp/myotherlog.log -profiles: - home: - dotfiles: - - f_vimrc - - f_xinitrc -``` - -The above will execute `echo 'vim installed' > /tmp/mydotdrop.log` when -vimrc is installed and `echo 'xinitrc installed' > /tmp/myotherlog.log'` -when xinitrc is installed. - -# Default actions - -Dotdrop allows to execute an action for any dotfile installation. These actions work as any other action (*pre* or *post*). - -For example, the below action will log each dotfile installation to a file. - -```yaml -actions: - post: - loginstall: "echo {{@@ _dotfile_abs_src @@}} installed to {{@@ _dotfile_abs_dst @@}} >> {0}" -config: - backup: true - create: true - dotpath: dotfiles - default_actions: - - loginstall "/tmp/dotdrop-installation.log" -dotfiles: - f_vimrc: - dst: ~/.vimrc - src: vimrc -profiles: - hostname: - dotfiles: - - f_vimrc -``` - -# Profile actions - -Profile can be either `pre` or `post` actions. Those are executed before -any dotfile installation (for `pre`) and after all dotfiles installation (for `post`) -only if at least one dotfile has been installed. - -# Fake dotfile and actions - -*Fake* dotfile can be created by specifying no `dst` and no `src` (see [config format](https://github.com/deadc0de6/dotdrop/wiki/config#format)). By binding an action to such a *fake* dotfile, you make sure the action is always executed since *fake* dotfile are always considered installed. - -```yaml -actions: - always_action: 'date > ~/.dotdrop.log' -dotfiles: - fake: - src: - dst: - actions: - - always_action -``` diff --git a/docs/config/usage-transformations.md b/docs/config/usage-transformations.md deleted file mode 100644 index 1577e9b..0000000 --- a/docs/config/usage-transformations.md +++ /dev/null @@ -1,58 +0,0 @@ -* [Use transformations](#use-transformations) -* [Arguments and templating](#arguments-and-templating) -* [Examples](#examples) - ---- - -**Note**: any transformation 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. - -# Use transformations - -There are two types of transformations available: - -* **read transformations**: used to transform dotfiles before they are installed ([Config](config.md) key `trans_read`) - * Used for commands `install` and `compare` - * They have two arguments: - * **{0}** will be replaced with the dotfile to process - * **{1}** will be replaced with a temporary file to store the result of the transformation - * Happens **before** the dotfile is templated with jinja2 (see [templating](../template/templating.md)) - -* **write transformations**: used to transform files before updating a dotfile ([Config](config.md) key `trans_write`) - * Used for command `update` - * They have two arguments: - * **{0}** will be replaced with the file path to update the dotfile with - * **{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 [examples](#examples). - -Note that transformations cannot be used if the dotfiles is to be linked (when `link: link` or `link: link_children`). - -# Arguments and templating - -Transformations also support additional positional arguments that must start from 2 (since `{0}` and `{1}` are added automatically). The transformations itself as well as its arguments can also be templated. - -For example -```yaml -trans_read: - targ: echo "$(basename {0}); {{@@ _dotfile_key @@}}; {2}; {3}" > {1} -dotfiles: - f_abc: - dst: /tmp/abc - src: abc - trans_read: targ "{{@@ profile @@}}" lastarg -profiles: - p1: - dotfiles: - - f_abc -``` - -will result in `abc; f_abc; p1; lastarg` - -# Examples - -See - -* [Store compressed directories](../howto/store-compressed-directories.md) -* [Sensitive dotfiles](../howto/sensitive-dotfiles.md) diff --git a/docs/howto/README.md b/docs/howto/README.md index 2fa3913..887613d 100644 --- a/docs/howto/README.md +++ b/docs/howto/README.md @@ -2,15 +2,15 @@ ## Append to a dotfile -[Append to a dotfile](howto/append.md) +[Append to a dotfile](append.md) ## Create special files -[Create special files](howto/create-special-files.md) +[Create special files](create-special-files.md) ## Handle special chars -[Handle special chars](howto/special-chars.md) +[Handle special chars](special-chars.md) ## Improve git integration @@ -18,20 +18,20 @@ ## Merge files on install -[Merge files on install](howto/merge-files-when-installing.md) +[Merge files on install](merge-files-when-installing.md) ## Share content across dotfiles -[Share content across dotfiles](howto/sharing-content.md) +[Share content across dotfiles](sharing-content.md) ## Store compressed directories -[Store compressed directories](howto/store-compressed-directories.md) +[Store compressed directories](store-compressed-directories.md) ## Store secrets -[Store secrets](howto/sensitive-dotfiles.md) +[Store secrets](sensitive-dotfiles.md) ## Symlink dotfiles -[Symlink dotfiles](howto/symlinked-dotfiles.md) +[Symlink dotfiles](symlinked-dotfiles.md) diff --git a/docs/howto/append.md b/docs/howto/append.md index 11c3331..6b07fb3 100644 --- a/docs/howto/append.md +++ b/docs/howto/append.md @@ -1,6 +1,6 @@ -Sometimes it might be useful to be able to append some text to a +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](https://github.com/deadc0de6/dotdrop/wiki/usage-actions) +[actions](../config.md#actions). and a temporary file. Below is a config example to append to a file: @@ -18,7 +18,7 @@ dotfiles: - append "{{@@ tmpfile @@}}" "{{@@ somefile_final @@}}" actions: pre: - strip: "sed -i '/^# my pattern$/,$d' {0}" + strip: "sed -i '/^# my pattern$/,$d' {0}" post: append: "cat {0} >> {1}; rm -f {0}" ``` @@ -28,4 +28,4 @@ Obviously the dotfile in the dotpath should start with a unique pattern (here `# ``` # my pattern this is the end -``` \ No newline at end of file +``` diff --git a/docs/howto/create-special-files.md b/docs/howto/create-special-files.md index 92b5e27..903ca68 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/usage-actions.md) and a *fake* dotfile. +[actions](../config.md#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`. diff --git a/docs/howto/merge-files-when-installing.md b/docs/howto/merge-files-when-installing.md index ed38bae..4968cd8 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/config-variables.md#interpreted-variables-entry) +[dynvariables](../config.md#interpreted-variables) 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/config-variables.md#interpreted-variables-entry) +First define a [dynvariables](../config.md#interpreted-variables) in the config file which will look for files to include in the above directory: ```yaml dynvariables: @@ -59,7 +59,7 @@ dynvariables: ``` Note that `_dotdrop_dotpath` is part of the built-in variables -(for more see [template variables](../template/templating.md#template-variables)). +(for more see [template variables](../templating.md#template-variables)). And then use the generated list in the dotfile template: ``` diff --git a/docs/howto/sensitive-dotfiles.md b/docs/howto/sensitive-dotfiles.md index 0147efb..608869a 100644 --- a/docs/howto/sensitive-dotfiles.md +++ b/docs/howto/sensitive-dotfiles.md @@ -8,7 +8,7 @@ # Available solutions -Two solutions exist, the first one using an unversioned file (see [Environment variables](../template/templating.md#environment-variables)) +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 diff --git a/docs/howto/sharing-content.md b/docs/howto/sharing-content.md index a8632f6..7f695a4 100644 --- a/docs/howto/sharing-content.md +++ b/docs/howto/sharing-content.md @@ -64,7 +64,7 @@ export DB_PORT='4521' Albeit flexible, the previous method is a bit cumbersome for some use cases. For example, when the dotfiles belong to different profiles, the cleanest solution consists in using -[profile variables](../config/config-variables.md#profile-variables). This is achieved by: +[profile variables](../config.md#profile-variables). This is achieved by: 1. Creating the merged dotfile with an arbitrary name somewhere in `dotpath`. 2. Adding some variables in the merged dotfile via templating. diff --git a/docs/howto/symlinked-dotfiles.md b/docs/howto/symlinked-dotfiles.md index bee1d17..ba2d016 100644 --- a/docs/howto/symlinked-dotfiles.md +++ b/docs/howto/symlinked-dotfiles.md @@ -85,10 +85,10 @@ $ tree -L 1 ~/.vim # Templating symlinked dotfiles For dotfiles not using any templating directives, those are directly linked -to dotdrop's `dotpath` directory (see [Config](../config/config.md)). +to dotdrop's `dotpath` directory (see [Config](../config.md)). When using templating directives however the dotfiles are first installed into -`workdir` (defaults to *~/.config/dotdrop*, see [Config](../config/config.md)) +`workdir` (defaults to *~/.config/dotdrop*, see [Config](../config.md)) and then symlinked there. This applies to both dotfiles with `link: link` and `link: link_children`. diff --git a/docs/installation.md b/docs/installation.md index cc1a1e0..4095ad9 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -70,7 +70,7 @@ Then follow the instructions under [As a submodule](#as-a-submodule). Install dotdrop ```bash -$ pip3 install --user dotdrop +$ pip3 install dotdrop --user ``` and then [setup your repository](#setup-your-repository). @@ -147,7 +147,7 @@ $ git push Or if installed through pypi: ```bash -$ pip3 install --user dotdrop --upgrade +$ pip3 install dotdrop --upgrade --user ``` ## Setup your repository @@ -173,7 +173,7 @@ $ wget https://raw.githubusercontent.com/deadc0de6/dotdrop/master/config.yaml ``` It is recommended to store your config file directly within your repository (*my-dotfiles* in the example above) but you could save it in different places if you wish, -see [this doc](https://github.com/deadc0de6/dotdrop/wiki/config#location) for more. +see [config location](config.md#location) for more. ```bash $ tree my-dotfiles @@ -188,9 +188,10 @@ in your preferred shell to call dotdrop with the config file path argument. alias dotdrop='dotdrop --cfg=' ``` -For more info on the config file format, see [the config doc](https://github.com/deadc0de6/dotdrop/wiki/config) +For more info on the config file format, see [the config doc](config.md). -Finally start using dotdrop with `dotdrop --help`. See the [usage doc](https://github.com/deadc0de6/dotdrop/wiki/usage) and [the example](https://github.com/deadc0de6/dotdrop/blob/master/README.md#getting-started). +Finally start using dotdrop with `dotdrop --help`. See the [usage doc](usage.md) +and [the example](https://github.com/deadc0de6/dotdrop/blob/master/README.md#getting-started). ## Shell completion diff --git a/docs/template/templating.md b/docs/templating.md similarity index 91% rename from docs/template/templating.md rename to docs/templating.md index 7a5697e..1f96ba0 100644 --- a/docs/template/templating.md +++ b/docs/templating.md @@ -25,12 +25,12 @@ Following variables are available in templates: * `{{@@ profile @@}}` contains the profile provided to dotdrop. * `{{@@ env['MY_VAR'] @@}}` contains environment variables (see [Environment variables](#environment-variables)). * `{{@@ header() @@}}` contains dotdrop header (see [Dotdrop header](#dotdrop-header)). -* `{{@@ _dotdrop_dotpath @@}}` contains the [dotpath](https://github.com/deadc0de6/dotdrop/wiki/config) absolute path. -* `{{@@ _dotdrop_cfgpath @@}}` contains the absolute path to the [config file](https://github.com/deadc0de6/dotdrop/wiki/config). -* `{{@@ _dotdrop_workdir @@}}` contains the [workdir](https://github.com/deadc0de6/dotdrop/wiki/config) absolute path. +* `{{@@ _dotdrop_dotpath @@}}` contains the [dotpath](config.md) absolute path. +* `{{@@ _dotdrop_cfgpath @@}}` contains the absolute path to the [config file](config.md). +* `{{@@ _dotdrop_workdir @@}}` contains the [workdir](config.md) absolute path. * dotfile specific variables (see [Dotfile variables](#dotfile-variables)) -* config variables (see [Variables](../config/config-variables.md)). -* config interpreted variables (see [Interpreted variables](../config/config-variables.md)). +* config variables (see [Variables](config.md#variables)). +* config interpreted variables (see [Interpreted variables](config.md#interpreted-variables)). ## Dotfile variables @@ -59,7 +59,7 @@ It's possible to access environment variables inside the templates. ``` This allows for storing host-specific properties and/or secrets in environment variables. -It is recommended to use `variables` (see [Config variables](../config/config-variables.md)) +It is recommended to use `variables` (see [config variables](config.md#variables)) instead of environment variables unless these contain sensitive information that shouldn't be versioned in git. @@ -201,7 +201,7 @@ It is possible to avoid having an empty rendered template being deployed by setting the `ignoreempty` entry to *true*. This can be set globally for all dotfiles or only for specific dotfiles. -For more see the [Config](../config/config.md). +For more see the [Config](config.md). ## Include file or template in template diff --git a/docs/usage.md b/docs/usage.md index 2dab09c..ca07693 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -13,7 +13,6 @@ Then if you happen to update the file/directory directly on the filesystem (add For more advanced uses: -* See [this wiki](https://github.com/deadc0de6/dotdrop/wiki) * `dotdrop --help` for more options. * [the example](https://github.com/deadc0de6/dotdrop#getting-started) @@ -24,14 +23,14 @@ Simply run $ dotdrop install ``` -options +some available options * `-t --temp`: install the dotfile(s) to a temporary directory for review (it helps to debug templating issues for example). Note that actions are not executed in that mode. * `-a --force-actions`: force the execution of actions even if the dotfiles are not installed For more detail, see the usage with `dotdrop --help` -To ignore specific pattern during installation see [the dedicated wiki page](config/ignore-pattern.md) +To ignore specific pattern during installation see [the ignore patterns](config.md#ignore-patterns) ## Compare dotfiles @@ -44,7 +43,7 @@ The diffing is done by `diff` in the backend, one can provide its specific diff command using the config option `diff_command`. To ignore specific pattern, -see [the dedicated wiki page](config/ignore-pattern.md) +see [the ignore patterns](config.md#ignore-patterns) It is also possible to install all dotfiles for a specific profile in a temporary directory in order to manually compare them with @@ -160,11 +159,11 @@ $ dotdrop update --key f_vimrc If not argument is provided, all dotfiles for the selected profile are updated. To ignore specific pattern, -see [the dedicated wiki page](config/ignore-pattern.md) +see [the dedicated page](config.md#ignore-patterns) There are two cases when updating a dotfile: -### The dotfile doesn't use [templating](template/templating.md) +### The dotfile doesn't use [templating](templating.md) The new version of the dotfile is copied to the *dotpath* directory and overwrites the old version. If git is used to version the dotfiles stored by dotdrop, the git command @@ -175,7 +174,7 @@ $ dotdrop update ~/.vimrc $ git diff ``` -### The dotfile uses [templating](template/templating.md) +### The dotfile uses [templating](templating.md) The dotfile must be manually updated, three solutions can be used to identify the changes to apply to the template: diff --git a/mkdocs.yml b/mkdocs.yml index 32a8ed8..49a652c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -4,17 +4,20 @@ repo_url: https://github.com/deadc0de6/dotdrop theme: name: readthedocs highlightjs: true + hljs_languages: + - yaml use_directory_urls: true nav: - Home: 'README.md' - Installation: 'installation.md' - Usage: 'usage.md' - - Config: 'config/config.md' - - Template: 'template/templating.md' + - Config: 'config.md' + - Templating: 'templating.md' - HowTo: 'howto/README.md' - Contributing: 'contributing.md' markdown_extensions: - - toc: - baselevel: 2 - permalink: "#" + - meta + - tables + - fenced_code + - toc