mirror of
https://github.com/deadc0de6/dotdrop.git
synced 2026-02-04 16:49:42 +00:00
template doc
This commit is contained in:
deadc0de6
2
docs/config/config-actions.md
vendored
2
docs/config/config-actions.md
vendored
@@ -64,7 +64,7 @@ dotfiles:
|
||||
## Dynamic actions
|
||||
|
||||
Variables ([config variables and dynvariables](config-file.md#variables)
|
||||
and [template variables](../templating.md#template-variables)) can be used
|
||||
and [template variables](../template/template-variables.md)) can be used
|
||||
in actions for more advanced use-cases.
|
||||
|
||||
```yaml
|
||||
|
||||
4
docs/config/config-config.md
vendored
4
docs/config/config-config.md
vendored
@@ -15,9 +15,9 @@ Entry | Description | Default
|
||||
`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)) | -
|
||||
`filter_file` | List of paths to load templating filters from (See [Templating available filters](../template/template-filters.md)) | -
|
||||
`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)) | -
|
||||
`func_file` | List of paths to load templating functions from (See [Templating available methods](../template/template-methods.md)) | -
|
||||
`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)) | -
|
||||
|
||||
12
docs/config/config-file.md
vendored
12
docs/config/config-file.md
vendored
@@ -35,7 +35,7 @@ parametrize the following elements of the config:
|
||||
Note that variables used in `actions` and `transformations`
|
||||
are resolved when the action/transformation is executed
|
||||
(See [Dynamic actions](config-actions.md#dynamic-actions),
|
||||
[Dynamic transformations](config-transformations.md#dynamic-transformations) and [Templating](../templating.md)).
|
||||
[Dynamic transformations](config-transformations.md#dynamic-transformations) and [Templating](../template/templating.md)).
|
||||
|
||||
The following variables are available in the config files:
|
||||
|
||||
@@ -44,13 +44,13 @@ The following variables are available in the config files:
|
||||
* [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'] @@}}`
|
||||
* The [enriched variables](../templating.md#enriched-variables)
|
||||
* Dotdrop header: `{{@@ header() @@}}` (see [Dotdrop header](../templating.md#dotdrop-header))
|
||||
* The [enriched variables](../template/template-variables.md#enriched-variables)
|
||||
* Dotdrop header: `{{@@ header() @@}}` (see [Dotdrop header](../template/templating.md#dotdrop-header))
|
||||
|
||||
as well as all [template methods](../templating.md#template-methods) and [template filters](../templating.md#template-filters).
|
||||
as well as all [template methods](../template/template-methods.md) and [template filters](../template/template-filters.md).
|
||||
|
||||
Note that all variables available in the config file will
|
||||
then be available during [templating](../templating.md).
|
||||
then be available during [templating](../template/templating.md).
|
||||
|
||||
Here are some rules on the use of variables in configs:
|
||||
|
||||
@@ -120,7 +120,7 @@ see the [symlink dotfiles documentation](../howto/symlink-dotfiles.md).
|
||||
|
||||
## Template config entries
|
||||
|
||||
Some entries in the config can be templated (See [templating](../templating.md)):
|
||||
Some entries in the config can be templated (See [templating](../template/templating.md)):
|
||||
|
||||
Entry | Related doc
|
||||
-------- | -------------
|
||||
|
||||
4
docs/config/config-transformations.md
vendored
4
docs/config/config-transformations.md
vendored
@@ -19,7 +19,7 @@ There are two types of transformations available:
|
||||
* They have two mandatory 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))
|
||||
* This Happens **before** the dotfile is templated (see [templating](../template/templating.md))
|
||||
|
||||
* **Write transformations**: used to transform files before updating a dotfile ([config](config-config.md) key `trans_write`)
|
||||
* Used for command `update` and `import`
|
||||
@@ -73,7 +73,7 @@ trans_write:
|
||||
|
||||
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)).
|
||||
and [template variables](../template/template-variables.md#template-variables)).
|
||||
|
||||
A very dumb example:
|
||||
```yaml
|
||||
|
||||
2
docs/howto/merge-files-when-installing.md
vendored
2
docs/howto/merge-files-when-installing.md
vendored
@@ -61,7 +61,7 @@ dynvariables:
|
||||
```
|
||||
|
||||
Note that `_dotdrop_dotpath` is part of the built-in variables
|
||||
(For more, see [template variables](../templating.md#template-variables)).
|
||||
(For more, see [template variables](../template/template-variables.md#template-variables)).
|
||||
|
||||
Then use the generated list in the dotfile template:
|
||||
```
|
||||
|
||||
4
docs/howto/sensitive-dotfiles.md
vendored
4
docs/howto/sensitive-dotfiles.md
vendored
@@ -27,9 +27,9 @@ alias dotdrop='eval $(grep -v "^#" ~/dotfiles/.env) /usr/bin/dotdrop --cfg=~/dot
|
||||
The above aliases load all the variables from `~/dotfiles/.env`
|
||||
(while omitting lines starting with `#`) before calling dotdrop.
|
||||
Defined variables can then be used [in the config](../config/config-file.md#template-config-entries)
|
||||
or [for templating dotfiles](../templating.md)
|
||||
or [for templating dotfiles](../template/templating.md)
|
||||
|
||||
For more see [the doc on environment variables](../templating.md#environment-variables).
|
||||
For more see [the doc on environment variables](../template/template-variables.md#environment-variables).
|
||||
|
||||
## Store encrypted dotfiles using GPG
|
||||
|
||||
|
||||
8
docs/template/template-debug.md
vendored
Normal file
8
docs/template/template-debug.md
vendored
Normal file
@@ -0,0 +1,8 @@
|
||||
## Debugging templates
|
||||
|
||||
To debug the result of a template, one can install the dotfiles to a temporary
|
||||
directory with the `install` command and the `-t` switch:
|
||||
```bash
|
||||
$ dotdrop install -t
|
||||
Installed to tmp /tmp/dotdrop-6ajz7565
|
||||
```
|
||||
27
docs/template/template-filters.md
vendored
Normal file
27
docs/template/template-filters.md
vendored
Normal file
@@ -0,0 +1,27 @@
|
||||
# Template filters
|
||||
|
||||
Besides [Jinja2 builtin filters](https://jinja.palletsprojects.com/en/2.11.x/templates/#builtin-filters),
|
||||
custom user-defined filter functions can be loaded using the config entry `filter_file`:
|
||||
|
||||
Example:
|
||||
|
||||
The config file:
|
||||
```yaml
|
||||
config:
|
||||
filter_file:
|
||||
- /tmp/myfilter_file.py
|
||||
```
|
||||
|
||||
The python filter under `/tmp/myfilter_file.py`:
|
||||
```python
|
||||
def myfilter(arg1):
|
||||
return str(int(arg1) - 10)
|
||||
```
|
||||
|
||||
The dotfile content:
|
||||
```
|
||||
{{@@ "13" | myfilter() @@}}
|
||||
```
|
||||
|
||||
For more information on how to create filters,
|
||||
see [the Jinja2 official docs](https://jinja.palletsprojects.com/en/2.11.x/api/#writing-filters).
|
||||
55
docs/template/template-methods.md
vendored
Normal file
55
docs/template/template-methods.md
vendored
Normal file
@@ -0,0 +1,55 @@
|
||||
# Template methods
|
||||
|
||||
Besides [Jinja2 global functions](https://jinja.palletsprojects.com/en/2.11.x/templates/#list-of-global-functions),
|
||||
the following methods can be used within templates:
|
||||
|
||||
* `exists(path)`: returns true when path exists
|
||||
```
|
||||
{%@@ if exists('/dev/null') @@%}
|
||||
it does exist
|
||||
{%@@ endif @@%}
|
||||
```
|
||||
|
||||
* `exists_in_path(name, path=None)`: returns true when executable exists in `$PATH`
|
||||
```
|
||||
{%@@ if exists_in_path('exa') @@%}
|
||||
alias ls='exa --git --color=always'
|
||||
{%@@ endif @@%}
|
||||
```
|
||||
|
||||
* `basename(path)`: returns the `basename` of the path argument
|
||||
```
|
||||
{%@@ set dotfile_filename = basename( _dotfile_abs_dst ) @@%}
|
||||
dotfile dst filename: {{@@ dotfile_filename @@}}
|
||||
```
|
||||
|
||||
* `dirname(path)`: returns the `dirname` of the path argument
|
||||
```
|
||||
{%@@ set dotfile_dirname = dirname( _dotfile_abs_dst ) @@%}
|
||||
dotfile dst dirname: {{@@ dotfile_dirname @@}}
|
||||
```
|
||||
|
||||
Custom user-defined functions can be loaded with the help of the
|
||||
config entry `func_file`.
|
||||
|
||||
Example:
|
||||
|
||||
The config file:
|
||||
```yaml
|
||||
config:
|
||||
func_file:
|
||||
- /tmp/myfuncs_file.py
|
||||
```
|
||||
|
||||
The python function under `/tmp/myfuncs_file.py`:
|
||||
```python
|
||||
def myfunc(arg):
|
||||
return not arg
|
||||
```
|
||||
|
||||
The dotfile content:
|
||||
```
|
||||
{%@@ if myfunc(False) @@%}
|
||||
this should exist
|
||||
{%@@ endif @@%}
|
||||
```
|
||||
59
docs/template/template-variables.md
vendored
Normal file
59
docs/template/template-variables.md
vendored
Normal file
@@ -0,0 +1,59 @@
|
||||
# Template variables
|
||||
|
||||
## Available variables
|
||||
|
||||
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](templating.md#dotdrop-header)).
|
||||
* `{{@@ _dotdrop_dotpath @@}}` contains the [dotpath](../config/config-config.md) absolute path.
|
||||
* `{{@@ _dotdrop_cfgpath @@}}` contains the [config file](../config/config-file.md) absolute path.
|
||||
* `{{@@ _dotdrop_workdir @@}}` contains the [workdir](../config/config-config.md) absolute path.
|
||||
* The [enriched variables](#enriched-variables)
|
||||
* Dotfile specific variables (see [Dotfile variables](#dotfile-variables))
|
||||
* All defined config variables (see [Variables](../config/config-file.md#variables))
|
||||
* All defined config interpreted variables (see [Interpreted variables](../config/config-dynvars.md#dynvariables-entry))
|
||||
|
||||
## Enriched variables
|
||||
|
||||
The below variables are added to the available variables within templates. If the variable
|
||||
is already set by the user (through the config file for example) it will not be overwritten.
|
||||
|
||||
* `{{@@ os @@}}` will contain the OS name as provided by <https://docs.python.org/3/library/platform.html#platform.system>
|
||||
* `{{@@ release @@}}` will contain the OS release version as provided by <https://docs.python.org/3/library/platform.html#platform.release>
|
||||
* `{{@@ distro_id @@}}` will contain the distribution ID as provided by <https://distro.readthedocs.io/en/latest/#distro.id>
|
||||
* `{{@@ distro_version @@}}` will contain the distribution version as provided by <https://distro.readthedocs.io/en/latest/#distro.version>
|
||||
* `{{@@ distro_like @@}}` will contain a space-separated list of distro IDs that are closely related to the current OS distro as provided by <https://distro.readthedocs.io/en/latest/#distro.like>
|
||||
|
||||
## Dotfile variables
|
||||
|
||||
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.
|
||||
* `{{@@ _dotfile_key @@}}` contains the processed dotfile key.
|
||||
* `{{@@ _dotfile_link @@}}` contains the processed dotfile `link` string value.
|
||||
|
||||
In addition to the above, the following variables are set in each file processed by dotdrop:
|
||||
|
||||
* `{{@@ _dotfile_sub_abs_src @@}}` contains the absolute source path of each file when handled by dotdrop.
|
||||
* `{{@@ _dotfile_sub_abs_dst @@}}` contains the absolute destination path of each file when handled by dotdrop.
|
||||
|
||||
For example, a directory dotfile (like `~/.ssh`) would process several files
|
||||
(`~/.ssh/config` and `~/.ssh/authorized_keys`, for example). In `~/.ssh/config`:
|
||||
|
||||
* `_dotfile_abs_dst` would be `/home/user/.ssh`
|
||||
* `_dotfile_sub_abs_dst` would be `/home/user/.ssh/config`
|
||||
|
||||
## Environment variables
|
||||
|
||||
It's possible to access environment variables inside the templates:
|
||||
```
|
||||
{{@@ env['MY_VAR'] @@}}
|
||||
```
|
||||
|
||||
This allows for storing host-specific properties and/or secrets in environment variables.
|
||||
It is recommended to use `variables` (see [config variables](../config/config-file.md#variables))
|
||||
instead of environment variables unless these contain sensitive information that
|
||||
shouldn't be versioned in Git (see [handle secrets doc](../howto/sensitive-dotfiles.md)).
|
||||
62
docs/template/templating.md
vendored
Normal file
62
docs/template/templating.md
vendored
Normal file
@@ -0,0 +1,62 @@
|
||||
# Templating
|
||||
|
||||
Dotdrop leverages the power of [Jinja2](https://palletsprojects.com/p/jinja/) to handle the
|
||||
templating of dotfiles. See [the Jinja2 templates docs](https://jinja.palletsprojects.com/en/2.11.x/templates/)
|
||||
or the below sections for more information on how to template your dotfiles.
|
||||
|
||||
## Templating or not templating
|
||||
|
||||
The dotfile config entry [template](../config/config-dotfiles.md#dotfiles-block)
|
||||
and the global config entry [template_dotfile_default](../config/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
|
||||
processed by the engine).
|
||||
|
||||
For dotfiles being symlinked (`absolute`, `relative` or `link_children`), see
|
||||
[the dedicated doc](../howto/symlink-dotfiles.md#templating-symlinked-dotfiles).
|
||||
|
||||
## Delimiters
|
||||
|
||||
Dotdrop uses different delimiters than
|
||||
[Jinja2](https://palletsprojects.com/p/jinja/)'s defaults:
|
||||
|
||||
* Block/statement start = `{%@@`
|
||||
* Block/statement end = `@@%}`
|
||||
* Variable/expression start = `{{@@`
|
||||
* Variable/expression end = `@@}}`
|
||||
* Comment start = `{#@@`
|
||||
* Comment end = `@@#}`
|
||||
|
||||
More info in [Jinja2 templating docs](https://jinja.palletsprojects.com/en/2.11.x/templates/?highlight=delimiter)
|
||||
|
||||
## Importing macros
|
||||
|
||||
Macros must be imported `with context` in order to have access to the variables:
|
||||
```
|
||||
{%@@ from 'macro_file' import macro with context @@%}
|
||||
```
|
||||
|
||||
For more information, see the [dedicated Jinja2 docs](https://jinja.palletsprojects.com/en/2.11.x/templates/#macros).
|
||||
|
||||
## Dotdrop header
|
||||
|
||||
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:
|
||||
```none
|
||||
This dotfile is managed using dotdrop
|
||||
```
|
||||
|
||||
The header can be automatically added with:
|
||||
```none
|
||||
{{@@ header() @@}}
|
||||
```
|
||||
|
||||
Properly commenting the header in templates is the responsibility of the user,
|
||||
as [Jinja2](https://palletsprojects.com/p/jinja/) has no way of knowing what is the proper char(s) used for comments.
|
||||
Either prepend the directive with the commenting char(s) used in the dotfile
|
||||
(for example `# {{@@ header() @@}}`) or provide it as an argument `{{@@ header('# ') @@}}`.
|
||||
The results are equivalent.
|
||||
213
docs/templating.md
vendored
213
docs/templating.md
vendored
@@ -1,213 +0,0 @@
|
||||
# Templating
|
||||
|
||||
Dotdrop leverages the power of [Jinja2](https://palletsprojects.com/p/jinja/) to handle the
|
||||
templating of dotfiles. See [the Jinja2 templates docs](https://jinja.palletsprojects.com/en/2.11.x/templates/)
|
||||
or the below sections for more information on how to template your dotfiles.
|
||||
|
||||
## Templating or not templating
|
||||
|
||||
The dotfile config entry [template](config/config-dotfiles.md#dotfiles-block)
|
||||
and the global config entry [template_dotfile_default](config/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
|
||||
processed by the engine).
|
||||
|
||||
For dotfiles being symlinked (`absolute`, `relative` or `link_children`), see
|
||||
[the dedicated doc](howto/symlink-dotfiles.md#templating-symlinked-dotfiles).
|
||||
|
||||
## Delimiters
|
||||
|
||||
Dotdrop uses different delimiters than
|
||||
[Jinja2](https://palletsprojects.com/p/jinja/)'s defaults:
|
||||
|
||||
* Block/statement start = `{%@@`
|
||||
* Block/statement end = `@@%}`
|
||||
* Variable/expression start = `{{@@`
|
||||
* Variable/expression end = `@@}}`
|
||||
* Comment start = `{#@@`
|
||||
* Comment end = `@@#}`
|
||||
|
||||
More info in [Jinja2 templating docs](https://jinja.palletsprojects.com/en/2.11.x/templates/?highlight=delimiter)
|
||||
|
||||
## Template variables
|
||||
|
||||
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/config-config.md) absolute path.
|
||||
* `{{@@ _dotdrop_cfgpath @@}}` contains the [config file](config/config-file.md) absolute path.
|
||||
* `{{@@ _dotdrop_workdir @@}}` contains the [workdir](config/config-config.md) absolute path.
|
||||
* The [enriched variables](#enriched-variables)
|
||||
* Dotfile specific variables (see [Dotfile variables](#dotfile-variables))
|
||||
* All defined config variables (see [Variables](config/config-file.md#variables))
|
||||
* All defined config interpreted variables (see [Interpreted variables](config/config-dynvars.md#dynvariables-entry))
|
||||
|
||||
## Enriched variables
|
||||
|
||||
The below variables are added to the available variables within templates. If the variable
|
||||
is already set by the user (through the config file for example) it will not be overwritten.
|
||||
|
||||
* `{{@@ os @@}}` will contain the OS name as provided by <https://docs.python.org/3/library/platform.html#platform.system>
|
||||
* `{{@@ release @@}}` will contain the OS release version as provided by <https://docs.python.org/3/library/platform.html#platform.release>
|
||||
* `{{@@ distro_id @@}}` will contain the distribution ID as provided by <https://distro.readthedocs.io/en/latest/#distro.id>
|
||||
* `{{@@ distro_version @@}}` will contain the distribution version as provided by <https://distro.readthedocs.io/en/latest/#distro.version>
|
||||
* `{{@@ distro_like @@}}` will contain a space-separated list of distro IDs that are closely related to the current OS distro as provided by <https://distro.readthedocs.io/en/latest/#distro.like>
|
||||
|
||||
## Dotfile variables
|
||||
|
||||
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.
|
||||
* `{{@@ _dotfile_key @@}}` contains the processed dotfile key.
|
||||
* `{{@@ _dotfile_link @@}}` contains the processed dotfile `link` string value.
|
||||
|
||||
In addition to the above, the following variables are set in each file processed by dotdrop:
|
||||
|
||||
* `{{@@ _dotfile_sub_abs_src @@}}` contains the absolute source path of each file when handled by dotdrop.
|
||||
* `{{@@ _dotfile_sub_abs_dst @@}}` contains the absolute destination path of each file when handled by dotdrop.
|
||||
|
||||
For example, a directory dotfile (like `~/.ssh`) would process several files
|
||||
(`~/.ssh/config` and `~/.ssh/authorized_keys`, for example). In `~/.ssh/config`:
|
||||
|
||||
* `_dotfile_abs_dst` would be `/home/user/.ssh`
|
||||
* `_dotfile_sub_abs_dst` would be `/home/user/.ssh/config`
|
||||
|
||||
## Environment variables
|
||||
|
||||
It's possible to access environment variables inside the templates:
|
||||
```
|
||||
{{@@ env['MY_VAR'] @@}}
|
||||
```
|
||||
|
||||
This allows for storing host-specific properties and/or secrets in environment variables.
|
||||
It is recommended to use `variables` (see [config variables](config/config-file.md#variables))
|
||||
instead of environment variables unless these contain sensitive information that
|
||||
shouldn't be versioned in Git (see [handle secrets doc](howto/sensitive-dotfiles.md)).
|
||||
|
||||
## Template methods
|
||||
|
||||
Besides [Jinja2 global functions](https://jinja.palletsprojects.com/en/2.11.x/templates/#list-of-global-functions),
|
||||
the following methods can be used within templates:
|
||||
|
||||
* `exists(path)`: returns true when path exists
|
||||
```
|
||||
{%@@ if exists('/dev/null') @@%}
|
||||
it does exist
|
||||
{%@@ endif @@%}
|
||||
```
|
||||
|
||||
* `exists_in_path(name, path=None)`: returns true when executable exists in `$PATH`
|
||||
```
|
||||
{%@@ if exists_in_path('exa') @@%}
|
||||
alias ls='exa --git --color=always'
|
||||
{%@@ endif @@%}
|
||||
```
|
||||
|
||||
* `basename(path)`: returns the `basename` of the path argument
|
||||
```
|
||||
{%@@ set dotfile_filename = basename( _dotfile_abs_dst ) @@%}
|
||||
dotfile dst filename: {{@@ dotfile_filename @@}}
|
||||
```
|
||||
|
||||
* `dirname(path)`: returns the `dirname` of the path argument
|
||||
```
|
||||
{%@@ set dotfile_dirname = dirname( _dotfile_abs_dst ) @@%}
|
||||
dotfile dst dirname: {{@@ dotfile_dirname @@}}
|
||||
```
|
||||
|
||||
Custom user-defined functions can be loaded with the help of the
|
||||
config entry `func_file`.
|
||||
|
||||
Example:
|
||||
|
||||
The config file:
|
||||
```yaml
|
||||
config:
|
||||
func_file:
|
||||
- /tmp/myfuncs_file.py
|
||||
```
|
||||
|
||||
The python function under `/tmp/myfuncs_file.py`:
|
||||
```python
|
||||
def myfunc(arg):
|
||||
return not arg
|
||||
```
|
||||
|
||||
The dotfile content:
|
||||
```
|
||||
{%@@ if myfunc(False) @@%}
|
||||
this should exist
|
||||
{%@@ endif @@%}
|
||||
```
|
||||
|
||||
## Template filters
|
||||
|
||||
Besides [Jinja2 builtin filters](https://jinja.palletsprojects.com/en/2.11.x/templates/#builtin-filters),
|
||||
custom user-defined filter functions can be loaded using the config entry `filter_file`:
|
||||
|
||||
Example:
|
||||
|
||||
The config file:
|
||||
```yaml
|
||||
config:
|
||||
filter_file:
|
||||
- /tmp/myfilter_file.py
|
||||
```
|
||||
|
||||
The python filter under `/tmp/myfilter_file.py`:
|
||||
```python
|
||||
def myfilter(arg1):
|
||||
return str(int(arg1) - 10)
|
||||
```
|
||||
|
||||
The dotfile content:
|
||||
```
|
||||
{{@@ "13" | myfilter() @@}}
|
||||
```
|
||||
|
||||
For more information on how to create filters,
|
||||
see [the Jinja2 official docs](https://jinja.palletsprojects.com/en/2.11.x/api/#writing-filters).
|
||||
|
||||
## Importing macros
|
||||
|
||||
Macros must be imported `with context` in order to have access to the variables:
|
||||
```
|
||||
{%@@ from 'macro_file' import macro with context @@%}
|
||||
```
|
||||
|
||||
For more information, see the [dedicated Jinja2 docs](https://jinja.palletsprojects.com/en/2.11.x/templates/#macros).
|
||||
|
||||
## Dotdrop header
|
||||
|
||||
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:
|
||||
```none
|
||||
This dotfile is managed using dotdrop
|
||||
```
|
||||
|
||||
The header can be automatically added with:
|
||||
```none
|
||||
{{@@ header() @@}}
|
||||
```
|
||||
|
||||
Properly commenting the header in templates is the responsibility of the user,
|
||||
as [Jinja2](https://palletsprojects.com/p/jinja/) has no way of knowing what is the proper char(s) used for comments.
|
||||
Either prepend the directive with the commenting char(s) used in the dotfile
|
||||
(for example `# {{@@ header() @@}}`) or provide it as an argument `{{@@ header('# ') @@}}`.
|
||||
The results are equivalent.
|
||||
|
||||
## Debugging templates
|
||||
|
||||
To debug the result of a template, one can install the dotfiles to a temporary
|
||||
directory with the `install` command and the `-t` switch:
|
||||
```bash
|
||||
$ dotdrop install -t
|
||||
Installed to tmp /tmp/dotdrop-6ajz7565
|
||||
```
|
||||
8
docs/usage.md
vendored
8
docs/usage.md
vendored
@@ -63,7 +63,7 @@ A dotfile can be imported as a different file with the use
|
||||
of the command line switch `--as` (effectively modifying the `src` part
|
||||
of the dotfile in the config, that is the location of the dotfile in the
|
||||
`dotpath`). It is however recommended
|
||||
to use [templating](templating.md) to avoid duplicates and optimize
|
||||
to use [templating](template/templating.md) to avoid duplicates and optimize
|
||||
dotfile management.
|
||||
```bash
|
||||
$ dotdrop import ~/.zshrc --as=~/.zshrc.test
|
||||
@@ -133,7 +133,7 @@ f_xinitrc
|
||||
```
|
||||
|
||||
By using the `-T`/`--template` switch, only the dotfiles that
|
||||
are using [templating](templating.md) are listed.
|
||||
are using [templating](template/templating.md) are listed.
|
||||
|
||||
It is also possible to list all the files related to each dotfile entry
|
||||
by invoking the `detail` command, for example:
|
||||
@@ -178,7 +178,7 @@ There are two cases when updating a dotfile:
|
||||
* [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 dotfile does not use [templating](template/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
|
||||
@@ -189,7 +189,7 @@ $ dotdrop update ~/.vimrc
|
||||
$ git diff
|
||||
```
|
||||
|
||||
### The dotfile uses [templating](templating.md)
|
||||
### The dotfile uses [templating](template/templating.md)
|
||||
|
||||
The dotfile must be manually updated; three solutions can be used to identify the
|
||||
changes to apply to the template:
|
||||
|
||||
6
mkdocs.yml
vendored
6
mkdocs.yml
vendored
@@ -24,7 +24,11 @@ nav:
|
||||
- 'Dynvariables block': 'config/config-dynvars.md'
|
||||
- 'Uservariables block': 'config/config-uservars.md'
|
||||
- 'Templating':
|
||||
- 'Templating': 'templating.md'
|
||||
- 'Templating': 'template/templating.md'
|
||||
- 'Template variables': 'template/template-variables.md'
|
||||
- 'Template methods': 'template/template-methods.md'
|
||||
- 'Template filters': 'template/template-filters.md'
|
||||
- 'Debugging templates': 'template/template-debug.md'
|
||||
- 'HowTo':
|
||||
- 'Append text to a dotfile on install': 'howto/append.md'
|
||||
- 'Create files on install': 'howto/create-special-files.md'
|
||||
|
||||
Reference in New Issue
Block a user