From 067f7eea7b126740246d009995d609f797787b84 Mon Sep 17 00:00:00 2001 From: deadc0de6 Date: Fri, 18 Sep 2020 10:04:00 +0200 Subject: [PATCH] update doc --- docs/config-details.md | 11 +++++++---- docs/config-format.md | 3 +++ docs/config.md | 14 +++++++++++++- docs/installation.md | 1 + docs/usage.md | 9 +++++---- 5 files changed, 29 insertions(+), 9 deletions(-) diff --git a/docs/config-details.md b/docs/config-details.md index 3503127..64abfaf 100644 --- a/docs/config-details.md +++ b/docs/config-details.md @@ -10,7 +10,7 @@ Four types of actions can be defined: * [Profile actions](#profile-actions) * [Fake dotfiles and actions](#fake-dotfile-and-actions) -### Dotfile actions +#### Dotfile actions It is sometimes useful to execute some kind of action when deploying a dotfile. @@ -119,7 +119,7 @@ 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 +#### Default actions Dotdrop allows to execute an action for any dotfile installation. These actions work as any other action (*pre* or *post*). @@ -145,13 +145,13 @@ profiles: - f_vimrc ``` -### Profile actions +#### Profile actions Profile can be either `pre` or `post` actions. Those are executed before any dotfile installation (for `pre`) and after all dotfiles installation (for `post`) only if at least one dotfile has been installed. -### Fake dotfile and actions +#### Fake dotfile 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 @@ -338,6 +338,9 @@ profiles: - "profile_{{@@ var1 @@}}" ``` +Note that profile cannot include other profiles defined above in +the import tree (profile exists in another file and is imported using `import_configs` for example). + ## Entry profile import Profile's dotfiles list can be loaded from external files diff --git a/docs/config-format.md b/docs/config-format.md index 057bdac..372764d 100644 --- a/docs/config-format.md +++ b/docs/config-format.md @@ -2,6 +2,9 @@ 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 diff --git a/docs/config.md b/docs/config.md index 231bf80..d20a95e 100644 --- a/docs/config.md +++ b/docs/config.md @@ -26,6 +26,7 @@ parametrize following elements of the config: * `import_actions` * `import_configs` * profiles's `import` + * profiles's `include` `actions` and `transformations` also support the use of variables but those are resolved when the action/transformation is executed @@ -40,7 +41,18 @@ Following variables are available in the config files: * environment variables: `{{@@ env['MY_VAR'] @@}}` * dotdrop header: `{{@@ header() @@}}` (see [Dotdrop header](templating.md#dotdrop-header)) -As well as all template methods (see [Available methods](templating.md#template-methods)) +As well as all [template methods](templating.md#template-methods) and [template filters](templating.md#template-filters). + +Note that all variables available in the config file will +then be available during [templating](templating.md). + +Here are some rules on the use of variables in configs: + +* [interpreted variables](config-details.md#entry-dynvariables) are executed in their own file +* [interpreted variables](config-details.md#entry-dynvariables) and + [variables](config-details.md#entry-variables) are templated before + [interpreted variables](config-details.md#entry-dynvariables) are executed +* config files do not have access to variables defined above in the import tree ## Symlink dotfiles diff --git a/docs/installation.md b/docs/installation.md index cd232cf..83707d1 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -96,6 +96,7 @@ Then follow the instructions under [Pypi package](#pypi-package). ## Aur packages Dotdrop is available on aur: + * stable: * git version: diff --git a/docs/usage.md b/docs/usage.md index 6f6e66d..b19d33e 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -9,7 +9,7 @@ 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 ` * install the dotfiles (will *copy/link* those from your `dotpath` to the filesystem): `dotdrop install` -Then if you happen to update the file/directory directly on the filesystem (add new file/dir, edit content, etc) you can use `update` to mirror back those changes in the `dotpath` of dotdrop. +Then if you happen to update the file/directory directly on the filesystem (add new file/dir, edit content, etc) you can use `update` to mirror back those changes in dotdrop. For more advanced uses: @@ -56,7 +56,7 @@ filesystem. It will copy the dotfile and update the config file automatically. Note that dotdrop will dereference all symlinks -when importing a file or directory (see [issue #184](https://github.com/deadc0de6/dotdrop/issues/184) for more) +when importing a file or directory. For example to import `~/.xinitrc` ```bash @@ -82,8 +82,9 @@ Importing `~/.mutt/colors` and then `~/.vim/colors` will result in * `d_mutt_colors` and `d_vim_colors` in the long format Dotfile can be imported as a different file with the use -of the command line switch `--as`. It is however recommended -to use the [[templating]] to avoid duplicates and optimize +of the command line switch `--as` (effectively selecting the `src` part +of the dotfile in the config). It is however recommended +to use [templating](templating.md) to avoid duplicates and optimize dotfiles management. ```bash $ dotdrop import ~/.zshrc --as=~/.zshrc.test