Skip to content

Latest commit

 

History

History
353 lines (294 loc) · 11.2 KB

config-file.md

File metadata and controls

353 lines (294 loc) · 11.2 KB

Config file

Location

The default config file used by dotdrop is config.yaml. A clean base config can be generated using dotdrop gencfg.

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
  • transformations

Note that variables used in actions and transformations are resolved when the action/transformation is executed (See Dynamic actions, Dynamic transformations and Templating).

The following variables are available in the config files:

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:

  • dynvariables are executed in their own file.
  • dynvariables and variables are templated before dynvariables are executed.
  • Config files do not have access to variables defined above in the import tree (variables defined in importing config are not seen by the imported config file, where import can be any of import_configs, import_variables, import_actions, profile's import and profile's include)
  • 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.
  • uservariables are ignored if any other variable with the same key is defined.

For more see the CONTRIBUTING doc.

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
  f_preserve:
    src: pfile
    dst: ~/pfile
    chmod: preserve

The chmod value defines the file permissions in octal notation to apply to the dotfile. If undefined new files will get the system default permissions (see umask, 777-<umask> for directories and 666-<umask> for files).

The special keyword preserve allows to ensure that if the dotfiles already exists on the filesystem, its permission is not altered during install and the chmod config value won't be changed during update.

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.
  • If chmod is preserve and the destination exists with a different permission set than system default, then it is not altered

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 (unless chmod value is preserve)

Symlinking dotfiles

see the symlink dotfiles documentation.

Template config entries

Some entries in the config can be templated (See templating):

Entry Related doc
dotpath config entries
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.

The ignore pattern must follow Unix shell-style wildcards, like for example */path/to/file for files and */path/to/directory/* for directories. Make sure to quote these when using wildcards in the config file.

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

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).

For example to ignore everything but the colors directory under ~/.vim

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

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]*'

To ignore specific files on different profiles (same src but some files are not installed for specific profile)

dotfiles:
  d_testdir_p1:
    src: testdir
    dst: ~/.testdir
    instignore:
    - '*/ignore-me-1'
  d_testdir_p2:
    src: testdir
    dst: ~/.testdir
    instignore:
    - '*/ignore-me-2'
profiles:
  p1:
    dotfiles:
    - d_testdir_p1
  p2:
    dotfiles:
    - d_testdir_p2

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.