dotdrop/docs/config-format.md

Config format

The dotdrop config file uses YAML syntax.

Here is a minimal config file to start with: config.yaml.

config entry

The config entry (mandatory) contains settings for the deployment.

Entry	Description	Default
backup	Create a backup of the dotfile in case it differs from the one that will be installed by dotdrop	true
banner	Display the banner	true
check_version	Check if a new version of dotdrop is available on github	false
chmod_on_import	Always add a chmod entry on newly imported dotfiles (see --preserve-mode)	false
clear_workdir	On install clear the workdir before installing dotfiles (see --workdir-clear)	false
compare_workdir	On compare notify on files in workdir not tracked by dotdrop	false
cmpignore	List of patterns to ignore when comparing, applied to all dotfiles (enclose in quotes when using wildcards; see ignore patterns)	-
create	Create a directory hierarchy when installing dotfiles if it doesn't exist	true
default_actions	List of action keys to execute for all installed dotfiles (See actions)	-
diff_command	The diff command to use for diffing files	diff -r -u {0} {1}
dotpath	Path to the directory containing the dotfiles to be managed by dotdrop (absolute path or relative to the config file location)	dotfiles
filter_file	List of paths to load templating filters from (See Templating available filters)	-
force_chmod	If true, do not ask confirmation to apply permissions on install	false
func_file	List of paths to load templating functions from (See Templating available methods)	-
ignore_missing_in_dotdrop	Ignore missing files in dotdrop when comparing and importing (See Ignore missing)	false
ignoreempty	Do not deploy template if empty	false
impignore	List of patterns to ignore when importing (enclose in quotes when using wildcards; see ignore patterns)	-
import_actions	List of paths to load actions from (absolute path or relative to the config file location; see Import actions from file)	-
import_configs	List of config file paths to be imported into the current config (absolute paths or relative to the current config file location; see Import config files)	-
import_variables	List of paths to load variables from (absolute paths or relative to the config file location; see Import variables from file)	-
instignore	List of patterns to ignore when installing, applied to all dotfiles (enclose in quotes when using wildcards; see ignore patterns)	-
keepdot	Preserve leading dot when importing hidden file in the dotpath	false
key_prefix	Prefix dotfile key on import with f<key_separator> for file and d<key_separator> for directory	true
key_separator	Separator to use on dotfile key generation on import	_
link_dotfile_default	Set a dotfile's link attribute to this value when undefined. Possible values: nolink, link (See Symlinking dotfiles)	nolink
link_on_import	Set a dotfile's link attribute to this value when importing. Possible values: nolink, link Symlinking dotfiles)	nolink
longkey	Use long keys for dotfiles when importing (See Import dotfiles)	false
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)	false
template_dotfile_default	Disable templating on all dotfiles when set to false	true
upignore	List of patterns to ignore when updating, appled to all dotfiles (enclose in quotes when using wildcards; see 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)	~/.config/dotdrop
link_by_default	When importing a dotfile, set link to this value by default	false

dotfiles entry

The dotfiles entry (mandatory) contains a YAML object with sub-objects for the dotfiles managed by dotdrop. The entries in the sub-objects are as follows:

Entry	Description
dst	Where this dotfile needs to be deployed (dotfiles with empty dst are ignored and considered installed, can use variables, make sure to quote)
src	Dotfile path within the dotpath (dotfiles with empty src are ignored and considered installed, can use variables, make sure to quote)
link	Defines how this dotfile is installed. Possible values: nolink, link, link_children (See Symlinking dotfiles) (defaults to value of link_dotfile_default)
actions	List of action keys that need to be defined in the actions entry below (See actions)
chmod	Defines the file permissions in octal notation to apply during installation (See permissions)
cmpignore	List of patterns to ignore when comparing (enclose in quotes when using wildcards; see ignore patterns)
ignore_missing_in_dotdrop	Ignore missing files in dotdrop when comparing and importing (see Ignore missing)
ignoreempty	If true, an empty template will not be deployed (defaults to the value of ignoreempty)
instignore	List of patterns to ignore when installing (enclose in quotes when using wildcards; see ignore patterns)
template	If false, disable templating for this dotfile (defaults to the value of template_dotfile_default)
trans_read	Transformation key to apply when installing this dotfile (must be defined in the trans_read entry below; see transformations)
trans_write	Transformation key to apply when updating this dotfile (must be defined in the trans_write entry below; see transformations)
upignore	List of patterns to ignore when updating (enclose in quotes when using wildcards; see ignore patterns)
link_children	Replaced by link: link_children
trans	Replaced by trans_read

<dotfile-key-name>:
  dst: <where-this-file-is-deployed>
  src: <filename-within-the-dotpath>
  ## Optional
  link: (nolink|link|link_children)
  ignoreempty: (true|false)
  cmpignore:
    - "<ignore-pattern>"
  upignore:
    - "<ignore-pattern>"
  instignore:
    - "<ignore-pattern>"
  actions:
    - <action-key>
  template: (true|false)
  chmod: '<file-permissions>'
  trans_read: <transformation-key>
  trans_write: <transformation-key>

profiles entry

The profiles entry (mandatory) contains a YAML object with sub-objects for the profiles for the different dotfiles that need to be managed. The entries in the sub-objects are as follows:

Entry	Description
dotfiles	The dotfiles associated with this profile
import	List of paths containing dotfile keys for this profile (absolute path or relative to the config file location; see Import profile dotfiles from file).
include	Include all elements (dotfiles, actions, (dyn)variables, etc) from another profile (See Include dotfiles from another profile)
variables	Profile-specific variables (See Variables)
dynvariables	Profile-specific interpreted variables (See Interpreted variables)
actions	List of action keys that need to be defined in the actions entry below (See actions)

<some-profile-name-usually-the-hostname>:
  dotfiles:
  - <some-dotfile-key-name-defined-above>
  - <some-other-dotfile-key-name>
  - ...
  ## Optional
  include:
  - <some-other-profile>
  - ...
  variables:
    <name>: <value>
  dynvariables:
    <name>: <value>
  actions:
  - <some-action>
  - ...
  import:
  - <some-path>
  - ...

actions entry

The actions entry (optional) contains an actions mapping (See actions).

actions:
  <action-key>: <command-to-execute>

pre actions:

actions:
  pre:
    <action-key>: <command-to-execute>

post actions:

actions:
  post:
    <action-key>: <command-to-execute>

trans_read entry

The trans_read entry (optional) contains a transformations mapping (See transformations).

trans_read:
   <trans-key>: <command-to-execute>

trans_write entry

The trans_write entry (optional) contains a write transformations mapping (See transformations).

trans_write:
   <trans-key>: <command-to-execute>

variables entry

The variables entry (optional) contains a variables mapping (See variables).

variables:
  <variable-name>: <variable-content>

dynvariables entry

The dynvariables entry (optional) contains an interpreted variables mapping (See Interpreted variables).

dynvariables:
  <variable-name>: <shell-oneliner>

uservariables entry

The uservariables entry (optional) contains a collection of variables whose values are queried from the user (See User variables).

uservariables:
  <variable-name>: <prompt>