1
0
mirror of https://github.com/deadc0de6/dotdrop.git synced 2026-02-09 07:09:18 +00:00

doc update doc

This commit is contained in:
deadc0de6
2020-09-13 22:01:46 +02:00
parent d4051a4942
commit b024891af1
19 changed files with 990 additions and 1018 deletions

View File

@@ -1,5 +1,5 @@
Here are the completion files for `bash`, `zsh` and `fish`. Here are completion files for `bash`, `zsh` and `fish`
for the use of dotdrop either through the bash script `dotdrop.sh` for the use of dotdrop through the bash script `dotdrop.sh`
or through the python script `dotdrop` (pypi, snap, setup.py, etc). or through the python script `dotdrop` (pypi, snap, setup.py, etc).
`bash` and `zsh` scripts are generated using `bash` and `zsh` scripts are generated using

View File

@@ -1,18 +1,21 @@
# Dotdrop documentation # Dotdrop documentation
[Dotdrop](https://deadc0de.re/dotdrop/) is a dotfiles manager that provides efficient ways of managing your dotfiles. [Dotdrop](https://deadc0de.re/dotdrop/) is a dotfiles manager that provides efficient ways of managing your dotfiles.
It is especially powerful when it comes to managing those across different hosts.. It is especially powerful when it comes to managing those across different hosts.
The idea of dotdrop is to have the ability to store each dotfile only once and deploy them with a different content on different hosts/setups. The idea of dotdrop is to have the ability to store each dotfile only once and deploy them with a different
content on different hosts/setups.
To achieve this, it uses [jinja2](http://jinja.pocoo.org/) which is a templating engine that allows to specify To achieve this, it uses [jinja2](http://jinja.pocoo.org/) which is a templating engine that allows to specify
during the dotfile installation how (with what content) each dotfile will be installed based on a selected profile. during the dotfile installation how (with what content) each dotfile will be installed based on a selected profile.
Most information on using dotdrop are described in this wiki and in the [readme](https://github.com/deadc0de6/dotdrop/blob/master/README.md). Most information on using dotdrop are described in this documentation
and in the [readme](https://github.com/deadc0de6/dotdrop/blob/master/README.md).
For more check For more check
* [a quick overview of dotdrop features](https://deadc0de.re/dotdrop/) * [a quick overview of dotdrop features](https://deadc0de.re/dotdrop/)
* [the blogpost on dotdrop](https://deadc0de.re/articles/dotfiles.html) * [the blogpost on dotdrop](https://deadc0de.re/articles/dotfiles.html)
* [an example](https://github.com/deadc0de6/dotdrop#getting-started) * [an example](https://github.com/deadc0de6/dotdrop#getting-started)
* [how people are using dotdrop](meta/people-using-dotdrop.md) * [how people are using dotdrop](misc/people-using-dotdrop.md)
For more examples of config file, [search github](https://github.com/search?q=filename%3Aconfig.yaml+dotdrop&type=Code). For more examples of config file, [search github](https://github.com/search?q=filename%3Aconfig.yaml+dotdrop&type=Code).

934
docs/config.md Normal file
View File

@@ -0,0 +1,934 @@
# Config
The config file used by dotdrop is
[config.yaml](https://github.com/deadc0de6/dotdrop/blob/master/config.yaml).
## 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.
### config entry
The **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-patterns))
* `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](#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.md#available-filters))
* `func_file`: list of paths to load templating functions from
(see [Templating available methods](templating.md#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-patterns))
* `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.md#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-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, defaults to *~/.config/dotdrop*)
* *DEPRECATED* `link_by_default`: when importing a dotfile set `link` to that value per default (default *false*)
### dotfiles entry
The **dotfiles** entry (mandatory) contains a list of dotfiles managed by dotdrop
* `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](#actions))
* `cmpignore`: list of patterns to ignore when comparing (enclose in quotes when using wildcards,
see [ignore patterns](#ignore-patterns))
* `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-patterns))
* `trans_read`: transformation key to apply when installing this dotfile
(must be defined in the **trans_read** entry below, see [Use transformations](#transformations))
* `trans_write`: transformation key to apply when updating this dotfile
(must be defined in the **trans_write** entry below, see [Use transformations](#transformations))
* `upignore`: list of patterns to ignore when updating (enclose in quotes when using wildcards,
see [ignore patterns](#ignore-patterns))
* *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
The **profiles** entry (mandatory) contains 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](#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
The **actions** entry (optional) contains a list of actions (see [actions](#actions))
```yaml
actions:
<action-key>: <command-to-execute>
```
### trans_read entry
The **trans_read** entry (optional) contains a list of transformations (see [transformations](#transformations))
```yaml
trans_read:
<trans-key>: <command-to-execute>
```
### trans_write entry
The **trans_write** entry (optional) contains a list of write transformations (see [transformations](#transformations))
```yaml
trans_write:
<trans-key>: <command-to-execute>
```
### variables entry
The **variables** entry (optional) contains a list of variables (see [variables](#variables))
```yaml
variables:
<variable-name>: <variable-content>
```
### dynvariables entry
The **dynvariables** entry (optional) contains a list of interpreted variables
(see [Interpreted variables](#interpreted-variables))
```yaml
dynvariables:
<variable-name>: <shell-oneliner>
```
## Actions
**Note**: any action with a key starting with an underscore (`_`) won't be shown in output.
This can be useful when working with sensitive data containing passwords for example.
### Dotfile actions
It is sometimes useful to execute some kind of action
when deploying a dotfile.
Note that dotfile actions are only
executed when the dotfile is installed.
For example let's consider
[Vundle](https://github.com/VundleVim/Vundle.vim) is used
to manage vim's plugins, the following action could
be set to update and install the plugins when `vimrc` is
deployed:
```yaml
actions:
vundle: vim +VundleClean! +VundleInstall +VundleInstall! +qall
config:
backup: true
create: true
dotpath: dotfiles
dotfiles:
f_vimrc:
dst: ~/.vimrc
src: vimrc
actions:
- vundle
profiles:
home:
dotfiles:
- f_vimrc
```
Thus when `f_vimrc` is installed, the command
`vim +VundleClean! +VundleInstall +VundleInstall! +qall` will
be executed.
Sometimes, you may even want to execute some action prior to deploying a dotfile.
Let's take another example with
[vim-plug](https://github.com/junegunn/vim-plug):
```yaml
actions:
pre:
vim-plug-install: test -e ~/.vim/autoload/plug.vim || (mkdir -p ~/.vim/autoload; curl
-fLo ~/.vim/autoload/plug.vim https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim)
vim-plug: vim +PlugInstall +qall
config:
backup: true
create: true
dotpath: dotfiles
dotfiles:
f_vimrc:
dst: ~/.vimrc
src: vimrc
actions:
- vim-plug-install
- vim-plug
profiles:
home:
dotfiles:
- f_vimrc
```
This way, we make sure [vim-plug](https://github.com/junegunn/vim-plug)
is installed prior to deploying the `~/.vimrc` dotfile.
You can also define `post` actions like this:
```yaml
actions:
post:
some-action: echo "Hello, World!" >/tmp/log
```
If you don't specify neither `post` nor `pre`, the action will be executed
after the dotfile deployment (which is equivalent to `post`).
Actions cannot obviously be named `pre` or `post`.
Actions can even be parameterized. For example:
```yaml
actions:
echoaction: echo '{0}' > {1}
config:
backup: true
create: true
dotpath: dotfiles
dotfiles:
f_vimrc:
dst: ~/.vimrc
src: vimrc
actions:
- echoaction "vim installed" /tmp/mydotdrop.log
f_xinitrc:
dst: ~/.xinitrc
src: xinitrc
actions:
- echoaction "xinitrc installed" /tmp/myotherlog.log
profiles:
home:
dotfiles:
- f_vimrc
- f_xinitrc
```
The above will execute `echo 'vim installed' > /tmp/mydotdrop.log` when
vimrc is installed and `echo 'xinitrc installed' > /tmp/myotherlog.log'`
when xinitrc is installed.
### Default actions
Dotdrop allows to execute an action for any dotfile installation. These actions work as any other action (*pre* or *post*).
For example, the below action will log each dotfile installation to a file.
```yaml
actions:
post:
loginstall: "echo {{@@ _dotfile_abs_src @@}} installed to {{@@ _dotfile_abs_dst @@}} >> {0}"
config:
backup: true
create: true
dotpath: dotfiles
default_actions:
- loginstall "/tmp/dotdrop-installation.log"
dotfiles:
f_vimrc:
dst: ~/.vimrc
src: vimrc
profiles:
hostname:
dotfiles:
- f_vimrc
```
### Profile actions
Profile can be either `pre` or `post` actions. Those are executed before
any dotfile installation (for `pre`) and after all dotfiles installation (for `post`)
only if at least one dotfile has been installed.
### Fake dotfile and actions
*Fake* dotfile can be created by specifying no `dst` and no `src` (see [config format](#format)).
By binding an action to such a *fake* dotfile, you make sure the action is always executed since
*fake* dotfile are always considered installed.
```yaml
actions:
always_action: 'date > ~/.dotdrop.log'
dotfiles:
fake:
src:
dst:
actions:
- always_action
```
## Transformations
For examples of transformation uses, see
* [Store compressed directories](howto/store-compressed-directories.md)
* [Sensitive dotfiles](howto/sensitive-dotfiles.md)
**Note**: any transformation with a key starting with an underscore (`_`) won't be shown in output.
This can be useful when working with sensitive data containing passwords for example.
There are two types of transformations available:
* **read transformations**: used to transform dotfiles before they are installed ([format](#format) key `trans_read`)
* Used for commands `install` and `compare`
* They have two arguments:
* **{0}** will be replaced with the dotfile to process
* **{1}** will be replaced with a temporary file to store the result of the transformation
* Happens **before** the dotfile is templated with jinja2 (see [templating](templating.md))
* **write transformations**: used to transform files before updating a dotfile ([format](#format) key `trans_write`)
* Used for command `update`
* They have two arguments:
* **{0}** will be replaced with the file path to update the dotfile with
* **{1}** will be replaced with a temporary file to store the result of the transformation
A typical use-case for transformations is when dotfiles need to be
stored encrypted or compressed. For more see below [the howto](howto/README.md).
Note that transformations cannot be used if the dotfiles is to be linked (when `link: link` or `link: link_children`).
Transformations also support additional positional arguments that must start from 2 (since `{0}` and `{1}` are added automatically). The transformations itself as well as its arguments can also be templated.
For example
```yaml
trans_read:
targ: echo "$(basename {0}); {{@@ _dotfile_key @@}}; {2}; {3}" > {1}
dotfiles:
f_abc:
dst: /tmp/abc
src: abc
trans_read: targ "{{@@ profile @@}}" lastarg
profiles:
p1:
dotfiles:
- f_abc
```
will result in `abc; f_abc; p1; lastarg`
## Variables
Multiple variables can be used within the config file to
parametrize following elements of the config:
* dotfiles `src` and `dst` paths (see [Dynamic dotfile paths](#dynamic-dotfile-paths))
* external path specifications
* `import_variables`
* `import_actions`
* `import_configs`
* profiles's `import`
`actions` and `transformations` also support the use of variables
but those are resolved when the action/transformation is executed
(see [Dynamic actions](#dynamic-actions),
[Dynamic transformations](#dynamic-transformations) and [Templating](templating.md)).
Following variables are available in the config files:
* [variables defined in the config](#variables)
* [interpreted variables defined in the config](#interpreted-variables)
* [profile variables defined in the config](#profile-variables)
* environment variables: `{{@@ env['MY_VAR'] @@}}`
* dotdrop header: `{{@@ header() @@}}` (see [Dotdrop header](templating.md#dotdrop-header))
As well as all template methods (see [Available methods](templating.md#available-methods))
### config variables
Variables defined in the `variables` entry are made available within the config file.
Config variables are recursively evaluated what means that
a config like the below
```yaml
variables:
var1: "var1"
var2: "{{@@ var1 @@}} var2"
var3: "{{@@ var2 @@}} var3"
var4: "{{@@ dvar4 @@}}"
dynvariables:
dvar1: "echo dvar1"
dvar2: "{{@@ dvar1 @@}} dvar2"
dvar3: "{{@@ dvar2 @@}} dvar3"
dvar4: "echo {{@@ var3 @@}}"
```
will result in the following available variables:
* var1: `var1`
* var2: `var1 var2`
* var3: `var1 var2 var3`
* var4: `echo var1 var2 var3`
* dvar1: `dvar1`
* dvar2: `dvar1 dvar2`
* dvar3: `dvar1 dvar2 dvar3`
* dvar4: `var1 var2 var3`
### Profile variables
Profile variables will take precedence over globally defined variables.
This means that you could do something like this:
```yaml
variables:
git_email: home@email.com
dotfiles:
f_gitconfig:
dst: ~/.gitconfig
src: gitconfig
profiles:
work:
dotfiles:
- f_gitconfig
variables:
git_email: work@email.com
private:
dotfiles:
- f_gitconfig
```
### Interpreted variables
It is also possible to have *dynamic* variables in the sense that their
content will be interpreted by the shell before being substituted.
These need to be defined in the config file under the entry `dynvariables`.
For example:
```yaml
dynvariables:
dvar1: head -1 /proc/meminfo
dvar2: "echo 'this is some test' | rev | tr ' ' ','"
dvar3: /tmp/my_shell_script.sh
user: "echo $USER"
config_file: test -f "{{@@ user_config @@}}" && echo "{{@@ user_config @@}}" || echo "{{@@ dfl_config @@}}"
variables:
user_config: "profile_{{@@ user @@}}_uid.yaml"
dfl_config: "profile_default.yaml"
```
They have the same properties as [Variables](#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](howto/symlinked-dotfiles.md)
## 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](#variables) and [dynvariables](#interpreted-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](#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](#variables)
and [template variables](templating.md#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](#variables)
and [template variables](templating.md#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
```
## Ignore patterns
It is possible to ignore specific patterns when using dotdrop. For example for `compare` when temporary
files don't need to appear in the output.
* for [install](usage.md#install-dotfiles)
* using `instignore` in the config file
* for [compare](usage.md#compare-dotfiles)
* using `cmpignore` in the config file
* using the command line switch `-i --ignore`
* for [update](usage.md#update-dotfiles)
* 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 those when using wildcards in the config file.
Patterns used on a specific dotfile can be specified relative to the dotfile destination (`dst`).
```yaml
config:
cmpignore:
- '*/README.md'
upignore:
- '*/README.md'
instignore:
- '*/README.md'
...
dotfiles:
d_vim
dst: ~/.vim
src: vim
upignore:
- "*/undo-dir"
- "*/plugged"
...
```
examples
To completely ignore comparison of a specific dotfile:
```yaml
dotfiles:
d_vim
dst: ~/.vim
src: vim
cmpignore:
- "*"
```
To ignore specific directory when updating
```yaml
dotfiles:
d_colorpicker:
src: config/some_directory
dst: ~/.config/some_directory
upignore:
- '*sub_directory_to_ignore'
```

View File

@@ -1,126 +0,0 @@
# Config variables
* [Config available variables](#available-variables)
* [Variables entry](#variables-entry)
* [Profile variables](#profile-variables)
* [Config variables in templates](#config-variables-in-templates)
* [Interpreted variables entry](#interpreted-variables-entry)
---
# Available variables
Multiple variables can be used within the config file to
parametrize following elements of the config:
* dotfiles `src` and `dst` paths (see [Dynamic dotfile paths](config.md#dynamic-dotfile-paths))
* external path specifications
* `import_variables`
* `import_actions`
* `import_configs`
* profiles's `import`
`actions` and `transformations` also support the use of variables
but those are resolved when the action/transformation is executed
(see [Dynamic actions](config.md#dynamic-actions),
[Dynamic transformations](config.md#dynamic-transformations) and [Templating](../template/templating.md)).
Following variables are available in the config files:
* [variables defined in the config](#variables-entry)
* [interpreted variables defined in the config](#interpreted-variables-entry)
* [profile variables defined in the config](#profile-variables)
* environment variables: `{{@@ env['MY_VAR'] @@}}`
* dotdrop header: `{{@@ header() @@}}` (see [Dotdrop header](../template/templating.md#dotdrop-header))
As well as all template methods (see [Available methods](../template/templating.md#available-methods))
# Variables entry
Variables defined in the `variables` entry are made available within the config file.
Config variables are recursively evaluated what means that
a config like the below
```yaml
variables:
var1: "var1"
var2: "{{@@ var1 @@}} var2"
var3: "{{@@ var2 @@}} var3"
var4: "{{@@ dvar4 @@}}"
dynvariables:
dvar1: "echo dvar1"
dvar2: "{{@@ dvar1 @@}} dvar2"
dvar3: "{{@@ dvar2 @@}} dvar3"
dvar4: "echo {{@@ var3 @@}}"
```
will result in the following available variables:
* var1: `var1`
* var2: `var1 var2`
* var3: `var1 var2 var3`
* var4: `echo var1 var2 var3`
* dvar1: `dvar1`
* dvar2: `dvar1 dvar2`
* dvar3: `dvar1 dvar2 dvar3`
* dvar4: `var1 var2 var3`
# Profile variables
Profile variables will take precedence over globally defined variables.
This means that you could do something like this:
```yaml
variables:
git_email: home@email.com
dotfiles:
f_gitconfig:
dst: ~/.gitconfig
src: gitconfig
profiles:
work:
dotfiles:
- f_gitconfig
variables:
git_email: work@email.com
private:
dotfiles:
- f_gitconfig
```
# Config variables in templates
`variables` and `dynvariables` are also made available in templates
(see [Template variables](../template/templating.md#template-variables)).
Variables in the config file
```yaml
variables:
var1: some variable content
var2: some other content
```
Can be used in any templates like this
```
var1 value is: {{@@ var1 @@}}
```
# Interpreted variables entry
It is also possible to have *dynamic* variables in the sense that their
content will be interpreted by the shell before being substituted.
These need to be defined in the config file under the entry `dynvariables`.
For example:
```yaml
dynvariables:
dvar1: head -1 /proc/meminfo
dvar2: "echo 'this is some test' | rev | tr ' ' ','"
dvar3: /tmp/my_shell_script.sh
user: "echo $USER"
config_file: test -f "{{@@ user_config @@}}" && echo "{{@@ user_config @@}}" || echo "{{@@ dfl_config @@}}"
variables:
user_config: "profile_{{@@ user @@}}_uid.yaml"
dfl_config: "profile_default.yaml"
```
They have the same properties as [Variables](#variables-entry).

View File

@@ -1,560 +0,0 @@
# Config
The config file used by dotdrop is
[config.yaml](https://github.com/deadc0de6/dotdrop/blob/master/config.yaml).
## 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.md))
* `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.md))
* `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](../template/templating.md#available-filters))
* `func_file`: list of paths to load templating functions from
(see [Templating available methods](../template/templating.md#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.md))
* `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.md#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.md))
* `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.md))
* `cmpignore`: list of patterns to ignore when comparing (enclose in quotes when using wildcards,
see [ignore patterns](ignore-pattern.md))
* `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.md))
* `trans_read`: transformation key to apply when installing this dotfile
(must be defined in the **trans_read** entry below, see [Use transformations](usage-transformations.md))
* `trans_write`: transformation key to apply when updating this dotfile
(must be defined in the **trans_write** entry below, see [Use transformations](usage-transformations.md))
* `upignore`: list of patterns to ignore when updating (enclose in quotes when using wildcards,
see [ignore patterns](ignore-pattern.md))
* 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.md))
```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.md))
```yaml
actions:
<action-key>: <command-to-execute>
```
* **trans_read** entry (optional): a list of transformations (see [Use transformations](usage-transformations.md))
```yaml
trans_read:
<trans-key>: <command-to-execute>
```
* **trans_write** entry (optional): a list of write transformations (see [Use transformations](usage-transformations.md))
```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.md)
## Transformations
see [Transformations](usage-transformations.md)
## Variables
see [Variables](config-variables.md)
## Interpreted variables
see [Interpreted variables](config-variables.md)
## 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](../howto/symlinked-dotfiles.md)
## 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.md) and [dynvariables](config-variables.md))
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.md)).
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.md)
and [template variables](../template/templating.md#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.md)
and [template variables](../template/templating.md#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
```

View File

@@ -1,59 +0,0 @@
# Ignore patterns
It is possible to ignore specific patterns when using dotdrop. For example for `compare` when temporary
files don't need to appear in the output.
* for [install](../usage.md#install-dotfiles)
* using `instignore` in [the config file](config.md)
* for [compare](../usage.md#compare-dotfiles)
* using `cmpignore` in [the config file](config.md)
* using the command line switch `-i --ignore`
* for [update](../usage.md#update-dotfiles)
* using `upignore` in [the config file](config.md)
* 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 those when using wildcards in the config file.
Patterns used on a specific dotfile can be specified relative to the dotfile destination (`dst`).
```yaml
config:
cmpignore:
- '*/README.md'
upignore:
- '*/README.md'
instignore:
- '*/README.md'
...
dotfiles:
d_vim
dst: ~/.vim
src: vim
upignore:
- "*/undo-dir"
- "*/plugged"
...
```
## examples
To completely ignore comparison of a specific dotfile:
```yaml
dotfiles:
d_vim
dst: ~/.vim
src: vim
cmpignore:
- "*"
```
To ignore specific directory when updating
```yaml
dotfiles:
d_colorpicker:
src: config/some_directory
dst: ~/.config/some_directory
upignore:
- '*sub_directory_to_ignore'
```

View File

@@ -1,165 +0,0 @@
* [Dotfile actions](#dotfile-actions)
* [Default actions](#default-actions)
* [Profile actions](#profile-actions)
* [Fake dotfile and actions](#fake-dotfile-and-actions)
---
**Note**: any action with a key starting with an underscore (`_`) won't be shown in output.
This can be useful when working with sensitive data containing passwords for example.
# Dotfile actions
It is sometimes useful to execute some kind of action
when deploying a dotfile.
Note that dotfile actions are only
executed when the dotfile is installed.
For example let's consider
[Vundle](https://github.com/VundleVim/Vundle.vim) is used
to manage vim's plugins, the following action could
be set to update and install the plugins when `vimrc` is
deployed:
```yaml
actions:
vundle: vim +VundleClean! +VundleInstall +VundleInstall! +qall
config:
backup: true
create: true
dotpath: dotfiles
dotfiles:
f_vimrc:
dst: ~/.vimrc
src: vimrc
actions:
- vundle
profiles:
home:
dotfiles:
- f_vimrc
```
Thus when `f_vimrc` is installed, the command
`vim +VundleClean! +VundleInstall +VundleInstall! +qall` will
be executed.
Sometimes, you may even want to execute some action prior to deploying a dotfile.
Let's take another example with
[vim-plug](https://github.com/junegunn/vim-plug):
```yaml
actions:
pre:
vim-plug-install: test -e ~/.vim/autoload/plug.vim || (mkdir -p ~/.vim/autoload; curl
-fLo ~/.vim/autoload/plug.vim https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim)
vim-plug: vim +PlugInstall +qall
config:
backup: true
create: true
dotpath: dotfiles
dotfiles:
f_vimrc:
dst: ~/.vimrc
src: vimrc
actions:
- vim-plug-install
- vim-plug
profiles:
home:
dotfiles:
- f_vimrc
```
This way, we make sure [vim-plug](https://github.com/junegunn/vim-plug)
is installed prior to deploying the `~/.vimrc` dotfile.
You can also define `post` actions like this:
```yaml
actions:
post:
some-action: echo "Hello, World!" >/tmp/log
```
If you don't specify neither `post` nor `pre`, the action will be executed
after the dotfile deployment (which is equivalent to `post`).
Actions cannot obviously be named `pre` or `post`.
Actions can even be parameterized. For example:
```yaml
actions:
echoaction: echo '{0}' > {1}
config:
backup: true
create: true
dotpath: dotfiles
dotfiles:
f_vimrc:
dst: ~/.vimrc
src: vimrc
actions:
- echoaction "vim installed" /tmp/mydotdrop.log
f_xinitrc:
dst: ~/.xinitrc
src: xinitrc
actions:
- echoaction "xinitrc installed" /tmp/myotherlog.log
profiles:
home:
dotfiles:
- f_vimrc
- f_xinitrc
```
The above will execute `echo 'vim installed' > /tmp/mydotdrop.log` when
vimrc is installed and `echo 'xinitrc installed' > /tmp/myotherlog.log'`
when xinitrc is installed.
# Default actions
Dotdrop allows to execute an action for any dotfile installation. These actions work as any other action (*pre* or *post*).
For example, the below action will log each dotfile installation to a file.
```yaml
actions:
post:
loginstall: "echo {{@@ _dotfile_abs_src @@}} installed to {{@@ _dotfile_abs_dst @@}} >> {0}"
config:
backup: true
create: true
dotpath: dotfiles
default_actions:
- loginstall "/tmp/dotdrop-installation.log"
dotfiles:
f_vimrc:
dst: ~/.vimrc
src: vimrc
profiles:
hostname:
dotfiles:
- f_vimrc
```
# Profile actions
Profile can be either `pre` or `post` actions. Those are executed before
any dotfile installation (for `pre`) and after all dotfiles installation (for `post`)
only if at least one dotfile has been installed.
# Fake dotfile and actions
*Fake* dotfile can be created by specifying no `dst` and no `src` (see [config format](https://github.com/deadc0de6/dotdrop/wiki/config#format)). By binding an action to such a *fake* dotfile, you make sure the action is always executed since *fake* dotfile are always considered installed.
```yaml
actions:
always_action: 'date > ~/.dotdrop.log'
dotfiles:
fake:
src:
dst:
actions:
- always_action
```

View File

@@ -1,58 +0,0 @@
* [Use transformations](#use-transformations)
* [Arguments and templating](#arguments-and-templating)
* [Examples](#examples)
---
**Note**: any transformation with a key starting with an underscore (`_`) won't be shown in output.
This can be useful when working with sensitive data containing passwords for example.
# Use transformations
There are two types of transformations available:
* **read transformations**: used to transform dotfiles before they are installed ([Config](config.md) key `trans_read`)
* Used for commands `install` and `compare`
* They have two arguments:
* **{0}** will be replaced with the dotfile to process
* **{1}** will be replaced with a temporary file to store the result of the transformation
* Happens **before** the dotfile is templated with jinja2 (see [templating](../template/templating.md))
* **write transformations**: used to transform files before updating a dotfile ([Config](config.md) key `trans_write`)
* Used for command `update`
* They have two arguments:
* **{0}** will be replaced with the file path to update the dotfile with
* **{1}** will be replaced with a temporary file to store the result of the transformation
A typical use-case for transformations is when dotfiles need to be
stored encrypted or compressed. For more see below [examples](#examples).
Note that transformations cannot be used if the dotfiles is to be linked (when `link: link` or `link: link_children`).
# Arguments and templating
Transformations also support additional positional arguments that must start from 2 (since `{0}` and `{1}` are added automatically). The transformations itself as well as its arguments can also be templated.
For example
```yaml
trans_read:
targ: echo "$(basename {0}); {{@@ _dotfile_key @@}}; {2}; {3}" > {1}
dotfiles:
f_abc:
dst: /tmp/abc
src: abc
trans_read: targ "{{@@ profile @@}}" lastarg
profiles:
p1:
dotfiles:
- f_abc
```
will result in `abc; f_abc; p1; lastarg`
# Examples
See
* [Store compressed directories](../howto/store-compressed-directories.md)
* [Sensitive dotfiles](../howto/sensitive-dotfiles.md)

View File

@@ -2,15 +2,15 @@
## Append to a dotfile ## Append to a dotfile
[Append to a dotfile](howto/append.md) [Append to a dotfile](append.md)
## Create special files ## Create special files
[Create special files](howto/create-special-files.md) [Create special files](create-special-files.md)
## Handle special chars ## Handle special chars
[Handle special chars](howto/special-chars.md) [Handle special chars](special-chars.md)
## Improve git integration ## Improve git integration
@@ -18,20 +18,20 @@
## Merge files on install ## Merge files on install
[Merge files on install](howto/merge-files-when-installing.md) [Merge files on install](merge-files-when-installing.md)
## Share content across dotfiles ## Share content across dotfiles
[Share content across dotfiles](howto/sharing-content.md) [Share content across dotfiles](sharing-content.md)
## Store compressed directories ## Store compressed directories
[Store compressed directories](howto/store-compressed-directories.md) [Store compressed directories](store-compressed-directories.md)
## Store secrets ## Store secrets
[Store secrets](howto/sensitive-dotfiles.md) [Store secrets](sensitive-dotfiles.md)
## Symlink dotfiles ## Symlink dotfiles
[Symlink dotfiles](howto/symlinked-dotfiles.md) [Symlink dotfiles](symlinked-dotfiles.md)

View File

@@ -1,6 +1,6 @@
Sometimes it might be useful to be able to append some text to a Sometimes it might be useful to be able to append some text to a
file. Dotdrop is able to do that with the help of file. Dotdrop is able to do that with the help of
[actions](https://github.com/deadc0de6/dotdrop/wiki/usage-actions) [actions](../config.md#actions).
and a temporary file. and a temporary file.
Below is a config example to append to a file: Below is a config example to append to a file:
@@ -18,7 +18,7 @@ dotfiles:
- append "{{@@ tmpfile @@}}" "{{@@ somefile_final @@}}" - append "{{@@ tmpfile @@}}" "{{@@ somefile_final @@}}"
actions: actions:
pre: pre:
strip: "sed -i '/^# my pattern$/,$d' {0}" strip: "sed -i '/^# my pattern$/,$d' {0}"
post: post:
append: "cat {0} >> {1}; rm -f {0}" append: "cat {0} >> {1}; rm -f {0}"
``` ```
@@ -28,4 +28,4 @@ Obviously the dotfile in the dotpath should start with a unique pattern (here `#
``` ```
# my pattern # my pattern
this is the end this is the end
``` ```

View File

@@ -1,5 +1,5 @@
One way for creating symlinks (or any other special files) is to use a combination of One way for creating symlinks (or any other special files) is to use a combination of
[actions](../config/usage-actions.md) and a *fake* dotfile. [actions](../config.md#actions) and a *fake* dotfile.
Let's say for example you have a list of directories you want to link Let's say for example you have a list of directories you want to link
from under `~/.original` to `~/symlinks`. from under `~/.original` to `~/symlinks`.

View File

@@ -46,12 +46,12 @@ Dotdrop will then automagically include the files into your vimrc when handling
# Merge all files in a directory # Merge all files in a directory
To include all files in a directory, a combination of To include all files in a directory, a combination of
[dynvariables](../config/config-variables.md#interpreted-variables-entry) [dynvariables](../config.md#interpreted-variables)
and [jinja2 directives](http://jinja.pocoo.org/docs/2.10/) have to be used. and [jinja2 directives](http://jinja.pocoo.org/docs/2.10/) have to be used.
Let's say all files in `<dotpath>/toinclude` need to be included into a dotfile. Let's say all files in `<dotpath>/toinclude` need to be included into a dotfile.
First define a [dynvariables](../config/config-variables.md#interpreted-variables-entry) First define a [dynvariables](../config.md#interpreted-variables)
in the config file which will look for files to include in the above directory: in the config file which will look for files to include in the above directory:
```yaml ```yaml
dynvariables: dynvariables:
@@ -59,7 +59,7 @@ dynvariables:
``` ```
Note that `_dotdrop_dotpath` is part of the built-in variables Note that `_dotdrop_dotpath` is part of the built-in variables
(for more see [template variables](../template/templating.md#template-variables)). (for more see [template variables](../templating.md#template-variables)).
And then use the generated list in the dotfile template: And then use the generated list in the dotfile template:
``` ```

View File

@@ -8,7 +8,7 @@
# Available solutions # Available solutions
Two solutions exist, the first one using an unversioned file (see [Environment variables](../template/templating.md#environment-variables)) Two solutions exist, the first one using an unversioned file (see [Environment variables](../templating.md#environment-variables))
and the second using transformations (see [Store encrypted dotfiles](#store-encrypted-dotfiles)). and the second using transformations (see [Store encrypted dotfiles](#store-encrypted-dotfiles)).
# Store encrypted dotfiles # Store encrypted dotfiles

View File

@@ -64,7 +64,7 @@ export DB_PORT='4521'
Albeit flexible, the previous method is a bit cumbersome for some use cases. Albeit flexible, the previous method is a bit cumbersome for some use cases.
For example, when the dotfiles belong to different profiles, the cleanest For example, when the dotfiles belong to different profiles, the cleanest
solution consists in using solution consists in using
[profile variables](../config/config-variables.md#profile-variables). This is achieved by: [profile variables](../config.md#profile-variables). This is achieved by:
1. Creating the merged dotfile with an arbitrary name somewhere in `dotpath`. 1. Creating the merged dotfile with an arbitrary name somewhere in `dotpath`.
2. Adding some variables in the merged dotfile via templating. 2. Adding some variables in the merged dotfile via templating.

View File

@@ -85,10 +85,10 @@ $ tree -L 1 ~/.vim
# Templating symlinked dotfiles # Templating symlinked dotfiles
For dotfiles not using any templating directives, those are directly linked For dotfiles not using any templating directives, those are directly linked
to dotdrop's `dotpath` directory (see [Config](../config/config.md)). to dotdrop's `dotpath` directory (see [Config](../config.md)).
When using templating directives however the dotfiles are first installed into When using templating directives however the dotfiles are first installed into
`workdir` (defaults to *~/.config/dotdrop*, see [Config](../config/config.md)) `workdir` (defaults to *~/.config/dotdrop*, see [Config](../config.md))
and then symlinked there. and then symlinked there.
This applies to both dotfiles with `link: link` and `link: link_children`. This applies to both dotfiles with `link: link` and `link: link_children`.

View File

@@ -70,7 +70,7 @@ Then follow the instructions under [As a submodule](#as-a-submodule).
Install dotdrop Install dotdrop
```bash ```bash
$ pip3 install --user dotdrop $ pip3 install dotdrop --user
``` ```
and then [setup your repository](#setup-your-repository). and then [setup your repository](#setup-your-repository).
@@ -147,7 +147,7 @@ $ git push
Or if installed through pypi: Or if installed through pypi:
```bash ```bash
$ pip3 install --user dotdrop --upgrade $ pip3 install dotdrop --upgrade --user
``` ```
## Setup your repository ## Setup your repository
@@ -173,7 +173,7 @@ $ wget https://raw.githubusercontent.com/deadc0de6/dotdrop/master/config.yaml
``` ```
It is recommended to store your config file directly within your repository It is recommended to store your config file directly within your repository
(*my-dotfiles* in the example above) but you could save it in different places if you wish, (*my-dotfiles* in the example above) but you could save it in different places if you wish,
see [this doc](https://github.com/deadc0de6/dotdrop/wiki/config#location) for more. see [config location](config.md#location) for more.
```bash ```bash
$ tree my-dotfiles $ tree my-dotfiles
@@ -188,9 +188,10 @@ in your preferred shell to call dotdrop with the config file path argument.
alias dotdrop='dotdrop --cfg=<path-to-your-config.yaml>' alias dotdrop='dotdrop --cfg=<path-to-your-config.yaml>'
``` ```
For more info on the config file format, see [the config doc](https://github.com/deadc0de6/dotdrop/wiki/config) For more info on the config file format, see [the config doc](config.md).
Finally start using dotdrop with `dotdrop --help`. See the [usage doc](https://github.com/deadc0de6/dotdrop/wiki/usage) and [the example](https://github.com/deadc0de6/dotdrop/blob/master/README.md#getting-started). Finally start using dotdrop with `dotdrop --help`. See the [usage doc](usage.md)
and [the example](https://github.com/deadc0de6/dotdrop/blob/master/README.md#getting-started).
## Shell completion ## Shell completion

View File

@@ -25,12 +25,12 @@ Following variables are available in templates:
* `{{@@ profile @@}}` contains the profile provided to dotdrop. * `{{@@ profile @@}}` contains the profile provided to dotdrop.
* `{{@@ env['MY_VAR'] @@}}` contains environment variables (see [Environment variables](#environment-variables)). * `{{@@ env['MY_VAR'] @@}}` contains environment variables (see [Environment variables](#environment-variables)).
* `{{@@ header() @@}}` contains dotdrop header (see [Dotdrop header](#dotdrop-header)). * `{{@@ header() @@}}` contains dotdrop header (see [Dotdrop header](#dotdrop-header)).
* `{{@@ _dotdrop_dotpath @@}}` contains the [dotpath](https://github.com/deadc0de6/dotdrop/wiki/config) absolute path. * `{{@@ _dotdrop_dotpath @@}}` contains the [dotpath](config.md) absolute path.
* `{{@@ _dotdrop_cfgpath @@}}` contains the absolute path to the [config file](https://github.com/deadc0de6/dotdrop/wiki/config). * `{{@@ _dotdrop_cfgpath @@}}` contains the absolute path to the [config file](config.md).
* `{{@@ _dotdrop_workdir @@}}` contains the [workdir](https://github.com/deadc0de6/dotdrop/wiki/config) absolute path. * `{{@@ _dotdrop_workdir @@}}` contains the [workdir](config.md) absolute path.
* dotfile specific variables (see [Dotfile variables](#dotfile-variables)) * dotfile specific variables (see [Dotfile variables](#dotfile-variables))
* config variables (see [Variables](../config/config-variables.md)). * config variables (see [Variables](config.md#variables)).
* config interpreted variables (see [Interpreted variables](../config/config-variables.md)). * config interpreted variables (see [Interpreted variables](config.md#interpreted-variables)).
## Dotfile variables ## Dotfile variables
@@ -59,7 +59,7 @@ It's possible to access environment variables inside the templates.
``` ```
This allows for storing host-specific properties and/or secrets in environment variables. This allows for storing host-specific properties and/or secrets in environment variables.
It is recommended to use `variables` (see [Config variables](../config/config-variables.md)) It is recommended to use `variables` (see [config variables](config.md#variables))
instead of environment variables unless these contain sensitive information that instead of environment variables unless these contain sensitive information that
shouldn't be versioned in git. shouldn't be versioned in git.
@@ -201,7 +201,7 @@ It is possible to avoid having an empty rendered template being
deployed by setting the `ignoreempty` entry to *true*. This can be set deployed by setting the `ignoreempty` entry to *true*. This can be set
globally for all dotfiles or only for specific dotfiles. globally for all dotfiles or only for specific dotfiles.
For more see the [Config](../config/config.md). For more see the [Config](config.md).
## Include file or template in template ## Include file or template in template

View File

@@ -13,7 +13,6 @@ Then if you happen to update the file/directory directly on the filesystem (add
For more advanced uses: For more advanced uses:
* See [this wiki](https://github.com/deadc0de6/dotdrop/wiki)
* `dotdrop --help` for more options. * `dotdrop --help` for more options.
* [the example](https://github.com/deadc0de6/dotdrop#getting-started) * [the example](https://github.com/deadc0de6/dotdrop#getting-started)
@@ -24,14 +23,14 @@ Simply run
$ dotdrop install $ dotdrop install
``` ```
options some available options
* `-t --temp`: install the dotfile(s) to a temporary directory for review (it helps to debug templating issues for example). Note that actions are not executed in that mode. * `-t --temp`: install the dotfile(s) to a temporary directory for review (it helps to debug templating issues for example). Note that actions are not executed in that mode.
* `-a --force-actions`: force the execution of actions even if the dotfiles are not installed * `-a --force-actions`: force the execution of actions even if the dotfiles are not installed
For more detail, see the usage with `dotdrop --help` For more detail, see the usage with `dotdrop --help`
To ignore specific pattern during installation see [the dedicated wiki page](config/ignore-pattern.md) To ignore specific pattern during installation see [the ignore patterns](config.md#ignore-patterns)
## Compare dotfiles ## Compare dotfiles
@@ -44,7 +43,7 @@ The diffing is done by `diff` in the backend, one can provide its specific
diff command using the config option `diff_command`. diff command using the config option `diff_command`.
To ignore specific pattern, To ignore specific pattern,
see [the dedicated wiki page](config/ignore-pattern.md) see [the ignore patterns](config.md#ignore-patterns)
It is also possible to install all dotfiles for a specific profile It is also possible to install all dotfiles for a specific profile
in a temporary directory in order to manually compare them with in a temporary directory in order to manually compare them with
@@ -160,11 +159,11 @@ $ dotdrop update --key f_vimrc
If not argument is provided, all dotfiles for the selected profile are updated. If not argument is provided, all dotfiles for the selected profile are updated.
To ignore specific pattern, To ignore specific pattern,
see [the dedicated wiki page](config/ignore-pattern.md) see [the dedicated page](config.md#ignore-patterns)
There are two cases when updating a dotfile: There are two cases when updating a dotfile:
### The dotfile doesn't use [templating](template/templating.md) ### The dotfile doesn't use [templating](templating.md)
The new version of the dotfile is copied to the *dotpath* directory and overwrites The new version of the dotfile is copied to the *dotpath* directory and overwrites
the old version. If git is used to version the dotfiles stored by dotdrop, the git command the old version. If git is used to version the dotfiles stored by dotdrop, the git command
@@ -175,7 +174,7 @@ $ dotdrop update ~/.vimrc
$ git diff $ git diff
``` ```
### The dotfile uses [templating](template/templating.md) ### The dotfile uses [templating](templating.md)
The dotfile must be manually updated, three solutions can be used to identify the The dotfile must be manually updated, three solutions can be used to identify the
changes to apply to the template: changes to apply to the template:

View File

@@ -4,17 +4,20 @@ repo_url: https://github.com/deadc0de6/dotdrop
theme: theme:
name: readthedocs name: readthedocs
highlightjs: true highlightjs: true
hljs_languages:
- yaml
use_directory_urls: true use_directory_urls: true
nav: nav:
- Home: 'README.md' - Home: 'README.md'
- Installation: 'installation.md' - Installation: 'installation.md'
- Usage: 'usage.md' - Usage: 'usage.md'
- Config: 'config/config.md' - Config: 'config.md'
- Template: 'template/templating.md' - Templating: 'templating.md'
- HowTo: 'howto/README.md' - HowTo: 'howto/README.md'
- Contributing: 'contributing.md' - Contributing: 'contributing.md'
markdown_extensions: markdown_extensions:
- toc: - meta
baselevel: 2 - tables
permalink: "#" - fenced_code
- toc