mirror of
https://github.com/deadc0de6/dotdrop.git
synced 2026-02-04 12:46:44 +00:00
refactor documentation
This commit is contained in:
deadc0de6
deadc0de
@@ -127,7 +127,7 @@ Potential *included* entries:
|
||||
* Profile's *include*
|
||||
|
||||
Variables are then used to resolve different elements in the config file:
|
||||
see [this](docs/config.md#variables).
|
||||
see [this](docs/config-file.md#variables).
|
||||
|
||||
## Rules
|
||||
|
||||
|
||||
@@ -25,7 +25,7 @@
|
||||
It allows you to store your dotfiles in Git and automagically deploy
|
||||
different versions of the same file on different setups.
|
||||
|
||||
It also allows you to manage different *sets* of dotfiles.
|
||||
It also allows to manage different *sets* of dotfiles.
|
||||
For example, you can have a set of dotfiles for your home laptop and
|
||||
a different set for your office desktop. Those sets may overlap, and different
|
||||
versions of the same dotfiles can be deployed using different predefined *profiles*.
|
||||
@@ -68,8 +68,8 @@ A mirror of this repository is available on GitLab under <https://gitlab.com/dea
|
||||
## Why dotdrop?
|
||||
|
||||
There exist many tools to manage dotfiles; however, not
|
||||
many allow you to deploy different versions of the same dotfile
|
||||
on different hosts. Moreover, dotdrop allows you to specify the
|
||||
many allow to deploy different versions of the same dotfile
|
||||
on different hosts. Moreover, dotdrop allows to specify the
|
||||
set of dotfiles that need to be deployed for a specific profile.
|
||||
|
||||
See the [example](#getting-started) for a concrete example of
|
||||
|
||||
@@ -13,8 +13,8 @@ and in the [readme](https://github.com/deadc0de6/dotdrop/blob/master/README.md).
|
||||
For more, check:
|
||||
|
||||
* [A quick overview of dotdrop features](https://deadc0de.re/dotdrop/)
|
||||
* [The walkthrough example](https://github.com/deadc0de6/dotdrop#getting-started)
|
||||
* [The blogpost on dotdrop](https://deadc0de.re/articles/dotfiles.html)
|
||||
* [An example](https://github.com/deadc0de6/dotdrop#getting-started)
|
||||
* [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 config files examples, [search GitHub](https://github.com/search?q=filename%3Aconfig.yaml+dotdrop&type=Code).
|
||||
|
||||
95
docs/config-actions.md
Normal file
95
docs/config-actions.md
Normal file
@@ -0,0 +1,95 @@
|
||||
# Actions entry
|
||||
|
||||
The **actions** entry (optional) contains an actions mapping.
|
||||
|
||||
```yaml
|
||||
actions:
|
||||
<action-key>: <command-to-execute>
|
||||
```
|
||||
|
||||
*pre* actions:
|
||||
```yaml
|
||||
actions:
|
||||
pre:
|
||||
<action-key>: <command-to-execute>
|
||||
```
|
||||
|
||||
*post* actions:
|
||||
```yaml
|
||||
actions:
|
||||
post:
|
||||
<action-key>: <command-to-execute>
|
||||
```
|
||||
|
||||
Actions can be either `post` or `pre`.
|
||||
|
||||
* `post` action will be executed after the dotfile deployment.
|
||||
* `pre` action will be executed before the dotfile deployment.
|
||||
|
||||
If you don't specify either `post` or `pre`, the action will be executed
|
||||
after the dotfile deployment (which is equivalent to `post`).
|
||||
Actions cannot obviously be named `pre` or `post`.
|
||||
|
||||
Four types of actions can be defined:
|
||||
|
||||
* [Dotfiles actions](config-dotfiles.md#dotfile-actions)
|
||||
* [Default actions](config-config.md#default_actions-entry)
|
||||
* [Profile actions](config-profiles.md#profile-actions-entry)
|
||||
* [Fake dotfiles and actions](config-actions.md#fake-dotfile-and-actions)
|
||||
|
||||
**Notes**:
|
||||
|
||||
* 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.
|
||||
* Make sure to quote your actions to avoid bad surprises
|
||||
* Actions are executed using the default shell (`$SHELL`)
|
||||
* To use shell variables in your actions, you need to escape the curly brackets (`${HOME}` becomes `${{HOME}}`)
|
||||
|
||||
## Fake dotfile and actions
|
||||
|
||||
*Fake* dotfile can be created by specifying no `dst` and no `src` (see [Fake dotfiles and actions](config-actions.md#fake-dotfile-and-actions)).
|
||||
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
|
||||
```
|
||||
|
||||
## Dynamic actions
|
||||
|
||||
Variables ([config variables and dynvariables](config-file.md#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.
|
||||
215
docs/config-config.md
Normal file
215
docs/config-config.md
Normal file
@@ -0,0 +1,215 @@
|
||||
# Config entry
|
||||
|
||||
The **config** entry (mandatory) contains global settings.
|
||||
|
||||
Entry | Description | Default
|
||||
-------- | ------------- | ------------
|
||||
`backup` | Create a backup of the dotfile in case it differs from the one that will be installed by dotdrop | true
|
||||
`banner` | Display the banner | true
|
||||
`check_version` | Check if a new version of dotdrop is available on github | false
|
||||
`chmod_on_import` | Always add a chmod entry on newly imported dotfiles (see `--preserve-mode`) | false
|
||||
`clear_workdir` | On `install` clear the `workdir` before installing dotfiles (see `--workdir-clear`) | false
|
||||
`compare_workdir` | On `compare` notify on files in `workdir` not tracked by dotdrop | false
|
||||
`cmpignore` | List of patterns to ignore when comparing, applied to all dotfiles (enclose in quotes when using wildcards; see [ignore patterns](config-file.md#ignore-patterns)) | -
|
||||
`create` | Create a directory hierarchy when installing dotfiles if it doesn't exist | true
|
||||
`default_actions` | List of action keys to execute for all installed dotfiles (See [actions](config-actions.md)) | -
|
||||
`diff_command` | The diff command to use for diffing files | `diff -r -u {0} {1}`
|
||||
`dotpath` | Path to the directory containing the dotfiles to be managed by dotdrop (absolute path or relative to the config file location) | `dotfiles`
|
||||
`filter_file` | List of paths to load templating filters from (See [Templating available filters](templating.md#template-filters)) | -
|
||||
`force_chmod` | If true, do not ask confirmation to apply permissions on install | false
|
||||
`func_file` | List of paths to load templating functions from (See [Templating available methods](templating.md#template-methods)) | -
|
||||
`ignore_missing_in_dotdrop` | Ignore missing files in dotdrop when comparing and importing (See [Ignore missing](config-file.md#ignore-missing)) | false
|
||||
`ignoreempty` | Do not deploy template if empty | false
|
||||
`impignore` | List of patterns to ignore when importing (enclose in quotes when using wildcards; see [ignore patterns](config-file.md#ignore-patterns)) | -
|
||||
`import_actions` | List of paths to load actions from (absolute path or relative to the config file location; see [Import actions from file](config-config.md#import_actions-entry)) | -
|
||||
`import_configs` | List of config file paths to be imported into the current config (absolute paths or relative to the current config file location; see [Import config files](config-config.md#import_configs-entry)) | -
|
||||
`import_variables` | List of paths to load variables from (absolute paths or relative to the config file location; see [Import variables from file](config-config.md#import_variables-entry)) | -
|
||||
`instignore` | List of patterns to ignore when installing, applied to all dotfiles (enclose in quotes when using wildcards; see [ignore patterns](config-file.md#ignore-patterns)) | -
|
||||
`keepdot` | Preserve leading dot when importing hidden file in the `dotpath` | false
|
||||
`key_prefix` | Prefix dotfile key on `import` with `f<key_separator>` for file and `d<key_separator>` for directory | true
|
||||
`key_separator` | Separator to use on dotfile key generation on `import` | `_`
|
||||
`link_dotfile_default` | Set a dotfile's `link` attribute to this value when undefined. Possible values: *nolink*, *link* (See [Symlinking dotfiles](config-file.md#symlinking-dotfiles)) | `nolink`
|
||||
`link_on_import` | Set a dotfile's `link` attribute to this value when importing. Possible values: *nolink*, *link* [Symlinking dotfiles](config-file.md#symlinking-dotfiles)) | `nolink`
|
||||
`longkey` | Use long keys for dotfiles when importing (See [Import dotfiles](usage.md#import-dotfiles)) | false
|
||||
`minversion` | (*for internal use, do not modify*) Provides the minimal dotdrop version to use | -
|
||||
`showdiff` | On install, show a diff before asking to overwrite (See `--showdiff`) | false
|
||||
`template_dotfile_default` | Disable templating on all dotfiles when set to false | true
|
||||
`upignore` | List of patterns to ignore when updating, appled to all dotfiles (enclose in quotes when using wildcards; see [ignore patterns](config-file.md#ignore-patterns)) | -
|
||||
`workdir` | Path to the directory where templates are installed before being symlinked when using `link:link` or `link:link_children` (absolute path or relative to the config file location) | `~/.config/dotdrop`
|
||||
<s>link_by_default</s> | When importing a dotfile, set `link` to this value by default | false
|
||||
|
||||
|
||||
## import_variables entry
|
||||
|
||||
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 `:optional` to the path:
|
||||
```yaml
|
||||
import_variables:
|
||||
- variables.d/myvars.yaml:optional
|
||||
```
|
||||
|
||||
## import_actions entry
|
||||
|
||||
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/imported variables will take precedence over variables defined
|
||||
inside the main 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 `:optional` to the path:
|
||||
```yaml
|
||||
import_actions:
|
||||
- actions.d/myactions.yaml:optional
|
||||
```
|
||||
|
||||
## import_configs entry
|
||||
|
||||
Entire config files can be imported using the `import_configs` entry.
|
||||
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 `:optional` to the path.
|
||||
```yaml
|
||||
import_configs:
|
||||
- other-config.yaml:optional
|
||||
```
|
||||
|
||||
## default_actions entry
|
||||
|
||||
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
|
||||
```
|
||||
@@ -1,713 +0,0 @@
|
||||
# Config details
|
||||
|
||||
## actions entry
|
||||
|
||||
Actions can be either `post` or `pre`.
|
||||
|
||||
* `post` action will be executed after the dotfile deployment.
|
||||
* `pre` action will be executed before the dotfile deployment.
|
||||
|
||||
If you don't specify either `post` or `pre`, the action will be executed
|
||||
after the dotfile deployment (which is equivalent to `post`).
|
||||
Actions cannot obviously be named `pre` or `post`.
|
||||
|
||||
Four types of actions can be defined:
|
||||
|
||||
* [Dotfiles actions](#dotfile-actions)
|
||||
* [Default actions](#default-actions)
|
||||
* [Profile actions](#profile-actions)
|
||||
* [Fake dotfiles and actions](#fake-dotfile-and-actions)
|
||||
|
||||
**Notes**:
|
||||
|
||||
* 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.
|
||||
* Make sure to quote your actions to avoid bad surprises
|
||||
* Actions are executed using the default shell (`$SHELL`)
|
||||
* To use shell variables in your actions, you need to escape the curly brackets (`${HOME}` becomes `${{HOME}}`)
|
||||
|
||||
### Dotfile actions
|
||||
|
||||
It is sometimes useful to execute some kind of action
|
||||
when deploying a dotfile.
|
||||
|
||||
Note that a dotfile's actions are only
|
||||
executed when the dotfile is installed (that is, when
|
||||
the version present in dotdrop differs from the one
|
||||
in the filesystem).
|
||||
|
||||
For example, let's consider
|
||||
[Vundle](https://github.com/VundleVim/Vundle.vim), 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
|
||||
```
|
||||
|
||||
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 you 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
|
||||
|
||||
A profile action can be either a `pre` or `post` action (see [actions](config-details.md#actions-entry)).
|
||||
These are executed before any dotfile installation (for `pre`) and after all dotfile installations (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](config-format.md)).
|
||||
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 entry
|
||||
|
||||
For examples of transformation uses, see:
|
||||
|
||||
* [Handle compressed directories](howto/store-compressed-directories.md)
|
||||
* [Handle secrets](howto/sensitive-dotfiles.md)
|
||||
|
||||
**Notes**:
|
||||
|
||||
* 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.
|
||||
* Make sure to quote your transformations to avoid bad surprises
|
||||
* Transformations are executed using the default shell (`$SHELL`)
|
||||
* To use shell variables in your transformations you need to escape the curly brackets (`${HOME}` becomes `${{HOME}}`)
|
||||
|
||||
There are two types of transformations available:
|
||||
|
||||
* **Read transformations**: used to transform dotfiles before they are installed ([format](config-format.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
|
||||
* This Happens **before** the dotfile is templated (see [templating](templating.md))
|
||||
|
||||
* **Write transformations**: used to transform files before updating a dotfile ([format](config-format.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 [the howto](howto/howto.md).
|
||||
|
||||
Note that transformations cannot be used if the dotfile 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 themselves as well as their 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 entry
|
||||
|
||||
Variables defined in the `variables` entry are made available within the config file.
|
||||
|
||||
Config variables are recursively evaluated, which 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`
|
||||
|
||||
## dynvariables 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](config.md#variables).
|
||||
|
||||
## uservariables entry
|
||||
|
||||
If you want to manually enter variables' values, you can use the
|
||||
`uservariables` entry. Each variable will be prompted to the user.
|
||||
|
||||
For example:
|
||||
```yaml
|
||||
uservariables:
|
||||
emailvar: "email"
|
||||
```
|
||||
|
||||
will prompt the user to enter a value for the variable `emailvar`:
|
||||
```
|
||||
Please provide the value for "email":
|
||||
```
|
||||
|
||||
And store the entered text as the value for the variable `email`.
|
||||
The variable can then be used as any other [variable](config.md#variables).
|
||||
|
||||
`uservariables` are eventually saved to `uservariables.yaml` (relatively to the
|
||||
config file).
|
||||
This allows you to use the following construct to prompt once for some specific variables and
|
||||
then store them in a file. You might also want to add `uservariables.yaml` to your `.gitignore`.
|
||||
```yaml
|
||||
uservariables:
|
||||
emailvar: "email"
|
||||
config:
|
||||
import_variables:
|
||||
- uservariables.yaml:optional
|
||||
```
|
||||
|
||||
For an example, see [prompt user for variables](howto/prompt-user-for-variables.md).
|
||||
|
||||
## Profile variables entry
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
## Profile include entry
|
||||
|
||||
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.md#variables) and [dynvariables](#dynvariables-entry))
|
||||
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 @@}}"
|
||||
```
|
||||
|
||||
Note that profiles cannot include other profiles defined above in
|
||||
the import tree (for example, when a profile exists in another file and is imported using `import_configs`).
|
||||
|
||||
## Profile import entry
|
||||
|
||||
A 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`, which allow you to do something like:
|
||||
```yaml
|
||||
import:
|
||||
- profiles.d/{{@@ profile @@}}.yaml
|
||||
```
|
||||
|
||||
## import_variables entry
|
||||
|
||||
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 `:optional` to the path:
|
||||
```yaml
|
||||
import_variables:
|
||||
- variables.d/myvars.yaml:optional
|
||||
```
|
||||
|
||||
## import_actions entry
|
||||
|
||||
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/imported variables will take precedence over variables defined
|
||||
inside the main 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 `:optional` to the path:
|
||||
```yaml
|
||||
import_actions:
|
||||
- actions.d/myactions.yaml:optional
|
||||
```
|
||||
|
||||
## import_configs entry
|
||||
|
||||
Entire config files can be imported using the `import_configs` entry.
|
||||
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 `:optional` to the path.
|
||||
```yaml
|
||||
import_configs:
|
||||
- other-config.yaml:optional
|
||||
```
|
||||
|
||||
## Dynamic dotfile paths
|
||||
|
||||
Dotfile source (`src`) and destination (`dst`) paths can be dynamically constructed using
|
||||
defined variables ([variables and dynvariables](config.md#variables)).
|
||||
|
||||
For example, to have a dotfile deployed on a 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
|
||||
```
|
||||
|
||||
Or when you need to select the dotfile to deploy depending on
|
||||
the profile used (`ssh_config.perso` for the profile `perso` and
|
||||
`ssh_config.work` for the `work` profile):
|
||||
```yaml
|
||||
dotfiles:
|
||||
f_ssh_config:
|
||||
src: "{{@@ ssh_config_file @@}}"
|
||||
dst: ~/.ssh/config
|
||||
profiles:
|
||||
perso:
|
||||
dotfiles:
|
||||
- f_ssh_config
|
||||
variables:
|
||||
- ssh_config_file: "ssh_config.perso"
|
||||
work:
|
||||
dotfiles:
|
||||
- f_ssh_config
|
||||
variables:
|
||||
- ssh_config_file: "ssh_config.work"
|
||||
```
|
||||
|
||||
## Dynamic dotfile link value
|
||||
|
||||
Dotfile `link` values can be dynamically constructed using
|
||||
defined variables ([variables and dynvariables](config.md#variables)).
|
||||
|
||||
For example:
|
||||
```yaml
|
||||
variables:
|
||||
link_value: "nolink"
|
||||
dotfiles:
|
||||
f_test:
|
||||
src: test
|
||||
dst: ~/.test
|
||||
link: "{{@@ link_value @@}}"
|
||||
profiles:
|
||||
linux:
|
||||
dotfiles:
|
||||
- f_test
|
||||
variables:
|
||||
link_value: "link"
|
||||
windows:
|
||||
dotfiles:
|
||||
- f_test
|
||||
```
|
||||
|
||||
Make sure to quote the link value in the config file.
|
||||
|
||||
## Dynamic actions
|
||||
|
||||
Variables ([config variables and dynvariables](config.md#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](config.md#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
|
||||
```
|
||||
218
docs/config-dotfiles.md
Normal file
218
docs/config-dotfiles.md
Normal file
@@ -0,0 +1,218 @@
|
||||
# Dotfiles entry
|
||||
|
||||
The **dotfiles** entry (mandatory) contains a YAML object with sub-objects for the dotfiles managed by dotdrop. The entries in the sub-objects are as follows:
|
||||
|
||||
Entry | Description
|
||||
-------- | -------------
|
||||
`dst` | Where this dotfile needs to be deployed (dotfiles with empty `dst` are ignored and considered installed, can use `variables`, make sure to quote)
|
||||
`src` | Dotfile path within the `dotpath` (dotfiles with empty `src` are ignored and considered installed, can use `variables`, make sure to quote)
|
||||
`link` | Defines how this dotfile is installed. Possible values: *nolink*, *link*, *link_children* (See [Symlinking dotfiles](config-file.md#symlinking-dotfiles)) (defaults to value of `link_dotfile_default`)
|
||||
`actions` | List of action keys that need to be defined in the **actions** entry below (See [actions](config-actions.md))
|
||||
`chmod` | Defines the file permissions in octal notation to apply during installation (See [permissions](config-file.md#permissions))
|
||||
`cmpignore` | List of patterns to ignore when comparing (enclose in quotes when using wildcards; see [ignore patterns](config-file.md#ignore-patterns))
|
||||
`ignore_missing_in_dotdrop` | Ignore missing files in dotdrop when comparing and importing (see [Ignore missing](config-file.md#ignore-missing))
|
||||
`ignoreempty` | If true, an empty template will not be deployed (defaults to the value of `ignoreempty`)
|
||||
`instignore` | List of patterns to ignore when installing (enclose in quotes when using wildcards; see [ignore patterns](config-file.md#ignore-patterns))
|
||||
`template` | If false, disable templating for this dotfile (defaults to the value of `template_dotfile_default`)
|
||||
`trans_read` | Transformation key to apply when installing this dotfile (must be defined in the **trans_read** entry below; see [transformations](config-transformations.md))
|
||||
`trans_write` | Transformation key to apply when updating this dotfile (must be defined in the **trans_write** entry below; see [transformations](config-transformations.md))
|
||||
`upignore` | List of patterns to ignore when updating (enclose in quotes when using wildcards; see [ignore patterns](config-file.md#ignore-patterns))
|
||||
<s>link_children</s> | Replaced by `link: link_children`
|
||||
<s>trans</s> | 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>
|
||||
template: (true|false)
|
||||
chmod: '<file-permissions>'
|
||||
trans_read: <transformation-key>
|
||||
trans_write: <transformation-key>
|
||||
```
|
||||
|
||||
## Dotfile actions
|
||||
|
||||
It is sometimes useful to execute some kind of action
|
||||
when deploying a dotfile.
|
||||
|
||||
Note that a dotfile's actions are only
|
||||
executed when the dotfile is installed (that is, when
|
||||
the version present in dotdrop differs from the one
|
||||
in the filesystem).
|
||||
|
||||
For example, let's consider
|
||||
[Vundle](https://github.com/VundleVim/Vundle.vim), 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
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
## Dynamic dotfile paths
|
||||
|
||||
Dotfile source (`src`) and destination (`dst`) paths can be dynamically constructed using
|
||||
defined variables ([variables and dynvariables](config-file.md#variables)).
|
||||
|
||||
For example, to have a dotfile deployed on a 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
|
||||
```
|
||||
|
||||
Or when you need to select the dotfile to deploy depending on
|
||||
the profile used (`ssh_config.perso` for the profile `perso` and
|
||||
`ssh_config.work` for the `work` profile):
|
||||
```yaml
|
||||
dotfiles:
|
||||
f_ssh_config:
|
||||
src: "{{@@ ssh_config_file @@}}"
|
||||
dst: ~/.ssh/config
|
||||
profiles:
|
||||
perso:
|
||||
dotfiles:
|
||||
- f_ssh_config
|
||||
variables:
|
||||
- ssh_config_file: "ssh_config.perso"
|
||||
work:
|
||||
dotfiles:
|
||||
- f_ssh_config
|
||||
variables:
|
||||
- ssh_config_file: "ssh_config.work"
|
||||
```
|
||||
|
||||
## Dynamic dotfile link value
|
||||
|
||||
Dotfile `link` values can be dynamically constructed using
|
||||
defined variables ([variables and dynvariables](config-file.md#variables)).
|
||||
|
||||
For example:
|
||||
```yaml
|
||||
variables:
|
||||
link_value: "nolink"
|
||||
dotfiles:
|
||||
f_test:
|
||||
src: test
|
||||
dst: ~/.test
|
||||
link: "{{@@ link_value @@}}"
|
||||
profiles:
|
||||
linux:
|
||||
dotfiles:
|
||||
- f_test
|
||||
variables:
|
||||
link_value: "link"
|
||||
windows:
|
||||
dotfiles:
|
||||
- f_test
|
||||
```
|
||||
|
||||
Make sure to quote the link value in the config file.
|
||||
25
docs/config-dynvars.md
Normal file
25
docs/config-dynvars.md
Normal file
@@ -0,0 +1,25 @@
|
||||
# Dynvariables entry
|
||||
|
||||
The **dynvariables** entry (optional) contains an interpreted variables mapping.
|
||||
|
||||
```yaml
|
||||
dynvariables:
|
||||
<variable-name>: <shell-oneliner>
|
||||
```
|
||||
|
||||
Dynvariables (*dynamic* variables) will be interpreted by the shell before being substituted.
|
||||
|
||||
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](config-file.md#variables).
|
||||
@@ -1,8 +1,8 @@
|
||||
# Config
|
||||
# Config file
|
||||
|
||||
## Location
|
||||
|
||||
The config file used by dotdrop is
|
||||
The default config file used by dotdrop is
|
||||
[config.yaml](https://github.com/deadc0de6/dotdrop/blob/master/config.yaml).
|
||||
|
||||
Unless specified otherwise, dotdrop will look in the following places for its config file
|
||||
@@ -22,25 +22,25 @@ or by defining the `DOTDROP_CONFIG` environment variable.
|
||||
Multiple variables can be used within the config file to
|
||||
parametrize the following elements of the config:
|
||||
|
||||
* Dotfile `src` and `dst` paths (See [Dynamic dotfile paths](config-details.md#dynamic-dotfile-paths))
|
||||
* External path specifications
|
||||
* `import_variables`
|
||||
* `import_actions`
|
||||
* `import_configs`
|
||||
* Profiles' `import`
|
||||
* Profiles' `include`
|
||||
* Dotfile `src` and `dst` paths (See [Dynamic dotfile paths](config-dotfiles.md#dynamic-dotfile-paths))
|
||||
* External paths
|
||||
* `import_variables`
|
||||
* `import_actions`
|
||||
* `import_configs`
|
||||
* Profiles' `import`
|
||||
* Profiles' `include`
|
||||
|
||||
`actions` and `transformations` also support the use of variables,
|
||||
but those are resolved when the action/transformation is executed
|
||||
(See [Dynamic actions](config-details.md#dynamic-actions),
|
||||
[Dynamic transformations](config-details.md#dynamic-transformations) and [Templating](templating.md)).
|
||||
(See [Dynamic actions](config-actions.md#dynamic-actions),
|
||||
[Dynamic transformations](config-transformations.md#dynamic-transformations) and [Templating](templating.md)).
|
||||
|
||||
The following variables are available in the config files:
|
||||
|
||||
* [Variables defined in the config](config-details.md#variables-entry)
|
||||
* [Interpreted variables defined in the config](config-details.md#dynvariables-entry)
|
||||
* [User variables defined in the config](config-details.md#uservariables-entry)
|
||||
* [Profile variables defined in the config](config-details.md#profile-variables-entry)
|
||||
* [Variables defined in the config](config-variables.md)
|
||||
* [Interpreted variables defined in the config](config-dynvars.md)
|
||||
* [User variables defined in the config](config-variables.md)
|
||||
* [Profile variables defined in the config](config-profiles.md#profile-variables-entry)
|
||||
* Environment variables: `{{@@ env['MY_VAR'] @@}}`
|
||||
* Dotdrop header: `{{@@ header() @@}}` (see [Dotdrop header](templating.md#dotdrop-header))
|
||||
|
||||
@@ -51,24 +51,24 @@ then be available during [templating](templating.md).
|
||||
|
||||
Here are some rules on the use of variables in configs:
|
||||
|
||||
* [Interpreted variables](config-details.md#dynvariables-entry) are executed in their own file.
|
||||
* [Interpreted variables](config-details.md#dynvariables-entry) and
|
||||
[variables](config-details.md#variables-entry) are templated before
|
||||
[interpreted variables](config-details.md#dynvariables-entry) are executed.
|
||||
* [Interpreted variables](config-dynvars.md) are executed in their own file.
|
||||
* [Interpreted variables](config-dynvars.md) and
|
||||
[variables](config-dynvars.md) are templated before
|
||||
[interpreted variables](config-dynvars.md) are executed.
|
||||
* Config files do not have access to variables defined above in the import tree.
|
||||
* `dynvariables` take precedence over `variables`.
|
||||
* Profile `(dyn)variables` take precedence over any other `(dyn)variables`.
|
||||
* Profile `(dyn)variables` take precedence over profile's included `(dyn)variables`.
|
||||
* External/imported `(dyn)variables` take precedence over
|
||||
`(dyn)variables` defined inside the main config file.
|
||||
* [User variables](config-details.md#uservariables-entry) are ignored if
|
||||
* [User variables](config-uservars.md) are ignored if
|
||||
any other variable with the same key is defined.
|
||||
|
||||
## Permissions
|
||||
|
||||
Dotdrop allows you to control the permissions applied to a dotfile using the
|
||||
config dotfile entry [chmod](config-format.md#dotfiles-entry).
|
||||
A [chmod](config-format.md#dotfiles-entry) entry on a directory
|
||||
Dotdrop allows to control the permissions applied to a dotfile using the
|
||||
config dotfile entry [chmod](config-dotfiles.md).
|
||||
A [chmod](config-dotfiles.md) entry on a directory
|
||||
is applied to the directory only, not recursively.
|
||||
|
||||
For example:
|
||||
@@ -100,7 +100,7 @@ On `install`, the following rules are applied:
|
||||
* If the global setting `force_chmod` is set to true, dotdrop will not ask
|
||||
for confirmation to apply permissions.
|
||||
|
||||
On `update`:
|
||||
On `update`, the following rule is applied:
|
||||
|
||||
* If the permissions of the file in the filesystem differ from the dotfile in the `dotpath`,
|
||||
then the dotfile entry `chmod` is added/updated accordingly.
|
||||
@@ -119,21 +119,21 @@ For more, see [this how-to](howto/symlink-dotfiles.md).
|
||||
|
||||
## Template config entries
|
||||
|
||||
Some entries in the config can use the templating feature (See [templating](templating.md)):
|
||||
Some entries in the config can be templated (See [templating](templating.md)):
|
||||
|
||||
Entry | Related doc
|
||||
-------- | -------------
|
||||
dotfile src | [Dynamic dotfile paths](config-details.md#dynamic-dotfile-paths)
|
||||
dotfile dst | [Dynamic dotfile paths](config-details.md#dynamic-dotfile-paths)
|
||||
dotfile link | [Dynamic dotfile link value](config-details.md#dynamic-dotfile-link-value)
|
||||
variables | [variables](config-details.md#variables-entry)
|
||||
dynvariables | [dynvariables](config-details.md#dynvariables-entry)
|
||||
actions | [dynamic actions](config-details.md#dynamic-actions)
|
||||
profile include | [Profile include](config-details.md#profile-include-entry)
|
||||
profile import | [Profile import](config-details.md#profile-import-entry)
|
||||
import_variables | [import_variables](config-details.md#import_variables-entry)
|
||||
import_actions | [import_actions](config-details.md#import_actions-entry)
|
||||
import_configs | [import_configs](config-details.md#import_configs-entry)
|
||||
dotfile src | [Dynamic dotfile paths](config-dotfiles.md#dynamic-dotfile-paths)
|
||||
dotfile dst | [Dynamic dotfile paths](config-dotfiles.md#dynamic-dotfile-paths)
|
||||
dotfile link | [Dynamic dotfile link value](config-dotfiles.md#dynamic-dotfile-link-value)
|
||||
variables | [variables](config-variables.md)
|
||||
dynvariables | [dynvariables](config-dynvars.md)
|
||||
actions | [dynamic actions](config-dynvars.md)
|
||||
profile include | [Profile include](config-profiles.md#profile-include-entry)
|
||||
profile import | [Profile import](config-profiles.md#profile-import-entry)
|
||||
import_variables | [import_variables](config-config.md#import_variables-entry)
|
||||
import_actions | [import_actions](config-config.md#import_actions-entry)
|
||||
import_configs | [import_configs](config-config.md#import_configs-entry)
|
||||
|
||||
## All dotfiles for a profile
|
||||
|
||||
@@ -200,7 +200,7 @@ Patterns used for a specific dotfile can be specified relative to the dotfile de
|
||||
Similar to a `.gitignore` file, you can prefix ignore patterns with an exclamation point (`!`).
|
||||
This so-called "negative ignore pattern" will cause any files that match that pattern to __not__ be ignored,
|
||||
provided they *would have* been ignored by an earlier ignore pattern (dotdrop will warn if that is not the
|
||||
case). This feature allows you to, for example, ignore all files within a certain directory, except for a
|
||||
case). This feature allows to, for example, ignore all files within a certain directory, except for a
|
||||
particular one (See examples below).
|
||||
|
||||
To completely ignore comparison of a specific dotfile:
|
||||
@@ -252,3 +252,32 @@ dotfiles:
|
||||
- '!file'
|
||||
- '[a-zA-Z0-9]*'
|
||||
```
|
||||
|
||||
## Ignore missing
|
||||
|
||||
Sometimes, it is nice to have [update](usage.md#update-dotfiles) not copy all the files in the installed directory
|
||||
or [compare](usage.md#compare-dotfiles) diff them.
|
||||
|
||||
For example,
|
||||
maybe you only want to include a single configuration file in your repository
|
||||
and don't want to include other files the program uses,
|
||||
such as a cached files.
|
||||
Maybe you only want to change one file and don't want the others cluttering your repository.
|
||||
Maybe the program changes these files quite often and creates unnecessary diffs in your dotfiles.
|
||||
|
||||
In these cases, you can use the [ignore-missing](config-config.md) option.
|
||||
This option is available as a flag (`--ignore-missing` or `-z`) to the `update` and `compare` commands,
|
||||
or [as ignore-missing in the config](config-config.md).
|
||||
|
||||
To configure globally, place the following in `config.yaml`:
|
||||
```yaml
|
||||
config:
|
||||
ignore_missing_in_dotdrop: true
|
||||
```
|
||||
|
||||
To configure per dotfile:
|
||||
```yaml
|
||||
dotfiles:
|
||||
f_abc:
|
||||
ignore_missing_in_dotdrop: true
|
||||
```
|
||||
@@ -1,195 +0,0 @@
|
||||
# Config format
|
||||
|
||||
The dotdrop config file uses [YAML](https://yaml.org/) syntax.
|
||||
|
||||
Here is a minimal config file to start with:
|
||||
[config.yaml](https://github.com/deadc0de6/dotdrop/blob/master/config.yaml).
|
||||
|
||||
## config entry
|
||||
|
||||
The **config** entry (mandatory) contains settings for the deployment.
|
||||
|
||||
Entry | Description | Default
|
||||
-------- | ------------- | ------------
|
||||
`backup` | Create a backup of the dotfile in case it differs from the one that will be installed by dotdrop | true
|
||||
`banner` | Display the banner | true
|
||||
`check_version` | Check if a new version of dotdrop is available on github | false
|
||||
`chmod_on_import` | Always add a chmod entry on newly imported dotfiles (see `--preserve-mode`) | false
|
||||
`clear_workdir` | On `install` clear the `workdir` before installing dotfiles (see `--workdir-clear`) | false
|
||||
`compare_workdir` | On `compare` notify on files in `workdir` not tracked by dotdrop | false
|
||||
`cmpignore` | List of patterns to ignore when comparing, applied to all dotfiles (enclose in quotes when using wildcards; see [ignore patterns](config.md#ignore-patterns)) | -
|
||||
`create` | Create a directory hierarchy when installing dotfiles if it doesn't exist | true
|
||||
`default_actions` | List of action keys to execute for all installed dotfiles (See [actions](config-details.md#actions-entry)) | -
|
||||
`diff_command` | The diff command to use for diffing files | `diff -r -u {0} {1}`
|
||||
`dotpath` | Path to the directory containing the dotfiles to be managed by dotdrop (absolute path or relative to the config file location) | `dotfiles`
|
||||
`filter_file` | List of paths to load templating filters from (See [Templating available filters](templating.md#template-filters)) | -
|
||||
`force_chmod` | If true, do not ask confirmation to apply permissions on install | false
|
||||
`func_file` | List of paths to load templating functions from (See [Templating available methods](templating.md#template-methods)) | -
|
||||
`ignore_missing_in_dotdrop` | Ignore missing files in dotdrop when comparing and importing (See [Ignore missing](usage.md#ignore-missing)) | false
|
||||
`ignoreempty` | Do not deploy template if empty | false
|
||||
`impignore` | List of patterns to ignore when importing (enclose in quotes when using wildcards; see [ignore patterns](config.md#ignore-patterns)) | -
|
||||
`import_actions` | List of paths to load actions from (absolute path or relative to the config file location; see [Import actions from file](config-details.md#import_actions-entry)) | -
|
||||
`import_configs` | List of config file paths to be imported into the current config (absolute paths or relative to the current config file location; see [Import config files](config-details.md#import_configs-entry)) | -
|
||||
`import_variables` | List of paths to load variables from (absolute paths or relative to the config file location; see [Import variables from file](config-details.md#import_variables-entry)) | -
|
||||
`instignore` | List of patterns to ignore when installing, applied to all dotfiles (enclose in quotes when using wildcards; see [ignore patterns](config.md#ignore-patterns)) | -
|
||||
`keepdot` | Preserve leading dot when importing hidden file in the `dotpath` | false
|
||||
`key_prefix` | Prefix dotfile key on `import` with `f<key_separator>` for file and `d<key_separator>` for directory | true
|
||||
`key_separator` | Separator to use on dotfile key generation on `import` | `_`
|
||||
`link_dotfile_default` | Set a dotfile's `link` attribute to this value when undefined. Possible values: *nolink*, *link* (See [Symlinking dotfiles](config.md#symlinking-dotfiles)) | `nolink`
|
||||
`link_on_import` | Set a dotfile's `link` attribute to this value when importing. Possible values: *nolink*, *link* [Symlinking dotfiles](config.md#symlinking-dotfiles)) | `nolink`
|
||||
`longkey` | Use long keys for dotfiles when importing (See [Import dotfiles](usage.md#import-dotfiles)) | false
|
||||
`minversion` | (*for internal use, do not modify*) Provides the minimal dotdrop version to use | -
|
||||
`showdiff` | On install, show a diff before asking to overwrite (See `--showdiff`) | false
|
||||
`template_dotfile_default` | Disable templating on all dotfiles when set to false | true
|
||||
`upignore` | List of patterns to ignore when updating, appled to all dotfiles (enclose in quotes when using wildcards; see [ignore patterns](config.md#ignore-patterns)) | -
|
||||
`workdir` | Path to the directory where templates are installed before being symlinked when using `link:link` or `link:link_children` (absolute path or relative to the config file location) | `~/.config/dotdrop`
|
||||
<s>link_by_default</s> | When importing a dotfile, set `link` to this value by default | false
|
||||
|
||||
## dotfiles entry
|
||||
|
||||
The **dotfiles** entry (mandatory) contains a YAML object with sub-objects for the dotfiles managed by dotdrop. The entries in the sub-objects are as follows:
|
||||
|
||||
Entry | Description
|
||||
-------- | -------------
|
||||
`dst` | Where this dotfile needs to be deployed (dotfiles with empty `dst` are ignored and considered installed, can use `variables`, make sure to quote)
|
||||
`src` | Dotfile path within the `dotpath` (dotfiles with empty `src` are ignored and considered installed, can use `variables`, make sure to quote)
|
||||
`link` | Defines how this dotfile is installed. Possible values: *nolink*, *link*, *link_children* (See [Symlinking dotfiles](config.md#symlinking-dotfiles)) (defaults to value of `link_dotfile_default`)
|
||||
`actions` | List of action keys that need to be defined in the **actions** entry below (See [actions](config-details.md#actions-entry))
|
||||
`chmod` | Defines the file permissions in octal notation to apply during installation (See [permissions](config.md#permissions))
|
||||
`cmpignore` | List of patterns to ignore when comparing (enclose in quotes when using wildcards; see [ignore patterns](config.md#ignore-patterns))
|
||||
`ignore_missing_in_dotdrop` | Ignore missing files in dotdrop when comparing and importing (see [Ignore missing](usage.md#ignore-missing))
|
||||
`ignoreempty` | If true, an empty template will not be deployed (defaults to the value of `ignoreempty`)
|
||||
`instignore` | List of patterns to ignore when installing (enclose in quotes when using wildcards; see [ignore patterns](config.md#ignore-patterns))
|
||||
`template` | If false, disable templating for this dotfile (defaults to the value of `template_dotfile_default`)
|
||||
`trans_read` | Transformation key to apply when installing this dotfile (must be defined in the **trans_read** entry below; see [transformations](config-details.md#transformations-entry))
|
||||
`trans_write` | Transformation key to apply when updating this dotfile (must be defined in the **trans_write** entry below; see [transformations](config-details.md#transformations-entry))
|
||||
`upignore` | List of patterns to ignore when updating (enclose in quotes when using wildcards; see [ignore patterns](config.md#ignore-patterns))
|
||||
<s>link_children</s> | Replaced by `link: link_children`
|
||||
<s>trans</s> | 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>
|
||||
template: (true|false)
|
||||
chmod: '<file-permissions>'
|
||||
trans_read: <transformation-key>
|
||||
trans_write: <transformation-key>
|
||||
```
|
||||
|
||||
## profiles entry
|
||||
|
||||
The **profiles** entry (mandatory) contains a YAML object with sub-objects for the profiles for the different dotfiles that need to be managed. The entries in the sub-objects are as follows:
|
||||
|
||||
Entry | Description
|
||||
-------- | -------------
|
||||
`dotfiles` | The dotfiles associated with this profile
|
||||
`import` | List of paths containing dotfile keys for this profile (absolute path or relative to the config file location; see [Import profile dotfiles from file](config-details.md#profile-import-entry)).
|
||||
`include` | Include all elements (dotfiles, actions, (dyn)variables, etc) from another profile (See [Include dotfiles from another profile](config-details.md#profile-include-entry))
|
||||
`variables` | Profile-specific variables (See [Variables](config.md#variables))
|
||||
`dynvariables` | Profile-specific interpreted variables (See [Interpreted variables](config-details.md#dynvariables-entry))
|
||||
`actions` | List of action keys that need to be defined in the **actions** entry below (See [actions](config-details.md#actions-entry))
|
||||
|
||||
```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 an actions mapping (See [actions](config-details.md#actions-entry)).
|
||||
|
||||
```yaml
|
||||
actions:
|
||||
<action-key>: <command-to-execute>
|
||||
```
|
||||
|
||||
*pre* actions:
|
||||
```yaml
|
||||
actions:
|
||||
pre:
|
||||
<action-key>: <command-to-execute>
|
||||
```
|
||||
|
||||
*post* actions:
|
||||
```yaml
|
||||
actions:
|
||||
post:
|
||||
<action-key>: <command-to-execute>
|
||||
```
|
||||
|
||||
## trans_read entry
|
||||
|
||||
The **trans_read** entry (optional) contains a transformations mapping (See [transformations](config-details.md#transformations-entry)).
|
||||
|
||||
```yaml
|
||||
trans_read:
|
||||
<trans-key>: <command-to-execute>
|
||||
```
|
||||
|
||||
## trans_write entry
|
||||
|
||||
The **trans_write** entry (optional) contains a write transformations mapping (See [transformations](config-details.md#transformations-entry)).
|
||||
|
||||
```yaml
|
||||
trans_write:
|
||||
<trans-key>: <command-to-execute>
|
||||
```
|
||||
|
||||
## variables entry
|
||||
|
||||
The **variables** entry (optional) contains a variables mapping (See [variables](config.md#variables)).
|
||||
|
||||
```yaml
|
||||
variables:
|
||||
<variable-name>: <variable-content>
|
||||
```
|
||||
|
||||
## dynvariables entry
|
||||
|
||||
The **dynvariables** entry (optional) contains an interpreted variables mapping
|
||||
(See [Interpreted variables](config-details.md#dynvariables-entry)).
|
||||
|
||||
```yaml
|
||||
dynvariables:
|
||||
<variable-name>: <shell-oneliner>
|
||||
```
|
||||
|
||||
## uservariables entry
|
||||
|
||||
The **uservariables** entry (optional) contains a collection of variables
|
||||
whose values are queried from the user
|
||||
(See [User variables](config-details.md#uservariables-entry)).
|
||||
|
||||
```yaml
|
||||
uservariables:
|
||||
<variable-name>: <prompt>
|
||||
```
|
||||
152
docs/config-profiles.md
Normal file
152
docs/config-profiles.md
Normal file
@@ -0,0 +1,152 @@
|
||||
# Profiles entry
|
||||
|
||||
The **profiles** entry (mandatory) contains a YAML object with sub-objects for the profiles for the different dotfiles that need to be managed. The entries in the sub-objects are as follows:
|
||||
|
||||
Entry | Description
|
||||
-------- | -------------
|
||||
`dotfiles` | The dotfiles associated with this profile
|
||||
`import` | List of paths containing dotfile keys for this profile (absolute path or relative to the config file location; see [Import profile dotfiles from file](config-profiles.md#profile-import-entry)).
|
||||
`include` | Include all elements (dotfiles, actions, (dyn)variables, etc) from another profile (See [Include dotfiles from another profile](config-profiles.md#profile-include-entry))
|
||||
`variables` | Profile-specific variables (See [Variables](config-file.md#variables))
|
||||
`dynvariables` | Profile-specific interpreted variables (See [Interpreted variables](config-dynvars.md))
|
||||
`actions` | List of action keys that need to be defined in the **actions** entry below (See [actions](config-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>
|
||||
- ...
|
||||
```
|
||||
|
||||
## Profile include entry
|
||||
|
||||
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-dynvars.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 @@}}"
|
||||
```
|
||||
|
||||
Note that profiles cannot include other profiles defined above in
|
||||
the import tree (for example, when a profile exists in another file and is imported using `import_configs`).
|
||||
|
||||
## Profile import entry
|
||||
|
||||
A 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`, what allows to do something like:
|
||||
```yaml
|
||||
import:
|
||||
- profiles.d/{{@@ profile @@}}.yaml
|
||||
```
|
||||
|
||||
## Profile variables entry
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
## Profile actions entry
|
||||
|
||||
A profile action can be either a `pre` or `post` action (see [actions](config-actions.md)).
|
||||
These are executed before any dotfile installation (for `pre`) and after all dotfile installations (for `post`)
|
||||
only if at least one dotfile has been installed.
|
||||
100
docs/config-transformations.md
Normal file
100
docs/config-transformations.md
Normal file
@@ -0,0 +1,100 @@
|
||||
# Transformations entry
|
||||
|
||||
For examples of transformation uses, see:
|
||||
|
||||
* [Handle compressed directories](howto/store-compressed-directories.md)
|
||||
* [Handle secrets](howto/sensitive-dotfiles.md)
|
||||
|
||||
**Notes**:
|
||||
|
||||
* 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.
|
||||
* Make sure to quote your transformations to avoid bad surprises
|
||||
* Transformations are executed using the default shell (`$SHELL`)
|
||||
* To use shell variables in your transformations you need to escape the curly brackets (`${HOME}` becomes `${{HOME}}`)
|
||||
|
||||
There are two types of transformations available:
|
||||
|
||||
* **Read transformations**: used to transform dotfiles before they are installed ([config](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
|
||||
* This Happens **before** the dotfile is templated (see [templating](templating.md))
|
||||
|
||||
* **Write transformations**: used to transform files before updating a dotfile ([config](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 [the howto](howto/howto.md).
|
||||
|
||||
Note that transformations cannot be used if the dotfile 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 themselves as well as their 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`.
|
||||
|
||||
## trans_read entry
|
||||
|
||||
The **trans_read** entry (optional) contains a transformations mapping (See [transformations](config-transformations.md)).
|
||||
|
||||
```yaml
|
||||
trans_read:
|
||||
<trans-key>: <command-to-execute>
|
||||
```
|
||||
|
||||
## trans_write entry
|
||||
|
||||
The **trans_write** entry (optional) contains a write transformations mapping (See [transformations](config-transformations.md)).
|
||||
|
||||
```yaml
|
||||
trans_write:
|
||||
<trans-key>: <command-to-execute>
|
||||
```
|
||||
|
||||
## Dynamic transformations
|
||||
|
||||
As for [dynamic actions](config-actions.md#dynamic-actions), transformations support
|
||||
the use of variables ([variables and dynvariables](config-file.md#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
|
||||
```
|
||||
41
docs/config-uservars.md
Normal file
41
docs/config-uservars.md
Normal file
@@ -0,0 +1,41 @@
|
||||
# Uservariables entry
|
||||
|
||||
The **uservariables** entry (optional) contains a collection of variables
|
||||
whose values are queried from the user
|
||||
(See [User variables](config-variables.md)).
|
||||
|
||||
```yaml
|
||||
uservariables:
|
||||
<variable-name>: <prompt>
|
||||
```
|
||||
|
||||
If you want to manually enter variables' values, you can use the
|
||||
`uservariables` entry. Each variable will be prompted to the user.
|
||||
|
||||
For example:
|
||||
```yaml
|
||||
uservariables:
|
||||
emailvar: "email"
|
||||
```
|
||||
|
||||
will prompt the user to enter a value for the variable `emailvar`:
|
||||
```
|
||||
Please provide the value for "email":
|
||||
```
|
||||
|
||||
And store the entered text as the value for the variable `email`.
|
||||
The variable can then be used as any other [variable](config-file.md#variables).
|
||||
|
||||
`uservariables` are eventually saved to `uservariables.yaml` (relatively to the
|
||||
config file).
|
||||
This allows to use the following construct to prompt once for some specific variables and
|
||||
then store them in a file. You might also want to add `uservariables.yaml` to your `.gitignore`.
|
||||
```yaml
|
||||
uservariables:
|
||||
emailvar: "email"
|
||||
config:
|
||||
import_variables:
|
||||
- uservariables.yaml:optional
|
||||
```
|
||||
|
||||
For an example, see [prompt user for variables](howto/prompt-user-for-variables.md).
|
||||
36
docs/config-variables.md
Normal file
36
docs/config-variables.md
Normal file
@@ -0,0 +1,36 @@
|
||||
# Variables entry
|
||||
|
||||
The **variables** entry (optional) contains a variables mapping (See [variables](config-file.md#variables)).
|
||||
|
||||
```yaml
|
||||
variables:
|
||||
<variable-name>: <variable-content>
|
||||
```
|
||||
|
||||
Variables defined in the `variables` entry are made available within the config file.
|
||||
|
||||
Config variables are recursively evaluated, which 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`
|
||||
@@ -1,4 +1,6 @@
|
||||
# Repository setup
|
||||
# Getting started
|
||||
|
||||
## Repository setup
|
||||
|
||||
Either create a Git repository on your prefered platform and clone it or create one locally.
|
||||
This repository will contain two main elements, dotdrop's config file (`config.yaml`)
|
||||
@@ -21,7 +23,7 @@ $ wget https://raw.githubusercontent.com/deadc0de6/dotdrop/master/config.yaml
|
||||
```
|
||||
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;
|
||||
see [config location](config.md#location) for more.
|
||||
see [config location](config-file.md#location) for more.
|
||||
|
||||
```bash
|
||||
$ tree my-dotfiles
|
||||
@@ -36,7 +38,20 @@ in your preferred shell to call dotdrop with the config file path argument.
|
||||
alias dotdrop='dotdrop --cfg=<path-to-your-config.yaml>'
|
||||
```
|
||||
|
||||
For more info on the config file format, see [the config doc](config.md).
|
||||
For more info on the config file format, see [the config file doc](config-file.md).
|
||||
|
||||
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).
|
||||
## Basic usage
|
||||
|
||||
The basic use of dotdrop is:
|
||||
|
||||
* Import a file/directory to manage (this will copy the files from the filesystem to your `dotpath`): `dotdrop import <somefile>`
|
||||
* Install the dotfiles (this will *copy/link* them from your `dotpath` to the filesystem): `dotdrop install`
|
||||
|
||||
Then if you happen to update the file/directory directly on the filesystem (add a new file/dir, edit content, etc.) you can use the `update` command to mirror back those changes in dotdrop.
|
||||
|
||||
For more advanced uses:
|
||||
|
||||
* `dotdrop --help` for the CLI usage.
|
||||
* [The usage doc](usage.md)
|
||||
* [The example](https://github.com/deadc0de6/dotdrop#getting-started)
|
||||
* [The howto](howto/howto.md)
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
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
|
||||
[actions](../config-details.md#actions-entry) and a temporary file.
|
||||
[actions](../config-actions.md) and a temporary file.
|
||||
|
||||
Below is a config example to append to a file:
|
||||
```yaml
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# Create files on install
|
||||
|
||||
One way to create symlinks (or any other special file) is to use a combination of
|
||||
[actions](../config-details.md#actions-entry) and a *fake* dotfile.
|
||||
[actions](../config-actions.md) and a *fake* dotfile.
|
||||
|
||||
Let's say, for example, you have a list of directories you want to link
|
||||
from under `~/.original` to `~/symlinks`.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Merge files on install
|
||||
|
||||
Dotdrop allows you to merge multiple files into one using Jinja2's `include` directive.
|
||||
Dotdrop allows to merge multiple files into one using Jinja2's `include` directive.
|
||||
|
||||
For example, let's assume you want to keep your `.vimrc` split into multiple parts in dotdrop:
|
||||
* `<dotpath>/vimrc.d/top`: top part of the file
|
||||
@@ -48,12 +48,12 @@ Dotdrop will then automagically include the files into your vimrc when handling
|
||||
## Merge all files in a directory
|
||||
|
||||
To include all files in a directory, a combination of
|
||||
[dynvariables](../config-details.md#dynvariables-entry)
|
||||
[dynvariables](../config-dynvars.md)
|
||||
and [Jinja2 directives](https://jinja.palletsprojects.com/en/2.11.x/) have to be used.
|
||||
|
||||
Let's say all files in `<dotpath>/toinclude` need to be included into a dotfile.
|
||||
|
||||
First define a [dynvariables](../config-details.md#dynvariables-entry)
|
||||
First define a [dynvariables](../config-dynvars.md)
|
||||
in the config file which will look for files to include in the above directory:
|
||||
```yaml
|
||||
dynvariables:
|
||||
|
||||
@@ -1,12 +1,12 @@
|
||||
# Prompt user for variables
|
||||
|
||||
With the use of [uservariables](../config-details.md#uservariables-entry),
|
||||
With the use of [uservariables](../config-uservars.md),
|
||||
one can define specific variables that need to be initially filled in manually
|
||||
by the user on first run.
|
||||
|
||||
The provided values are then automatically saved by dotdrop to `uservariables.yaml`,
|
||||
which can be included in the main config as a file from which variables are imported
|
||||
using [import_variables](../config-details.md#import_variables-entry).
|
||||
using [import_variables](../config-config.md).
|
||||
|
||||
Let's say, for example, that you want to manually provide the email value
|
||||
on new hosts you deploy your dotfiles to.
|
||||
|
||||
@@ -19,7 +19,7 @@ trans_read:
|
||||
_gpg: gpg2 -q --for-your-eyes-only --no-tty -d {0} > {1}
|
||||
```
|
||||
|
||||
The above config allows you to store the dotfile `~/.secret` encrypted in the *dotpath*
|
||||
The above config allows to store the dotfile `~/.secret` encrypted in the *dotpath*
|
||||
directory and uses gpg to decrypt it when `install` is run.
|
||||
|
||||
Here's how to deploy the above solution:
|
||||
@@ -47,7 +47,7 @@ $ cp <encrypted-version-of-secret> dotfiles/secret
|
||||
|
||||
* Commit and push the changes
|
||||
|
||||
See [transformations](../config-details.md#transformations-entry).
|
||||
See [transformations](../config-transformations.md).
|
||||
|
||||
## Load passphrase from file
|
||||
|
||||
@@ -67,4 +67,4 @@ trans_read:
|
||||
_gpg: "gpg2 --batch --yes --passphrase-file <(cat {{@@ gpg_password_file @@}}) -q --for-your-eyes-only --no-tty -d {0} > {1}"
|
||||
```
|
||||
|
||||
See [transformations](../config-details.md#transformations-entry).
|
||||
See [transformations](../config-transformations.md).
|
||||
|
||||
@@ -66,7 +66,7 @@ export DB_PORT='4521'
|
||||
The previous method, albeit flexible, is a bit cumbersome for some use cases.
|
||||
For example, when the dotfiles belong to different profiles, the cleanest
|
||||
solution consists of using
|
||||
[profile variables](../config-details.md#profile-variables-entry). This is achieved by:
|
||||
[profile variables](../config-profiles.md#profile-variables-entry). This is achieved by:
|
||||
|
||||
1. Creating the merged dotfile with an arbitrary name somewhere in `dotpath`.
|
||||
2. Adding some variables in the merged dotfile via templating.
|
||||
|
||||
@@ -86,7 +86,7 @@ after autoload plugged plugin snippets spell swap vimrc
|
||||
As a result, all files under `~/.vim` will be managed by
|
||||
dotdrop (including unwanted directories like `spell`, `swap`, etc.).
|
||||
|
||||
A cleaner solution is to use `link_children` which allows you to only symlink
|
||||
A cleaner solution is to use `link_children` which allows to only symlink
|
||||
files under the dotfile directory. Let's say only `after`, `plugin`, `snippets`, and `vimrc`
|
||||
need to be managed in dotdrop. `~/.vim` is imported in dotdrop and cleaned of all unwanted
|
||||
files/directories, and then the `link` entry is set to `link_children` in the config file:
|
||||
@@ -121,10 +121,10 @@ $ tree -L 1 ~/.vim
|
||||
## Templating symlinked dotfiles
|
||||
|
||||
Dotfiles not using any templating directives are directly linked
|
||||
to dotdrop's `dotpath` directory (see [Config](../config.md)).
|
||||
to dotdrop's `dotpath` directory (see [the config file doc](../config-file.md)).
|
||||
|
||||
When using templating directives, however, the dotfiles are first installed into
|
||||
`workdir` (defaults to *~/.config/dotdrop*; see [Config format](../config-format.md))
|
||||
`workdir` (defaults to *~/.config/dotdrop*; see [the doc](../config-config.md))
|
||||
and then symlinked there.
|
||||
This applies to both dotfiles with `link: link` and `link: link_children`.
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Manage system dotfiles
|
||||
|
||||
Dotdrop doesn't allow you to handle file owernership (at least not directly). Every file operation (create/copy file/directory, create symlinks, etc.) is executed with the rights of the user calling dotdrop.
|
||||
Dotdrop doesn't allow to handle file owernership (at least not directly). Every file operation (create/copy file/directory, create symlinks, etc.) is executed with the rights of the user calling dotdrop.
|
||||
|
||||
Using dotdrop with `sudo` to manage unprivileged and privileged files in the same *session* is a bad idea as the resulting files will all have messed-up owners.
|
||||
|
||||
|
||||
@@ -38,9 +38,9 @@ shell with the config file path; for example:
|
||||
alias dotdrop=<absolute-path-to-dotdrop.sh> --cfg=<path-to-your-config.yaml>'
|
||||
```
|
||||
|
||||
## As a submodule in a virtualenv
|
||||
### As a submodule in a virtualenv
|
||||
|
||||
To install in a [virtualenv](https://virtualenv.pypa.io):
|
||||
To install it in a [virtualenv](https://virtualenv.pypa.io):
|
||||
```bash
|
||||
## create the repository
|
||||
$ mkdir dotfiles; cd dotfiles
|
||||
@@ -66,6 +66,46 @@ $ ./dotdrop.sh --help
|
||||
|
||||
Then follow the instructions under [As a submodule](#as-a-submodule).
|
||||
|
||||
### Upgrade dotdrop submodule
|
||||
|
||||
If using dotdrop as a submodule, one can control if dotdrop
|
||||
is auto-updated through the [dotdrop.sh](https://github.com/deadc0de6/dotdrop/blob/master/dotdrop.sh)
|
||||
script by defining the environment variable `DOTDROP_AUTOUPDATE=yes`.
|
||||
If undefined, `DOTDROP_AUTOUPDATE` will take the value `yes`.
|
||||
|
||||
If used as a submodule, update it with:
|
||||
```bash
|
||||
$ git submodule update --init --recursive
|
||||
$ git submodule update --remote dotdrop
|
||||
```
|
||||
|
||||
You will then need to commit the changes with:
|
||||
```bash
|
||||
$ git add dotdrop
|
||||
$ git commit -m 'update dotdrop'
|
||||
$ git push
|
||||
```
|
||||
|
||||
### Downgrade dotdrop submodule
|
||||
|
||||
If you wish to get a specific version of dotdrop when using
|
||||
it as a submodule, the following operations can be done.
|
||||
|
||||
Here dotdrop is downgraded to the latest stable version:
|
||||
```bash
|
||||
## enter the repository containing the dotdrop submodule
|
||||
$ cd my-dotfiles
|
||||
## enter the dotdrop submodule
|
||||
$ cd dotdrop
|
||||
## update the list of tags
|
||||
$ git fetch --tags
|
||||
## checkout the latest stable version
|
||||
$ git checkout `git tag -l | tail -1`
|
||||
```
|
||||
|
||||
If using the `dotdrop.sh` script, make sure it doesn't
|
||||
automatically update dotdrop back to the latest commit.
|
||||
|
||||
## PyPI package
|
||||
|
||||
Install dotdrop:
|
||||
@@ -73,9 +113,7 @@ Install dotdrop:
|
||||
$ pip3 install dotdrop --user
|
||||
```
|
||||
|
||||
and then [set up your repository](repository-setup.md).
|
||||
|
||||
## PyPI package in a virtualenv
|
||||
### PyPI package in a virtualenv
|
||||
|
||||
Install dotdrop from PyPI in a virtualenv:
|
||||
```bash
|
||||
@@ -109,8 +147,6 @@ Dotdrop is available on aur:
|
||||
|
||||
Make sure to install the [python-magic-ahupp](https://aur.archlinux.org/packages/python-magic-ahupp/) from aur.
|
||||
|
||||
Then follow the [doc to setup your repository](repository-setup.md).
|
||||
|
||||
## Snap package
|
||||
|
||||
Dotdrop is available as a snap package: <https://snapcraft.io/dotdrop>.
|
||||
@@ -120,8 +156,6 @@ Install it with:
|
||||
snap install dotdrop
|
||||
```
|
||||
|
||||
Then follow the [doc to setup your repository](repository-setup.md).
|
||||
|
||||
If you encounter warnings like `Warning: using regular magic file`,
|
||||
try defining the following environment variable:
|
||||
```bash
|
||||
@@ -148,7 +182,7 @@ $ ./dotdrop.sh --cfg <my-config-file> files
|
||||
Beside the Python dependencies defined in [requirements.txt](https://github.com/deadc0de6/dotdrop/blob/master/requirements.txt),
|
||||
dotdrop depends on the following tools:
|
||||
|
||||
* `diff` (unless a different tool is used, see [diff_command](config-format.md#config-entry))
|
||||
* `diff` (unless a different tool is used, see [diff_command](config-config.md#config-entry))
|
||||
* `git` (only if using the entry point script [dotdrop.sh](https://github.com/deadc0de6/dotdrop/blob/master/dotdrop.sh))
|
||||
* `readlink` or `realpath` (only if using the entry point script [dotdrop.sh](https://github.com/deadc0de6/dotdrop/blob/master/dotdrop.sh))
|
||||
|
||||
@@ -162,46 +196,6 @@ For WSL (Windows Subsystem for Linux), make sure to install `python-magic-bin`:
|
||||
pip install python-magic-bin
|
||||
```
|
||||
|
||||
## Update dotdrop submodule
|
||||
|
||||
If using dotdrop as a submodule, one can control if dotdrop
|
||||
is auto-updated through the [dotdrop.sh](https://github.com/deadc0de6/dotdrop/blob/master/dotdrop.sh)
|
||||
script by defining the environment variable `DOTDROP_AUTOUPDATE=yes`.
|
||||
If undefined, `DOTDROP_AUTOUPDATE` will take the value `yes`.
|
||||
|
||||
If used as a submodule, update it with:
|
||||
```bash
|
||||
$ git submodule update --init --recursive
|
||||
$ git submodule update --remote dotdrop
|
||||
```
|
||||
|
||||
You will then need to commit the changes with:
|
||||
```bash
|
||||
$ git add dotdrop
|
||||
$ git commit -m 'update dotdrop'
|
||||
$ git push
|
||||
```
|
||||
|
||||
## Downgrade dotdrop submodule
|
||||
|
||||
If you wish to get a specific version of dotdrop when using
|
||||
it as a submodule, the following operations can be done.
|
||||
|
||||
Here dotdrop is downgraded to the latest stable version:
|
||||
```bash
|
||||
## enter the repository containing the dotdrop submodule
|
||||
$ cd my-dotfiles
|
||||
## enter the dotdrop submodule
|
||||
$ cd dotdrop
|
||||
## update the list of tags
|
||||
$ git fetch --tags
|
||||
## checkout the latest stable version
|
||||
$ git checkout `git tag -l | tail -1`
|
||||
```
|
||||
|
||||
If using the `dotdrop.sh` script, make sure it doesn't
|
||||
automatically update dotdrop back to the latest commit.
|
||||
|
||||
## Shell completion
|
||||
|
||||
Completion scripts exist for `bash`, `zsh` and `fish`;
|
||||
|
||||
@@ -6,9 +6,9 @@ or the below sections for more information on how to template your dotfiles.
|
||||
|
||||
## Templating or not templating
|
||||
|
||||
The dotfile config entry [template](config-format.md#dotfiles-entry)
|
||||
and the global config entry [template_dotfile_default](config-format.md#config-entry)
|
||||
allow you to control whether a dotfile is processed by the templating engine.
|
||||
The dotfile config entry [template](config-dotfiles.md#dotfiles-entry)
|
||||
and the global config entry [template_dotfile_default](config-config.md)
|
||||
allow to control whether a dotfile is processed by the templating engine.
|
||||
|
||||
Obviously, if the dotfile uses template directives, it needs to be templated. However, if it
|
||||
is not, disabling templating will speed up its installation (since it won't have to be
|
||||
@@ -38,16 +38,16 @@ The following variables are available in templates:
|
||||
* `{{@@ profile @@}}` contains the profile provided to dotdrop.
|
||||
* `{{@@ env['MY_VAR'] @@}}` contains environment variables (see [Environment variables](#environment-variables)).
|
||||
* `{{@@ header() @@}}` contains the dotdrop header (see [Dotdrop header](#dotdrop-header)).
|
||||
* `{{@@ _dotdrop_dotpath @@}}` contains the [dotpath](config-format.md) absolute path.
|
||||
* `{{@@ _dotdrop_cfgpath @@}}` contains the absolute path to the [config file](config.md).
|
||||
* `{{@@ _dotdrop_workdir @@}}` contains the [workdir](config-format.md) absolute path.
|
||||
* `{{@@ _dotdrop_dotpath @@}}` contains the [dotpath](config-config.md) absolute path.
|
||||
* `{{@@ _dotdrop_cfgpath @@}}` contains the absolute path to the [config file](config-file.md).
|
||||
* `{{@@ _dotdrop_workdir @@}}` contains the [workdir](config-config.md) absolute path.
|
||||
* Dotfile specific variables (see [Dotfile variables](#dotfile-variables))
|
||||
* All defined config variables (see [Variables](config.md#variables))
|
||||
* All defined config interpreted variables (see [Interpreted variables](config-details.md#dynvariables-entry))
|
||||
* All defined config variables (see [Variables](config-file.md#variables))
|
||||
* All defined config interpreted variables (see [Interpreted variables](config-dynvars.md#dynvariables-entry))
|
||||
|
||||
## Dotfile variables
|
||||
|
||||
When a dotfile is handled by dotdrop, the following variables are added:
|
||||
When a dotfile is handled by dotdrop, the following variables are also available for templating:
|
||||
|
||||
* `{{@@ _dotfile_abs_src @@}}` contains the processed dotfile absolute source path.
|
||||
* `{{@@ _dotfile_abs_dst @@}}` contains the processed dotfile absolute destination path.
|
||||
@@ -73,7 +73,7 @@ It's possible to access environment variables inside the templates:
|
||||
```
|
||||
|
||||
This allows for storing host-specific properties and/or secrets in environment variables.
|
||||
It is recommended to use `variables` (see [config variables](config.md#variables))
|
||||
It is recommended to use `variables` (see [config variables](config-file.md#variables))
|
||||
instead of environment variables unless these contain sensitive information that
|
||||
shouldn't be versioned in Git.
|
||||
|
||||
@@ -192,7 +192,7 @@ For more information, see the [dedicated Jinja2 docs](https://jinja.palletsproje
|
||||
|
||||
## Dotdrop header
|
||||
|
||||
Dotdrop is able to insert a header in the generated dotfiles. This allows you
|
||||
Dotdrop is able to insert a header in the generated dotfiles. This allows
|
||||
to remind anyone opening the file for editing that this file is managed by dotdrop.
|
||||
|
||||
Here's what it looks like:
|
||||
|
||||
109
docs/usage.md
109
docs/usage.md
@@ -2,21 +2,6 @@
|
||||
|
||||
Run `dotdrop --help` to see all available options.
|
||||
|
||||
## Basic usage
|
||||
|
||||
The basic use of dotdrop is:
|
||||
|
||||
* Import a file/directory to manage (this will copy the files from the filesystem to your `dotpath`): `dotdrop import <somefile>`
|
||||
* Install the dotfiles (this will *copy/link* them from your `dotpath` to the filesystem): `dotdrop install`
|
||||
|
||||
Then if you happen to update the file/directory directly on the filesystem (add a new file/dir, edit content, etc.) you can use the `update` command to mirror back those changes in dotdrop.
|
||||
|
||||
For more advanced uses:
|
||||
|
||||
* `dotdrop --help` for the CLI usage.
|
||||
* [The example](https://github.com/deadc0de6/dotdrop#getting-started)
|
||||
* [The howto](howto/howto.md)
|
||||
|
||||
## Profile
|
||||
|
||||
The default profile used by dotdrop is the *hostname* of the host you are running dotdrop on.
|
||||
@@ -26,6 +11,20 @@ It can be changed:
|
||||
* Using the command line switch `-p`/`--profile=<profile>`
|
||||
* By defining it in the env variable `DOTDROP_PROFILE`
|
||||
|
||||
## List profiles
|
||||
|
||||
The `profiles` command lists the profiles defined in the config file.
|
||||
```bash
|
||||
$ dotdrop profiles
|
||||
```
|
||||
|
||||
Dotdrop allows to choose which profile to use
|
||||
with the `--profile` switch if you use something
|
||||
other than the default (the hostname).
|
||||
|
||||
The default profile can also be changed by defining the
|
||||
`DOTDROP_PROFILE` environment variable.
|
||||
|
||||
## Import dotfiles
|
||||
|
||||
The `import` command imports dotfiles to be managed by dotdrop.
|
||||
@@ -42,11 +41,11 @@ $ dotdrop import ~/.xinitrc
|
||||
```
|
||||
|
||||
You can control how the dotfile key is generated in the config file
|
||||
with the following config entries:
|
||||
with the following [config entries](config-config.md):
|
||||
|
||||
* `longkey`
|
||||
* *short format* (default): take the shortest unique path
|
||||
* *long format*: take the full path
|
||||
* `false` (default): take the shortest unique path
|
||||
* `true` take the full path
|
||||
* `key_prefix`: defines if the key is prefixed with `f<key_separator>` for file and `d<key_separator>` for directory
|
||||
* `key_separator`: defines the separator to use (defaults to `_`)
|
||||
|
||||
@@ -69,7 +68,7 @@ dotfile management.
|
||||
$ dotdrop import ~/.zshrc --as=~/.zshrc.test
|
||||
```
|
||||
|
||||
To ignore specific patterns during import, see [the ignore patterns](config.md#ignore-patterns).
|
||||
To ignore specific patterns during import, see [the ignore patterns](config-file.md#ignore-patterns).
|
||||
|
||||
For more options, see the usage with `dotdrop --help`.
|
||||
|
||||
@@ -86,11 +85,11 @@ Some available options:
|
||||
|
||||
* `-t`/`--temp`: Install the dotfile(s) to a temporary directory for review (helping to debug templating issues, for example).
|
||||
Note that actions are not executed in this 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 (see [Fake dotfile and actions](config-actions.md#fake-dotfile-and-actions) as an alternative)
|
||||
* `-f`/`--force`: Do not ask for any confirmation
|
||||
* `-W`/`--workdir-clear`: Clear the `workdir` before installing dotfiles (see config entry `clear_workdir`)
|
||||
* `-W`/`--workdir-clear`: Clear the `workdir` before installing dotfiles (see [the config entry](config-config.md) `clear_workdir`)
|
||||
|
||||
To ignore specific patterns during installation, see [the ignore patterns](config.md#ignore-patterns).
|
||||
To ignore specific patterns during installation, see [the ignore patterns](config-file.md#ignore-patterns).
|
||||
|
||||
For more options, see the usage with `dotdrop --help`.
|
||||
|
||||
@@ -102,36 +101,22 @@ $ dotdrop compare
|
||||
```
|
||||
|
||||
The diffing is done with the UNIX tool `diff` as the backend; one can provide a specific
|
||||
diff command using the config entry `diff_command`.
|
||||
diff command using [the config entry](config-config.md) `diff_command`.
|
||||
|
||||
You can specify against which destination file to compare:
|
||||
```bash
|
||||
$ dotdrop compare -C ~/.vimrc
|
||||
```
|
||||
|
||||
To ignore specific patterns, see [the ignore patterns](config.md#ignore-patterns).
|
||||
To ignore specific patterns, see [the ignore patterns](config-file.md#ignore-patterns).
|
||||
|
||||
To completely ignore all files not present in `dotpath` see [Ignore missing](#ignore-missing).
|
||||
To completely ignore all files not present in `dotpath` see [Ignore missing](config-file.md#ignore-missing).
|
||||
|
||||
If you want to get notified on files present in the `workdir` but not tracked
|
||||
by dotdrop see the [compare_workdir](config-format.md).
|
||||
by dotdrop see the [compare_workdir](config-config.md).
|
||||
|
||||
For more options, see the usage with `dotdrop --help`.
|
||||
|
||||
## List profiles
|
||||
|
||||
The `profiles` command lists the profiles defined in the config file.
|
||||
```bash
|
||||
$ dotdrop profiles
|
||||
```
|
||||
|
||||
Dotdrop allows you to choose which profile to use
|
||||
with the `--profile` switch if you use something
|
||||
other than the default (the hostname).
|
||||
|
||||
The default profile can also be changed by defining the
|
||||
`DOTDROP_PROFILE` environment variable.
|
||||
|
||||
## List dotfiles
|
||||
|
||||
The `files` command lists the dotfiles declared for a specific profile.
|
||||
@@ -180,13 +165,16 @@ $ dotdrop update --key f_vimrc
|
||||
|
||||
If not argument is provided, all dotfiles for the selected profile are updated.
|
||||
|
||||
To ignore specific patterns, see [the dedicated page](config.md#ignore-patterns).
|
||||
To ignore specific patterns, see [the dedicated page](config-file.md#ignore-patterns).
|
||||
|
||||
To completely ignore all files not present in `dotpath`, see [Ignore missing](#ignore-missing).
|
||||
To completely ignore all files not present in `dotpath`, see [Ignore missing](config-file.md#ignore-missing).
|
||||
|
||||
There are two cases when updating a dotfile:
|
||||
|
||||
### The dotfile doesn't use [templating](templating.md)
|
||||
* [The dotfile does not use templating](#the-dotfile-does-not-use-templating)
|
||||
* [The dotfile uses templating](#the-dotfile-uses-templating)
|
||||
|
||||
### The dotfile does not use [templating](templating.md)
|
||||
|
||||
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
|
||||
@@ -229,17 +217,17 @@ $ diff ~/.vimrc /tmp/dotdrop-6ajz7565/home/user/.vimrc
|
||||
|
||||
## Remove dotfiles
|
||||
|
||||
The command `remove` allows you to stop managing a specific dotfile with
|
||||
The command `remove` allows to stop managing a specific dotfile with
|
||||
dotdrop. It will:
|
||||
|
||||
* remove the entry from the config file (under `dotfiles` and `profile`)
|
||||
* remove the file from the `dotpath`
|
||||
* delete the file from the `dotpath`
|
||||
|
||||
For more options, see the usage with `dotdrop --help`.
|
||||
|
||||
## Concurrency
|
||||
|
||||
The command line switch `-w`/`--workers`, if set to a value greater than one, allows you to use
|
||||
The command line switch `-w`/`--workers`, if set to a value greater than one, allowing to use
|
||||
multiple concurrent workers to execute an operation. It can be applied to the following
|
||||
commands:
|
||||
|
||||
@@ -296,32 +284,3 @@ export DOTDROP_WORKDIR="/tmp/dotdrop-workdir"
|
||||
```bash
|
||||
export DOTDROP_WORKERS="10"
|
||||
```
|
||||
|
||||
## Ignore missing
|
||||
|
||||
Sometimes, it is nice to have [`update`](#update-dotfiles) not copy all the files in the installed directory
|
||||
or [`compare`](#compare-dotfiles) diff them.
|
||||
|
||||
For example,
|
||||
maybe you only want to include a single configuration file in your repository
|
||||
and don't want to include other files the program uses,
|
||||
such as a cache.
|
||||
Maybe you only want to change one file and don't want the others cluttering your repository.
|
||||
Maybe the program changes these files quite often and creates unnecessary diffs in your dotfiles.
|
||||
|
||||
In these cases, you can use the [ignore-missing](config-format.md) option.
|
||||
This option is available as a flag (`--ignore-missing` or `-z`) to the `update` and `compare` commands,
|
||||
or [as a configuration option either globally or on a specific dotfile](config-format.md).
|
||||
|
||||
To configure globally, place the following in `config.yaml`:
|
||||
```yaml
|
||||
config:
|
||||
ignore_missing_in_dotdrop: true
|
||||
```
|
||||
|
||||
To configure per dotfile:
|
||||
```yaml
|
||||
dotfiles:
|
||||
f_abc:
|
||||
ignore_missing_in_dotdrop: true
|
||||
```
|
||||
|
||||
27
mkdocs.yml
27
mkdocs.yml
@@ -9,15 +9,24 @@ theme:
|
||||
collapse_navigation: false
|
||||
use_directory_urls: true
|
||||
nav:
|
||||
- Dotdrop: 'README.md'
|
||||
- Installation: 'installation.md'
|
||||
- 'Repository setup': 'repository-setup.md'
|
||||
- Usage: 'usage.md'
|
||||
- Config: 'config.md'
|
||||
- 'Config format': 'config-format.md'
|
||||
- 'Config details': 'config-details.md'
|
||||
- Templating: 'templating.md'
|
||||
- HowTo: 'howto/howto.md'
|
||||
- 'Dotdrop': 'README.md'
|
||||
- 'Installation': 'installation.md'
|
||||
- 'Getting started': 'getting-started.md'
|
||||
- 'Usage': 'usage.md'
|
||||
- 'Config':
|
||||
- 'Config file': 'config-file.md'
|
||||
- 'Config': 'config-config.md'
|
||||
- 'Dotfiles': 'config-dotfiles.md'
|
||||
- 'Profiles': 'config-profiles.md'
|
||||
- 'Actions': 'config-actions.md'
|
||||
- 'Transformations': 'config-transformations.md'
|
||||
- 'Variables': 'config-variables.md'
|
||||
- 'Dynvariables': 'config-dynvars.md'
|
||||
- 'Uservariables': 'config-uservars.md'
|
||||
- 'Templating':
|
||||
- 'Templating': 'templating.md'
|
||||
- 'More':
|
||||
- 'HowTo': 'howto/howto.md'
|
||||
markdown_extensions:
|
||||
- meta
|
||||
- tables
|
||||
|
||||
Reference in New Issue
Block a user