dotdrop/docs/config-format.md

Config format

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
cmpignore	list of patterns to ignore when comparing, apply to all dotfiles (enclose in quotes when using wildcards, see ignore patterns)	-
create	create directory hierarchy when installing dotfiles if it doesn't exist	true
default_actions	list of action's keys to execute for all installed dotfile (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 in the current config (absolute path or relative to the current config file location, see 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)	-
instignore	list of patterns to ignore when installing, apply to all dotfiles (enclose in quotes when using wildcards, see ignore patterns)	-
keepdot	preserve leading dot when importing hidden file in the dotpath	false
link_dotfile_default	set dotfile's link attribute to this value when undefined. Possible values: nolink, link (see Symlinking dotfiles)	nolink
link_on_import	set 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, apply 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 that value per default	false

dotfiles entry

The dotfiles entry (mandatory) contains a list of dotfiles managed by dotdrop

Entry	Description
dst	where this dotfile needs to be deployed (dotfile with empty dst are ignored and considered installed, can use variables, make sure to quote)
src	dotfile path within the dotpath (dotfile with empty src are ignored and considered installed, can use variables, make sure to quote)
link	define 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 empty template will not be deployed (defaults to value of ignoreempty)
instignore	list of patterns to ignore when installing (enclose in quotes when using wildcards, see ignore patterns)
template	if false disable template for this dotfile (defaults to 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 list of profiles with the different dotfiles that need to be managed

Entry	Description
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).
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 a list of actions (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 list of transformations (see transformations)

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

trans_write entry

The trans_write entry (optional) contains a list of write transformations (see transformations)

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

variables entry

The variables entry (optional) contains a list of variables (see variables)

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

dynvariables entry

The dynvariables entry (optional) contains a list of interpreted variables (see Interpreted variables)

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

uservariables entry

The uservariables entry (optional) contains a list of variables to be queried to the user for their values. (see User variables)

uservariables:
  <variable-name>: <prompt>