mirrors/dotdrop
1
0
Fork 0
mirror of https://github.com/deadc0de6/dotdrop.git synced 2026-02-04 22:04:44 +00:00
Code Activity

doc fix links

Browse Source
This commit is contained in:
deadc0de6
2020-09-12 15:06:36 +02:00
parent 7be2eeff45
commit fecf2adaa9
12 changed files with 82 additions and 82 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
docs/config/config-variables.md
View File

@@ -1,6 +1,6 @@
# Config variables
* [Config available variables](available-variables)
* [Config available variables](#available-variables)
* [Variables entry](#variables-entry)
* [Profile variables](#profile-variables)
* [Config variables in templates](#config-variables-in-templates)
@@ -8,12 +8,12 @@
---
# Config available variables
# Available variables
Multiple variables can be used within the config file to
parametrize following elements of the config:
* dotfiles `src` and `dst` paths (see [Dynamic dotfile paths](config#dynamic-dotfile-paths))
* dotfiles `src` and `dst` paths (see [Dynamic dotfile paths](config.md#dynamic-dotfile-paths))
* external path specifications
* `import_variables`
* `import_actions`
@@ -22,8 +22,8 @@ parametrize following elements of the config:
`actions` and `transformations` also support the use of variables
but those are resolved when the action/transformation is executed
(see [Dynamic actions](config#dynamic-actions),
[Dynamic transformations](config#dynamic-transformations) and [Templating](templating)).
(see [Dynamic actions](config.md#dynamic-actions),
[Dynamic transformations](config.md#dynamic-transformations) and [Templating](../template/templating.md)).
Following variables are available in the config files:
@@ -31,9 +31,9 @@ Following variables are available in the config files:
* [interpreted variables defined in the config](#interpreted-variables-entry)
* [profile variables defined in the config](#profile-variables)
* environment variables: `{{@@ env['MY_VAR'] @@}}`
* dotdrop header: `{{@@ header() @@}}` (see [Dotdrop header](templating#dotdrop-header))
* dotdrop header: `{{@@ header() @@}}` (see [Dotdrop header](../template/templating.md#dotdrop-header))
As well as all template methods (see [Available methods](templating#available-methods))
As well as all template methods (see [Available methods](../template/templating.md#available-methods))
# Variables entry
@@ -89,7 +89,7 @@ profiles:
# Config variables in templates
`variables` and `dynvariables` are also made available in templates
(see [Template variables](templating#template-variables)).
(see [Template variables](../template/templating.md#template-variables)).
Variables in the config file
```yaml

56
docs/config/config.md
View File

@@ -49,18 +49,18 @@ Content Format:
one that will be installed by dotdrop (default *true*)
* `banner`: display the banner (default *true*)
* `cmpignore`: list of patterns to ignore when comparing, apply to all dotfiles
(enclose in quotes when using wildcards, see [ignore patterns](ignore-pattern))
(enclose in quotes when using wildcards, see [ignore patterns](ignore-pattern.md))
* `create`: create directory hierarchy when installing dotfiles if
it doesn't exist (default *true*)
* `default_actions`: list of action's keys to execute for all installed dotfile
(see [Use actions](usage-actions))
(see [Use actions](usage-actions.md))
* `diff_command`: the diff command to use for diffing files (default `diff -r -u {0} {1}`)
* `dotpath`: path to the directory containing the dotfiles to be managed (default `dotfiles`)
by dotdrop (absolute path or relative to the config file location)
* `filter_file`: list of paths to load templating filters from
(see [Templating available filters](templating#available-filters))
(see [Templating available filters](../template/templating.md#available-filters))
* `func_file`: list of paths to load templating functions from
(see [Templating available methods](templating#available-methods))
(see [Templating available methods](../template/templating.md#available-methods))
* `ignoreempty`: do not deploy template if empty (default *false*)
* `import_actions`: list of paths to load actions from
(absolute path or relative to the config file location,
@@ -72,7 +72,7 @@ Content Format:
(absolute path or relative to the config file location,
see [Import variables from file](#import-variables-from-file))
* `instignore`: list of patterns to ignore when installing, apply to all dotfiles
(enclose in quotes when using wildcards, see [ignore patterns](ignore-pattern))
(enclose in quotes when using wildcards, see [ignore patterns](ignore-pattern.md))
* `keepdot`: preserve leading dot when importing hidden file in the `dotpath` (default *false*)
* `link_dotfile_default`: set dotfile's `link` attribute to this value when undefined.
Possible values: *nolink*, *link*, *link_children* (default: *nolink*,
@@ -81,11 +81,11 @@ Content Format:
Possible values: *nolink*, *link*, *link_children* (default: *nolink*,
see [Symlinking dotfiles](#symlinking-dotfiles))
* `longkey`: use long keys for dotfiles when importing (default *false*,
see [Import dotfiles](usage#import-dotfiles))
see [Import dotfiles](../usage.md#import-dotfiles))
* `minversion`: (*for internal use, do not modify*) provides the minimal dotdrop version to use
* `showdiff`: on install show a diff before asking to overwrite (see `--showdiff`) (default *false*)
* `upignore`: list of patterns to ignore when updating, apply to all dotfiles
(enclose in quotes when using wildcards, see [ignore patterns](ignore-pattern))
(enclose in quotes when using wildcards, see [ignore patterns](ignore-pattern.md))
* `workdir`: path to the directory where templates are installed before being symlinked
when using `link:link` or `link:link_children`
(absolute path or relative to the config file location, defaults to *~/.config/dotdrop*)
@@ -102,18 +102,18 @@ Content Format:
Possible values: *nolink*, *link*, *link_children* (default: `link_dotfile_default`,
see [Symlinking dotfiles](#symlinking-dotfiles))
* `actions`: list of action keys that need to be defined in the **actions** entry below
(see [Use actions](usage-actions))
(see [Use actions](usage-actions.md))
* `cmpignore`: list of patterns to ignore when comparing (enclose in quotes when using wildcards,
see [ignore patterns](ignore-pattern))
see [ignore patterns](ignore-pattern.md))
* `ignoreempty`: if true empty template will not be deployed (defaults to the value of `ignoreempty` above)
* `instignore`: list of patterns to ignore when installing (enclose in quotes when using wildcards,
see [ignore patterns](ignore-pattern))
see [ignore patterns](ignore-pattern.md))
* `trans_read`: transformation key to apply when installing this dotfile
(must be defined in the **trans_read** entry below, see [Use transformations](usage-transformations))
(must be defined in the **trans_read** entry below, see [Use transformations](usage-transformations.md))
* `trans_write`: transformation key to apply when updating this dotfile
(must be defined in the **trans_write** entry below, see [Use transformations](usage-transformations))
(must be defined in the **trans_write** entry below, see [Use transformations](usage-transformations.md))
* `upignore`: list of patterns to ignore when updating (enclose in quotes when using wildcards,
see [ignore patterns](ignore-pattern))
see [ignore patterns](ignore-pattern.md))
* DEPRECATED `link_children`: replaced by `link: link_children`
* DEPRECATED `trans`: replaced by `trans_read`
@@ -149,7 +149,7 @@ Content Format:
* `dynvariables`: profile specific interpreted variables
(see [Interpreted variables](#interpreted-variables))
* `actions`: list of action keys that need to be defined in the **actions** entry below
(see [Use actions](usage-actions))
(see [Use actions](usage-actions.md))
```yaml
<some-profile-name-usually-the-hostname>:
@@ -173,21 +173,21 @@ Content Format:
- ...
```
* **actions** entry (optional): a list of actions (see [Use actions](usage-actions))
* **actions** entry (optional): a list of actions (see [Use actions](usage-actions.md))
```yaml
actions:
<action-key>: <command-to-execute>
```
* **trans_read** entry (optional): a list of transformations (see [Use transformations](usage-transformations))
* **trans_read** entry (optional): a list of transformations (see [Use transformations](usage-transformations.md))
```yaml
trans_read:
<trans-key>: <command-to-execute>
```
* **trans_write** entry (optional): a list of write transformations (see [Use transformations](usage-transformations))
* **trans_write** entry (optional): a list of write transformations (see [Use transformations](usage-transformations.md))
```yaml
trans_write:
@@ -211,19 +211,19 @@ dynvariables:
# Actions
see [Actions](usage-actions)
see [Actions](usage-actions.md)
# Transformations
see [Transformations](usage-transformations)
see [Transformations](usage-transformations.md)
# Variables
see [Variables](config-variables)
see [Variables](config-variables.md)
# Interpreted variables
see [Interpreted variables](config-variables)
see [Interpreted variables](config-variables.md)
# Symlinking dotfiles
@@ -234,7 +234,7 @@ which are controlled by the `link` attribute of each dotfile:
* `link: link`: the dotfile (file or directory) is symlinked to its destination
* `link: link_children`: the files/directories found under the dotfile (directory) are symlinked to their destination
For more see [this how-to](symlinked-dotfiles)
For more see [this how-to](../howto/symlinked-dotfiles.md)
# All dotfiles for a profile
@@ -282,7 +282,7 @@ profiles:
Here profile *host1* contains all the dotfiles defined for *host2* plus `f_xinitrc`.
For more advanced use-cases variables
([variables](config-variables) and [dynvariables](config-variables))
([variables](config-variables.md) and [dynvariables](config-variables.md))
can be used to specify the profile to include in a profile
For example:
@@ -498,7 +498,7 @@ import_configs:
# Dynamic dotfile paths
Dotfile source (`src`) and destination (`dst`) can be dynamically constructed using
defined variables ([variables and dynvariables](config-variables)).
defined variables ([variables and dynvariables](config-variables.md)).
For example to have a dotfile deployed on the unique firefox profile where the
profile path is dynamically found using a shell oneliner stored in a dynvariable:
@@ -519,8 +519,8 @@ Make sure to quote the path in the config file.
# Dynamic actions
Variables ([config variables and dynvariables](config-variables)
and [template variables](templating#template-variables)) can be used
Variables ([config variables and dynvariables](config-variables.md)
and [template variables](../template/templating.md#template-variables)) can be used
in actions for more advanced use-cases.
```yaml
@@ -553,8 +553,8 @@ Make sure to quote the actions using variables.
# Dynamic transformations
As for [dynamic actions](#dynamic-actions), transformations support
the use of variables ([variables and dynvariables](config-variables)
and [template variables](templating#template-variables)).
the use of variables ([variables and dynvariables](config-variables.md)
and [template variables](../template/templating.md#template-variables)).
A very dumb example:
```yaml

12
docs/config/ignore-pattern.md
View File

@@ -8,13 +8,13 @@
It is possible to ignore specific patterns when using dotdrop. For example for `compare` when temporary
files don't need to appear in the output.
* for [install](usage#install-dotfiles)
* using `instignore` in [the config file](config)
* for [compare](usage#compare-dotfiles)
* using `cmpignore` in [the config file](config)
* for [install](../usage.md#install-dotfiles)
* using `instignore` in [the config file](config.md)
* for [compare](../usage.md#compare-dotfiles)
* using `cmpignore` in [the config file](config.md)
* using the command line switch `-i --ignore`
* for [update](usage#update-dotfiles)
* using `upignore` in [the config file](config)
* for [update](../usage.md#update-dotfiles)
* using `upignore` in [the config file](config.md)
* using the command line switch `-i --ignore`
The ignore pattern must follow Unix shell-style wildcards like for example `*/path/to/file`.

10
docs/config/usage-transformations.md
View File

@@ -11,14 +11,14 @@ This can be useful when working with sensitive data containing passwords for exa
There are two types of transformations available:
* **read transformations**: used to transform dotfiles before they are installed ([Config](config) key `trans_read`)
* **read transformations**: used to transform dotfiles before they are installed ([Config](config.md) key `trans_read`)
* Used for commands `install` and `compare`
* They have two arguments:
* **{0}** will be replaced with the dotfile to process
* **{1}** will be replaced with a temporary file to store the result of the transformation
* Happens **before** the dotfile is templated with jinja2 (see [templating](templating))
* Happens **before** the dotfile is templated with jinja2 (see [templating](../template/templating.md))
* **write transformations**: used to transform files before updating a dotfile ([Config](config) key `trans_write`)
* **write transformations**: used to transform files before updating a dotfile ([Config](config.md) key `trans_write`)
* Used for command `update`
* They have two arguments:
* **{0}** will be replaced with the file path to update the dotfile with
@@ -54,5 +54,5 @@ will result in `abc; f_abc; p1; lastarg`
See
* [Store compressed directories](store-compressed-directories)
* [Sensitive dotfiles](sensitive-dotfiles)
* [Store compressed directories](../howto/store-compressed-directories.md)
* [Sensitive dotfiles](../howto/sensitive-dotfiles.md)

10
docs/howto/create-special-files.md
View File

@@ -1,10 +1,10 @@
One way for creating symlinks (or any other special files) is to use a combination of
[actions](usage-actions) and a *fake* dotfile.
[actions](../config/usage-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`.
```bash
$ tree ~/.original
$ tree ~/.original
/home/user/.original
├── dir1
├── dir2
@@ -28,7 +28,7 @@ The config file would contain different elements
dynvariables:
links_list: "cat {{@@ _dotdrop_dotpath @@}}/links.txt | xargs"
...
variables:
variables:
links_dst: "{{@@ env['HOME'] @@}}/.symlinks"
links_src: "{{@@ env['HOME'] @@}}/.original"
...
@@ -44,11 +44,11 @@ actions:
The result would be
```bash
$ tree ~/.symlinks
$ tree ~/.symlinks
/home/user/.symlinks
├── dir1 -> /home/user/.original/dir1
├── dir2 -> /home/user/.original/dir2
└── dir3 -> /home/user/.original/dir3
```
For reference, see [issue 243](https://github.com/deadc0de6/dotdrop/issues/243)
For reference, see [issue 243](https://github.com/deadc0de6/dotdrop/issues/243)

8
docs/howto/merge-files-when-installing.md
View File

@@ -20,7 +20,7 @@ profiles:
...
```
Note that the subfiles (`vimrc.d/top` and `vimrc.d/bottom`)
Note that the subfiles (`vimrc.d/top` and `vimrc.d/bottom`)
are not known to the config and do not need to be.
Edit the stored vimrc file to include the other files, for example:
@@ -46,12 +46,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-variables#interpreted-variables)
[dynvariables](../config/config-variables.md#interpreted-variables-entry)
and [jinja2 directives](http://jinja.pocoo.org/docs/2.10/) have to be used.
Let's say all files in `<dotpath>/toinclude` need to be included into a dotfile.
First define a [dynvariables](config-variables#interpreted-variables)
First define a [dynvariables](../config/config-variables.md#interpreted-variables-entry)
in the config file which will look for files to include in the above directory:
```yaml
dynvariables:
@@ -59,7 +59,7 @@ dynvariables:
```
Note that `_dotdrop_dotpath` is part of the built-in variables
(for more see [template variables](templating#template-variables)).
(for more see [template variables](../template/templating.md#template-variables)).
And then use the generated list in the dotfile template:
```

4
docs/howto/sensitive-dotfiles.md
View File

@@ -8,7 +8,7 @@
# Available solutions
Two solutions exist, the first one using an unversioned file (see [Environment variables](templating#environment-variables))
Two solutions exist, the first one using an unversioned file (see [Environment variables](../template/templating.md#environment-variables))
and the second using transformations (see [Store encrypted dotfiles](#store-encrypted-dotfiles)).
# Store encrypted dotfiles
@@ -68,4 +68,4 @@ variables:
gpg_password_file: "/tmp/the-password"
trans_read:
_gpg: "gpg2 --batch --yes --passphrase-file <(cat {{@@ gpg_password_file @@}}) -q --for-your-eyes-only --no-tty -d {0} > {1}"
```
```

12
docs/howto/sharing-content.md
View File

@@ -5,14 +5,14 @@ nice to share as much code as possible across the dotfiles, by leveraging
templating and merging them in the same dotfile in Dotdrop's `dotpath`. Here
are a few suggestions about how to achieve this.
* [Brute force templating](brute-force-templating)
* [Profile variables](profile-variables)
* [Jinja macros](jinja-macros)
* [Brute force templating](#brute-force-templating)
* [Profile variables](#profile-variables)
* [Jinja macros](#jinja-macros)
# Brute force templating
The first approach is sheer use of templating and Dotdrop
[template variables](#template-variables). In order to do this, we need to:
The first approach is sheer use of templating and variables
In order to do this, we need to:
1. Create the merged dotfile with an arbitrary name somewhere in `dotpath`.
2. Create two `dotfile` entries in `config.yaml`, both having the merged
@@ -64,7 +64,7 @@ export DB_PORT='4521'
Albeit flexible, the previous method is a bit cumbersome for some use cases.
For example, when the dotfiles belong to different profiles, the cleanest
solution consists in using
[profile variables](config-variables#profile-variables). This is achieved by:
[profile variables](../config/config-variables.md#profile-variables). 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.

4
docs/howto/special-chars.md
View File

@@ -37,10 +37,10 @@ See https://github.com/deadc0de6/dotdrop/issues/42.
Jinja2 is not able to process non-unicode chars (http://jinja.pocoo.org/docs/2.10/api/). This means that dotfiles using non-unicode chars can still be fully managed by dotdrop however when comparing the local file with the one stored in dotdrop, `compare` will return a difference even if there is none.
Either replace the non-unicode chars (see below [Re-encode](re-encode)) or accept the fact the comparison shows a difference while there's none.
Either replace the non-unicode chars (see below [Re-encode](#re-encode)) or accept the fact the comparison shows a difference while there's none.
See https://github.com/deadc0de6/dotdrop/issues/42.
# Re-encode
To change an existing file's encoding, you can use `recode UTF-8 <filename>` (see [recode](https://linux.die.net/man/1/recode)) or in vim `:set fileencoding=utf-8`.
To change an existing file's encoding, you can use `recode UTF-8 <filename>` (see [recode](https://linux.die.net/man/1/recode)) or in vim `:set fileencoding=utf-8`.

10
docs/howto/symlinked-dotfiles.md
View File

@@ -10,7 +10,7 @@ Where `src` is considered as the file stored in your *dotpath* and
`dst` as the file located in your `$HOME`.
Note that if the dotfile is using template directives, it will be symlinked into
`~/.config/dotdrop` instead of directly into your *dotpath*
`~/.config/dotdrop` instead of directly into your *dotpath*
(see [Templating symlinked dotfiles](#templating-symlinked-dotfiles))
* [Link children](#link-children)
@@ -22,7 +22,7 @@ Note that if the dotfile is using template directives, it will be symlinked into
This feature can be very useful for dotfiles when you don't want the entire
directory to be symlink but still want to keep a clean config files (with a
limited number of entries).
limited number of entries).
*Make sure to do a backup of your dotfiles with something like `cp -r <my-important-dotfile>{,.bak}`*
@@ -85,11 +85,11 @@ $ tree -L 1 ~/.vim
# Templating symlinked dotfiles
For dotfiles not using any templating directives, those are directly linked
to dotdrop's `dotpath` directory (see [Config](config)).
to dotdrop's `dotpath` directory (see [Config](../config/config.md)).
When using templating directives however the dotfiles are first installed into
`workdir` (defaults to *~/.config/dotdrop*, see [Config](config))
and then symlinked there.
`workdir` (defaults to *~/.config/dotdrop*, see [Config](../config/config.md))
and then symlinked there.
This applies to both dotfiles with `link: link` and `link: link_children`.
For example

8
docs/template/templating.md vendored
View File

@@ -43,8 +43,8 @@ Following variables are available in templates:
* `{{@@ _dotdrop_cfgpath @@}}` contains the absolute path to the [config file](https://github.com/deadc0de6/dotdrop/wiki/config).
* `{{@@ _dotdrop_workdir @@}}` contains the [workdir](https://github.com/deadc0de6/dotdrop/wiki/config) absolute path.
* dotfile specific variables (see [Dotfile variables](#dotfile-variables))
* config variables (see [Variables](config-variables)).
* config interpreted variables (see [Interpreted variables](config-variables)).
* config variables (see [Variables](../config/config-variables.md)).
* config interpreted variables (see [Interpreted variables](../config/config-variables.md)).
# Dotfile variables
@@ -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-variables))
It is recommended to use `variables` (see [Config variables](../config/config-variables.md))
instead of environment variables unless these contain sensitive information that
shouldn't be versioned in git.
@@ -215,7 +215,7 @@ It is possible to avoid having an empty rendered template being
deployed by setting the `ignoreempty` entry to *true*. This can be set
globally for all dotfiles or only for specific dotfiles.
For more see the [Config](config).
For more see the [Config](../config/config.md).
# Include file or template in template

14
docs/usage.md
View File

@@ -12,8 +12,8 @@ Run `dotdrop --help` to see all available options.
* [Update dotfiles](#update-dotfiles)
* [Remove dotfiles](#remove-dotfiles)
* Uses
* [Use actions](usage-actions)
* [Use transformations](usage-transformations)
* [Use actions](config/usage-actions.md)
* [Use transformations](config/usage-transformations.md)
* [Update dotdrop](#update-dotdrop)
* [Environment variables](#environment-variables)
* [User tricks](#user-tricks)
@@ -47,7 +47,7 @@ options
For more detail, see the usage with `dotdrop --help`
To ignore specific pattern during installation see [the dedicated wiki page](ignore-pattern)
To ignore specific pattern during installation see [the dedicated wiki page](config/ignore-pattern.md)
# Compare dotfiles
@@ -60,7 +60,7 @@ The diffing is done by `diff` in the backend, one can provide its specific
diff command using the config option `diff_command`.
To ignore specific pattern,
see [the dedicated wiki page](ignore-pattern)
see [the dedicated wiki page](config/ignore-pattern.md)
It is also possible to install all dotfiles for a specific profile
in a temporary directory in order to manually compare them with
@@ -176,11 +176,11 @@ $ dotdrop update --key f_vimrc
If not argument is provided, all dotfiles for the selected profile are updated.
To ignore specific pattern,
see [the dedicated wiki page](ignore-pattern)
see [the dedicated wiki page](config/ignore-pattern.md)
There are two cases when updating a dotfile:
## The dotfile doesn't use [templating](templating)
## The dotfile doesn't 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
@@ -191,7 +191,7 @@ $ dotdrop update ~/.vimrc
$ git diff
```
## The dotfile uses [templating](templating)
## 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: