mirror of
https://github.com/deadc0de6/dotdrop.git
synced 2026-02-08 21:54:16 +00:00
adding mkdocs
This commit is contained in:
deadc0de6
581
docs/config/config.md
Normal file
581
docs/config/config.md
Normal file
@@ -0,0 +1,581 @@
|
||||
# Config
|
||||
|
||||
The config file used by dotdrop is
|
||||
[config.yaml](https://github.com/deadc0de6/dotdrop/blob/master/config.yaml).
|
||||
|
||||
* [Location](#location)
|
||||
* [Format](#format)
|
||||
* [Actions](#actions)
|
||||
* [Transformations](#transformations)
|
||||
* [Variables](#variables)
|
||||
* [Interpreted variables](#interpreted-variables)
|
||||
* Config details on
|
||||
* [Symlinking dotfiles](#symlinking-dotfiles)
|
||||
* [All dotfiles for a profile](#all-dotfiles-for-a-profile)
|
||||
* [Include dotfiles from another profile](#include-dotfiles-from-another-profile)
|
||||
* [Import profile dotfiles from file](#import-profile-dotfiles-from-file)
|
||||
* [Import variables from file](#import-variables-from-file)
|
||||
* [Import actions from file](#import-actions-from-file)
|
||||
* [Import config files](#import-config-files)
|
||||
* Dynamic elements
|
||||
* [Dynamic dotfile paths](#dynamic-dotfile-paths)
|
||||
* [Dynamic actions](#dynamic-actions)
|
||||
* [Dynamic transformations](#dynamic-transformations)
|
||||
|
||||
---
|
||||
|
||||
# Location
|
||||
|
||||
Unless specified dotdrop will look in following places for the config file (`config.yaml`)
|
||||
and use the first one found
|
||||
|
||||
* current/working directory or the directory where [dotdrop.sh](https://github.com/deadc0de6/dotdrop/blob/master/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.
|
||||
|
||||
# Format
|
||||
|
||||
Dotdrop config file uses [yaml](https://yaml.org/) syntax.
|
||||
|
||||
Content Format:
|
||||
|
||||
* **config** entry (mandatory): contains settings for the deployment
|
||||
* `backup`: create a backup of the dotfile in case it differs from the
|
||||
one that will be installed by dotdrop (default *true*)
|
||||
* `banner`: display the banner (default *true*)
|
||||
* `cmpignore`: list of patterns to ignore when comparing, apply to all dotfiles
|
||||
(enclose in quotes when using wildcards, see [ignore patterns](ignore-pattern))
|
||||
* `create`: create directory hierarchy when installing dotfiles if
|
||||
it doesn't exist (default *true*)
|
||||
* `default_actions`: list of action's keys to execute for all installed dotfile
|
||||
(see [Use actions](usage-actions))
|
||||
* `diff_command`: the diff command to use for diffing files (default `diff -r -u {0} {1}`)
|
||||
* `dotpath`: path to the directory containing the dotfiles to be managed (default `dotfiles`)
|
||||
by dotdrop (absolute path or relative to the config file location)
|
||||
* `filter_file`: list of paths to load templating filters from
|
||||
(see [Templating available filters](templating#available-filters))
|
||||
* `func_file`: list of paths to load templating functions from
|
||||
(see [Templating available methods](templating#available-methods))
|
||||
* `ignoreempty`: do not deploy template if empty (default *false*)
|
||||
* `import_actions`: list of paths to load actions from
|
||||
(absolute path or relative to the config file location,
|
||||
see [Import actions from file](#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-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](#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](ignore-pattern))
|
||||
* `keepdot`: preserve leading dot when importing hidden file in the `dotpath` (default *false*)
|
||||
* `link_dotfile_default`: set dotfile's `link` attribute to this value when undefined.
|
||||
Possible values: *nolink*, *link*, *link_children* (default: *nolink*,
|
||||
see [Symlinking dotfiles](#symlinking-dotfiles))
|
||||
* `link_on_import`: set dotfile's `link` attribute to this value when importing.
|
||||
Possible values: *nolink*, *link*, *link_children* (default: *nolink*,
|
||||
see [Symlinking dotfiles](#symlinking-dotfiles))
|
||||
* `longkey`: use long keys for dotfiles when importing (default *false*,
|
||||
see [Import dotfiles](usage#import-dotfiles))
|
||||
* `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`) (default *false*)
|
||||
* `upignore`: list of patterns to ignore when updating, apply to all dotfiles
|
||||
(enclose in quotes when using wildcards, see [ignore patterns](ignore-pattern))
|
||||
* `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, defaults to *~/.config/dotdrop*)
|
||||
* DEPRECATED `link_by_default`: when importing a dotfile set `link` to that value per default (default *false*)
|
||||
|
||||
* **dotfiles** entry (mandatory): a list of dotfiles
|
||||
* `dst`: where this dotfile needs to be deployed
|
||||
(dotfile with empty `dst` are ignored and considered installed,
|
||||
can use `variables` and `dynvariables`, make sure to quote)
|
||||
* `src`: dotfile path within the `dotpath`
|
||||
(dotfile with empty `src` are ignored and considered installed,
|
||||
can use `variables` and `dynvariables`, make sure to quote)
|
||||
* `link`: define how this dotfile is installed.
|
||||
Possible values: *nolink*, *link*, *link_children* (default: `link_dotfile_default`,
|
||||
see [Symlinking dotfiles](#symlinking-dotfiles))
|
||||
* `actions`: list of action keys that need to be defined in the **actions** entry below
|
||||
(see [Use actions](usage-actions))
|
||||
* `cmpignore`: list of patterns to ignore when comparing (enclose in quotes when using wildcards,
|
||||
see [ignore patterns](ignore-pattern))
|
||||
* `ignoreempty`: if true empty template will not be deployed (defaults to the value of `ignoreempty` above)
|
||||
* `instignore`: list of patterns to ignore when installing (enclose in quotes when using wildcards,
|
||||
see [ignore patterns](ignore-pattern))
|
||||
* `trans_read`: transformation key to apply when installing this dotfile
|
||||
(must be defined in the **trans_read** entry below, see [Use transformations](usage-transformations))
|
||||
* `trans_write`: transformation key to apply when updating this dotfile
|
||||
(must be defined in the **trans_write** entry below, see [Use transformations](usage-transformations))
|
||||
* `upignore`: list of patterns to ignore when updating (enclose in quotes when using wildcards,
|
||||
see [ignore patterns](ignore-pattern))
|
||||
* DEPRECATED `link_children`: replaced by `link: link_children`
|
||||
* DEPRECATED `trans`: replaced by `trans_read`
|
||||
|
||||
```yaml
|
||||
<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>
|
||||
trans_read: <transformation-key>
|
||||
trans_write: <transformation-key>
|
||||
```
|
||||
|
||||
* **profiles** entry (mandatory): a list of profiles with the different dotfiles that
|
||||
need to be managed
|
||||
* `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](#import-profile-dotfiles-from-file)).
|
||||
* `include`: include all elements (dotfiles, actions, (dyn)variables, etc) from another profile
|
||||
(see [Include dotfiles from another profile](#include-dotfiles-from-another-profile))
|
||||
* `variables`: profile specific variables
|
||||
(see [Variables](#variables))
|
||||
* `dynvariables`: profile specific interpreted variables
|
||||
(see [Interpreted variables](#interpreted-variables))
|
||||
* `actions`: list of action keys that need to be defined in the **actions** entry below
|
||||
(see [Use actions](usage-actions))
|
||||
|
||||
```yaml
|
||||
<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 (optional): a list of actions (see [Use actions](usage-actions))
|
||||
|
||||
```yaml
|
||||
actions:
|
||||
<action-key>: <command-to-execute>
|
||||
```
|
||||
|
||||
* **trans_read** entry (optional): a list of transformations (see [Use transformations](usage-transformations))
|
||||
|
||||
```yaml
|
||||
trans_read:
|
||||
<trans-key>: <command-to-execute>
|
||||
```
|
||||
|
||||
* **trans_write** entry (optional): a list of write transformations (see [Use transformations](usage-transformations))
|
||||
|
||||
```yaml
|
||||
trans_write:
|
||||
<trans-key>: <command-to-execute>
|
||||
```
|
||||
|
||||
* **variables** entry (optional): a list of variables (see [Variables](#variables))
|
||||
|
||||
```yaml
|
||||
variables:
|
||||
<variable-name>: <variable-content>
|
||||
```
|
||||
|
||||
* **dynvariables** entry (optional): a list of interpreted variables
|
||||
(see [Interpreted variables](#interpreted-variables))
|
||||
|
||||
```yaml
|
||||
dynvariables:
|
||||
<variable-name>: <shell-oneliner>
|
||||
```
|
||||
|
||||
# Actions
|
||||
|
||||
see [Actions](usage-actions)
|
||||
|
||||
# Transformations
|
||||
|
||||
see [Transformations](usage-transformations)
|
||||
|
||||
# Variables
|
||||
|
||||
see [Variables](config-variables)
|
||||
|
||||
# Interpreted variables
|
||||
|
||||
see [Interpreted variables](config-variables)
|
||||
|
||||
# Symlinking dotfiles
|
||||
|
||||
Dotdrop is able to install dotfiles in three different ways
|
||||
which are controlled by the `link` 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](symlinked-dotfiles)
|
||||
|
||||
# All dotfiles for a profile
|
||||
|
||||
To use all defined dotfiles for a profile, simply use
|
||||
the keyword `ALL`.
|
||||
|
||||
For example:
|
||||
```yaml
|
||||
dotfiles:
|
||||
f_xinitrc:
|
||||
dst: ~/.xinitrc
|
||||
src: xinitrc
|
||||
f_vimrc:
|
||||
dst: ~/.vimrc
|
||||
src: vimrc
|
||||
profiles:
|
||||
host1:
|
||||
dotfiles:
|
||||
- ALL
|
||||
host2:
|
||||
dotfiles:
|
||||
- f_vimrc
|
||||
```
|
||||
|
||||
# Include dotfiles from another profile
|
||||
|
||||
If one profile is using the entire set of another profile, one can use
|
||||
the `include` entry to avoid redundancy.
|
||||
|
||||
Note that everything from the included profile is made available
|
||||
(actions, variables/dynvariables, etc).
|
||||
|
||||
For example:
|
||||
```yaml
|
||||
profiles:
|
||||
host1:
|
||||
dotfiles:
|
||||
- f_xinitrc
|
||||
include:
|
||||
- host2
|
||||
host2:
|
||||
dotfiles:
|
||||
- f_vimrc
|
||||
```
|
||||
Here profile *host1* contains all the dotfiles defined for *host2* plus `f_xinitrc`.
|
||||
|
||||
For more advanced use-cases variables
|
||||
([variables](config-variables) and [dynvariables](config-variables))
|
||||
can be used to specify the profile to include in a profile
|
||||
|
||||
For example:
|
||||
```yaml
|
||||
variables:
|
||||
var1: "john"
|
||||
dynvariables:
|
||||
d_user: "echo $USER"
|
||||
profiles:
|
||||
profile_john:
|
||||
dotfiles:
|
||||
- f_john_dotfile
|
||||
profile_bill:
|
||||
dotfiles:
|
||||
- f_bill_dotfile
|
||||
p1:
|
||||
include:
|
||||
- "profile_{{@@ d_user @@}}"
|
||||
p2:
|
||||
include:
|
||||
- "profile_{{@@ var1 @@}}"
|
||||
```
|
||||
|
||||
# Import profile dotfiles from file
|
||||
|
||||
Profile's dotfiles list can be loaded from external files
|
||||
by specifying their paths in the config entry `import` under the specific profile.
|
||||
|
||||
The paths can be absolute or relative to the config file location.
|
||||
|
||||
`config.yaml`
|
||||
```yaml
|
||||
dotfiles:
|
||||
f_abc:
|
||||
dst: ~/.abc
|
||||
src: abc
|
||||
f_def:
|
||||
dst: ~/.def
|
||||
src: def
|
||||
f_xyz:
|
||||
dst: ~/.xyz
|
||||
src: xyz
|
||||
profiles:
|
||||
p1:
|
||||
dotfiles:
|
||||
- f_abc
|
||||
import:
|
||||
- somedotfiles.yaml
|
||||
```
|
||||
|
||||
`somedotfiles.yaml`
|
||||
```
|
||||
dotfiles:
|
||||
- f_def
|
||||
- f_xyz
|
||||
```
|
||||
|
||||
Variables can be used in `import` and would allow to do something like
|
||||
```yaml
|
||||
import:
|
||||
- profiles.d/{{@@ profile @@}}.yaml
|
||||
```
|
||||
|
||||
# Import variables from file
|
||||
|
||||
It is possible to load variables/dynvariables from external files by providing their
|
||||
paths in the config entry `import_variables`.
|
||||
|
||||
The paths can be absolute or relative to the config file location.
|
||||
|
||||
`config.yaml`
|
||||
```yaml
|
||||
config:
|
||||
backup: true
|
||||
create: true
|
||||
dotpath: dotfiles
|
||||
import_variables:
|
||||
- variables.d/myvars.yaml
|
||||
```
|
||||
|
||||
`variables.d/myvars.yaml`
|
||||
```yaml
|
||||
variables:
|
||||
var1: "extvar1"
|
||||
dynvariables:
|
||||
dvar1: "echo extdvar1"
|
||||
```
|
||||
|
||||
Dotdrop will fail if an imported path points to a non-existing file.
|
||||
It is possible to make non-existing paths not fatal by appending the path with `:optional`
|
||||
```yaml
|
||||
import_variables:
|
||||
- variables.d/myvars.yaml:optional
|
||||
```
|
||||
|
||||
# Import actions from file
|
||||
|
||||
It is possible to load actions from external files by providing their
|
||||
paths in the config entry `import_actions`.
|
||||
|
||||
The paths can be absolute or relative to the config file location.
|
||||
|
||||
`config.yaml`
|
||||
```yaml
|
||||
config:
|
||||
backup: true
|
||||
create: true
|
||||
dotpath: dotfiles
|
||||
import_actions:
|
||||
- actions.d/myactions.yaml
|
||||
dotfiles:
|
||||
f_abc:
|
||||
dst: ~/.abc
|
||||
src: abc
|
||||
actions:
|
||||
- dateme
|
||||
```
|
||||
|
||||
`actions.d/myactions.yaml`
|
||||
```yaml
|
||||
actions:
|
||||
dateme: date > /tmp/timestamp
|
||||
```
|
||||
|
||||
External variables will take precedence over variables defined within
|
||||
the source config file.
|
||||
|
||||
Dotdrop will fail if an imported path points to a non-existing file.
|
||||
It is possible to make non-existing paths not fatal by appending the path with `:optional`
|
||||
```yaml
|
||||
import_actions:
|
||||
- actions.d/myactions.yaml:optional
|
||||
```
|
||||
|
||||
# Import config files
|
||||
|
||||
Entire config files can be imported. This means making the following available
|
||||
from the imported config file in the original config file:
|
||||
|
||||
- dotfiles
|
||||
- profiles
|
||||
- actions
|
||||
- read/write transformations
|
||||
- variables/dynvariables
|
||||
|
||||
Paths to import can be absolute or relative to the importing config file
|
||||
location.
|
||||
|
||||
`config.yaml`
|
||||
```yaml
|
||||
config:
|
||||
backup: true
|
||||
create: true
|
||||
dotpath: dotfiles
|
||||
import_configs:
|
||||
- other-config.yaml
|
||||
dotfiles:
|
||||
f_abc:
|
||||
dst: ~/.abc
|
||||
src: abc
|
||||
actions:
|
||||
- show
|
||||
profiles:
|
||||
my-host:
|
||||
dotfiles:
|
||||
- f_abc
|
||||
- f_def
|
||||
my-haskell:
|
||||
include:
|
||||
- other-host
|
||||
```
|
||||
|
||||
`other-config.yaml`
|
||||
```yaml
|
||||
config:
|
||||
backup: true
|
||||
create: true
|
||||
dotpath: dotfiles-other
|
||||
import_actions:
|
||||
- actions.yaml
|
||||
dotfiles:
|
||||
f_def:
|
||||
dst: ~/.def
|
||||
src: def
|
||||
f_ghci:
|
||||
dst: ~/.ghci
|
||||
src: ghci
|
||||
profiles:
|
||||
other-host:
|
||||
dotfiles:
|
||||
- f_gchi
|
||||
```
|
||||
|
||||
`actions.yaml`
|
||||
```yaml
|
||||
actions:
|
||||
post:
|
||||
show: less
|
||||
```
|
||||
|
||||
In this example `config.yaml` imports `other-config.yaml`. The dotfile `f_def`
|
||||
used in the profile `my-host` is defined in `other-config.yaml`, and so is the
|
||||
profile `other-host` included from `my-haskell`. The action `show` is defined
|
||||
in `actions.yaml`, which is in turn imported by `other-config.yaml`.
|
||||
|
||||
Dotdrop will fail if an imported path points to a non-existing file.
|
||||
It is possible to make non-existing paths not fatal by appending the path with `:optional`
|
||||
```yaml
|
||||
import_configs:
|
||||
- other-config.yaml:optional
|
||||
```
|
||||
|
||||
# Dynamic dotfile paths
|
||||
|
||||
Dotfile source (`src`) and destination (`dst`) can be dynamically constructed using
|
||||
defined variables ([variables and dynvariables](config-variables)).
|
||||
|
||||
For example to have a dotfile deployed on the unique firefox profile where the
|
||||
profile path is dynamically found using a shell oneliner stored in a dynvariable:
|
||||
```yaml
|
||||
dynvariables:
|
||||
mozpath: find ~/.mozilla/firefox -name '*.default'
|
||||
dotfiles:
|
||||
f_somefile:
|
||||
dst: "{{@@ mozpath @@}}/somefile"
|
||||
src: firefox/somefile
|
||||
profiles:
|
||||
home:
|
||||
dotfiles:
|
||||
- f_somefile
|
||||
```
|
||||
|
||||
Make sure to quote the path in the config file.
|
||||
|
||||
# Dynamic actions
|
||||
|
||||
Variables ([config variables and dynvariables](config-variables)
|
||||
and [template variables](templating#template-variables)) can be used
|
||||
in actions for more advanced use-cases.
|
||||
|
||||
```yaml
|
||||
dotfiles:
|
||||
f_test:
|
||||
dst: ~/.test
|
||||
src: test
|
||||
actions:
|
||||
- cookie_mv_somewhere "/tmp/moved-cookie"
|
||||
variables:
|
||||
cookie_dir_available: (test -d /tmp/cookiedir || mkdir -p /tmp/cookiedir)
|
||||
cookie_header: "{{@@ cookie_dir_available @@}} && echo 'header' > /tmp/cookiedir/cookie"
|
||||
cookie_mv: "{{@@ cookie_header @@}} && mv /tmp/cookiedir/cookie"
|
||||
actions:
|
||||
cookie_mv_somewhere: "{{@@ cookie_mv @@}} {0}"
|
||||
```
|
||||
|
||||
or even something like this:
|
||||
```yaml
|
||||
actions:
|
||||
log: "echo {0} >> {1}"
|
||||
config:
|
||||
default_actions:
|
||||
- preaction '{{@@ _dotfile_key @@}} installed' "/tmp/log"
|
||||
...
|
||||
```
|
||||
|
||||
Make sure to quote the actions using variables.
|
||||
|
||||
# Dynamic transformations
|
||||
|
||||
As for [dynamic actions](#dynamic-actions), transformations support
|
||||
the use of variables ([variables and dynvariables](config-variables)
|
||||
and [template variables](templating#template-variables)).
|
||||
|
||||
A very dumb example:
|
||||
```yaml
|
||||
trans_read:
|
||||
r_echo_abs_src: echo "{0}: {{@@ _dotfile_abs_src @@}}" > {1}
|
||||
r_echo_var: echo "{0}: {{@@ r_var @@}}" > {1}
|
||||
trans_write:
|
||||
w_echo_key: echo "{0}: {{@@ _dotfile_key @@}}" > {1}
|
||||
w_echo_var: echo "{0}: {{@@ w_var @@}}" > {1}
|
||||
variables:
|
||||
r_var: readvar
|
||||
w_var: writevar
|
||||
dotfiles:
|
||||
f_abc:
|
||||
dst: ${tmpd}/abc
|
||||
src: abc
|
||||
trans_read: r_echo_abs_src
|
||||
trans_write: w_echo_key
|
||||
f_def:
|
||||
dst: ${tmpd}/def
|
||||
src: def
|
||||
trans_read: r_echo_var
|
||||
trans_write: w_echo_var
|
||||
```
|
||||
Reference in New Issue
Block a user