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:
@@ -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
|
||||||
|
|||||||
@@ -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
934
docs/config.md
Normal 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'
|
||||||
|
```
|
||||||
|
|
||||||
@@ -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).
|
|
||||||
@@ -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
|
|
||||||
```
|
|
||||||
@@ -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'
|
|
||||||
```
|
|
||||||
@@ -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
|
|
||||||
```
|
|
||||||
@@ -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)
|
|
||||||
@@ -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)
|
||||||
|
|||||||
@@ -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
|
||||||
```
|
```
|
||||||
|
|||||||
@@ -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`.
|
||||||
|
|||||||
@@ -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:
|
||||||
```
|
```
|
||||||
|
|||||||
@@ -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
|
||||||
|
|||||||
@@ -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.
|
||||||
|
|||||||
@@ -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`.
|
||||||
|
|
||||||
|
|||||||
@@ -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
|
||||||
|
|
||||||
|
|||||||
@@ -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
|
||||||
|
|
||||||
@@ -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:
|
||||||
|
|||||||
13
mkdocs.yml
13
mkdocs.yml
@@ -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
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user