dotdrop/docs/config-file.md

Config file

Location

The default config file used by dotdrop is config.yaml.

Unless specified otherwise, dotdrop will look in the 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 the following elements of the config:

• Dotfile src and dst paths (See Dynamic dotfile paths)
• External paths
  • import_variables
  • import_actions
  • import_configs
  • Profiles' import
  • Profiles' 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).

The following variables are available in the config files:

• Variables defined in the config
• Interpreted variables defined in the config
• User 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.
• User variables are ignored if any other variable with the same key is defined.

Permissions

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

For example:

dotfiles:
  f_file:
    src: file
    dst: ~/file
    chmod: 644
  f_dir:
    src: dir
    dst: ~/dir
    chmod: 744

On import, the following rules are applied:

• If the -m/--preserve-mode switch is provided or the config option chmod_on_import is true, the imported file's permissions are stored in a chmod entry
• If the imported file's permissions differ from the umask, then the permissions are automatically stored in the chmod entry.
• Otherwise, no chmod entry is added

On install, the following rules are applied:

• If chmod is specified in the dotfile, it will be applied to the installed dotfile.
• Otherwise, the permissions of the dotfile in the dotpath are applied.
• If the global setting force_chmod is set to true, dotdrop will not ask for confirmation to apply permissions.

On update, the following rule is applied:

• If the permissions of the file in the filesystem differ from the dotfile in the dotpath, then the dotfile entry chmod is added/updated accordingly.

Symlinking 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 be templated (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 in 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 install:
  • Using instignore in the config file
• For import:
  • Using impignore 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 these when using wildcards in the config file.

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

Patterns used for a specific dotfile can be specified relative to the dotfile destination (dst).

Similar to a .gitignore file, you can prefix ignore patterns with an exclamation point (!). This so-called "negative ignore pattern" will cause any files that match that pattern to not be ignored, provided they would have been ignored by an earlier ignore pattern (dotdrop will warn if that is not the case). This feature allows to, for example, ignore all files within a certain directory, except for a particular one (See examples below).

To completely ignore comparison of a specific dotfile:

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

To ignore a specific directory when updating:

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

To ignore a specific file testfile and directory testdir when importing:

config:
  impignore:
    - "*/testfile"
    - "testdir"

To ignore all files within a certain directory relative to dst, except one called custom_plugin.zsh:

dotfiles:
  d_zsh:
    src: zsh
    dst: ~/.config/zsh
    upignore:
      - "plugins/*"
      - "!plugins/custom_plugin.zsh"

To ignore everything except a single file named file:

dotfiles:
  d_dir
    src: dir
    dst: ~/dir
    cmpignore:
      - '!file'
      - '[a-zA-Z0-9]*'

Ignore missing

Sometimes, it is nice to have update not copy all the files in the installed directory or compare diff them.

For example, maybe you only want to include a single configuration file in your repository and don't want to include other files the program uses, such as a cached files. Maybe you only want to change one file and don't want the others cluttering your repository. Maybe the program changes these files quite often and creates unnecessary diffs in your dotfiles.

In these cases, you can use the ignore-missing option. This option is available as a flag (--ignore-missing or -z) to the update and compare commands, or as ignore-missing in the config.

To configure globally, place the following in config.yaml:

config:
  ignore_missing_in_dotdrop: true

To configure per dotfile:

dotfiles:
  f_abc:
    ignore_missing_in_dotdrop: true

toml

Dotdrop should be able to handle toml config file however this feature hasn't been extensively tested. A base config.toml is available to get started.

The script (yaml-to-toml.py) allows to convert a yaml dotdrop config file to toml.

For more see issue #343.