dotdrop/docs/config.md

Location

The config file used by dotdrop is config.yaml.

Unless specified dotdrop will look in following places for its config file and use the first one found

• current/working directory or the directory where 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.

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)
• external path specifications
  • import_variables
  • import_actions
  • import_configs
  • profiles's import
  • profiles's include

actions and transformations also support the use of variables but those are resolved when the action/transformation is executed (see Dynamic actions, Dynamic transformations and Templating).

Following variables are available in the config files:

• variables defined in the config
• interpreted variables defined in the config
• profile variables defined in the config
• environment variables: {{@@ env['MY_VAR'] @@}}
• dotdrop header: {{@@ header() @@}} (see Dotdrop header)

As well as all template methods and template filters.

Note that all variables available in the config file will then be available during templating.

Here are some rules on the use of variables in configs:

• interpreted variables are executed in their own file
• interpreted variables and variables are templated before interpreted variables are executed
• config files do not have access to variables defined above in the import tree
• dynvariables take precedence over variables
• profile (dyn)variables take precedence over any other (dyn)variables
• 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

Permissions

Dotfile allows to control the permission applied to a dotfile using the config dotfile entry chmod. A chmod entry on a directory is applied to the directory only, not recursively.

On import the following rules are applied:

• if the -m --preserve-mode switch is provided the imported file permissions are stored in the chmod entry
• if imported file permissions differ from umask its permissions are automatically stored in the chmod entry

On install the following rules are applied:

• if chmod is specified in the dotfile, it will be applied to the installed dotfile
• if file exists and its permissions differ from umask and no chmod is specified user needs to confirm installation (unless -f --force is used or the permission match the dotfile in the dotpath)

On update:

• no chmod entry is added/updated in the config however the rights are mirrored from the filesystem to the file in dotpath

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

Template config entries

Some entries in the config can use the templating feature (see templating):

Entry	Related doc
dotfile src	dynamic dotfile paths
dotfile dst	dynamic dotfile paths
dotfile link	dynamic dotfile link value
variables	variables
dynvariables	dynvariables
actions	dynamic actions
profile include	profile include
profile import	profile import
import_variables	import_variables
import_actions	import_actions
import_configs	import_configs

All dotfiles for a profile

To use all defined dotfiles for a profile, simply use the keyword ALL.

For example:

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 files don't need to appear in the output.

• for install
  • using instignore in the config file
• for compare
  • using cmpignore in the config file
  • using the command line switch -i --ignore
• for update
  • 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).

config:
  cmpignore:
  - '*/README.md'
  upignore:
  - '*/README.md'
  instignore:
  - '*/README.md'
...
dotfiles:
  d_vim
    dst: ~/.vim
    src: vim
    upignore:
    - "*/undo-dir"
    - "*/plugged"
...

To completely ignore comparison of a specific dotfile:

dotfiles:
  d_vim
    dst: ~/.vim
    src: vim
    cmpignore:
    - "*"

To ignore specific directory when updating

dotfiles:
  d_colorpicker:
    src: config/some_directory
    dst: ~/.config/some_directory
    upignore:
      - '*sub_directory_to_ignore'