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

doc update doc

Browse Source
This commit is contained in:
deadc0de6
2020-09-13 22:46:37 +02:00
parent b024891af1
commit 837652e5f8
12 changed files with 111 additions and 121 deletions
Download Patch File Download Diff File Expand all files Collapse all files

188
docs/config.md
View File

@@ -33,7 +33,7 @@ The **config** entry (mandatory) contains settings for the deployment
* `create`: create directory hierarchy when installing dotfiles if
it doesn't exist (default *true*)
* `default_actions`: list of action's keys to execute for all installed dotfile
(see [Use actions](#actions))
(see [actions](#entry-actions))
* `diff_command`: the diff command to use for diffing files (default `diff -r -u {0} {1}`)
* `dotpath`: path to the directory containing the dotfiles to be managed (default `dotfiles`)
by dotdrop (absolute path or relative to the config file location)
@@ -44,22 +44,22 @@ The **config** entry (mandatory) contains settings for the deployment
* `ignoreempty`: do not deploy template if empty (default *false*)
* `import_actions`: list of paths to load actions from
(absolute path or relative to the config file location,
see [Import actions from file](#import-actions-from-file))
see [Import actions from file](#entry-import_actions))
* `import_configs`: list of config file paths to be imported in
the current config (absolute path or relative to the current config file location,
see [Import config files](#import-config-files))
see [Import config files](#entry-import_configs))
* `import_variables`: list of paths to load variables from
(absolute path or relative to the config file location,
see [Import variables from file](#import-variables-from-file))
see [Import variables from file](#entry-import_variables))
* `instignore`: list of patterns to ignore when installing, apply to all dotfiles
(enclose in quotes when using wildcards, see [ignore patterns](#ignore-patterns))
* `keepdot`: preserve leading dot when importing hidden file in the `dotpath` (default *false*)
* `link_dotfile_default`: set dotfile's `link` attribute to this value when undefined.
Possible values: *nolink*, *link*, *link_children* (default: *nolink*,
see [Symlinking dotfiles](#symlinking-dotfiles))
see [Symlinking dotfiles](#symlink-dotfiles))
* `link_on_import`: set dotfile's `link` attribute to this value when importing.
Possible values: *nolink*, *link*, *link_children* (default: *nolink*,
see [Symlinking dotfiles](#symlinking-dotfiles))
see [Symlinking dotfiles](#symlink-dotfiles))
* `longkey`: use long keys for dotfiles when importing (default *false*,
see [Import dotfiles](usage.md#import-dotfiles))
* `minversion`: (*for internal use, do not modify*) provides the minimal dotdrop version to use
@@ -83,18 +83,18 @@ The **dotfiles** entry (mandatory) contains a list of dotfiles managed by dotdro
can use `variables` and `dynvariables`, make sure to quote)
* `link`: define how this dotfile is installed.
Possible values: *nolink*, *link*, *link_children* (default: `link_dotfile_default`,
see [Symlinking dotfiles](#symlinking-dotfiles))
see [Symlinking dotfiles](#symlink-dotfiles))
* `actions`: list of action keys that need to be defined in the **actions** entry below
(see [Use actions](#actions))
(see [actions](#entry-actions))
* `cmpignore`: list of patterns to ignore when comparing (enclose in quotes when using wildcards,
see [ignore patterns](#ignore-patterns))
* `ignoreempty`: if true empty template will not be deployed (defaults to the value of `ignoreempty` above)
* `instignore`: list of patterns to ignore when installing (enclose in quotes when using wildcards,
see [ignore patterns](#ignore-patterns))
* `trans_read`: transformation key to apply when installing this dotfile
(must be defined in the **trans_read** entry below, see [Use transformations](#transformations))
(must be defined in the **trans_read** entry below, see [transformations](#entry-transformations))
* `trans_write`: transformation key to apply when updating this dotfile
(must be defined in the **trans_write** entry below, see [Use transformations](#transformations))
(must be defined in the **trans_write** entry below, see [transformations](#entry-transformations))
* `upignore`: list of patterns to ignore when updating (enclose in quotes when using wildcards,
see [ignore patterns](#ignore-patterns))
* *DEPRECATED* `link_children`: replaced by `link: link_children`
@@ -127,15 +127,15 @@ The **profiles** entry (mandatory) contains a list of profiles with the differen
* `dotfiles`: the dotfiles associated to this profile
* `import`: list of paths containing dotfiles keys for this profile
(absolute path or relative to the config file location,
see [Import profile dotfiles from file](#import-profile-dotfiles-from-file)).
see [Import profile dotfiles from file](#entry-profile-import)).
* `include`: include all elements (dotfiles, actions, (dyn)variables, etc) from another profile
(see [Include dotfiles from another profile](#include-dotfiles-from-another-profile))
(see [Include dotfiles from another profile](#entry-profile-include))
* `variables`: profile specific variables
(see [Variables](#variables))
* `dynvariables`: profile specific interpreted variables
(see [Interpreted variables](#interpreted-variables))
(see [Interpreted variables](#entry-dynvariables))
* `actions`: list of action keys that need to be defined in the **actions** entry below
(see [Use actions](#actions))
(see [actions](#entry-actions))
```yaml
<some-profile-name-usually-the-hostname>:
@@ -161,7 +161,7 @@ The **profiles** entry (mandatory) contains a list of profiles with the differen
### actions entry
The **actions** entry (optional) contains a list of actions (see [actions](#actions))
The **actions** entry (optional) contains a list of actions (see [actions](#entry-actions))
```yaml
actions:
@@ -170,7 +170,7 @@ actions:
### trans_read entry
The **trans_read** entry (optional) contains a list of transformations (see [transformations](#transformations))
The **trans_read** entry (optional) contains a list of transformations (see [transformations](#entry-transformations))
```yaml
trans_read:
@@ -179,7 +179,7 @@ trans_read:
### trans_write entry
The **trans_write** entry (optional) contains a list of write transformations (see [transformations](#transformations))
The **trans_write** entry (optional) contains a list of write transformations (see [transformations](#entry-transformations))
```yaml
trans_write:
@@ -198,14 +198,52 @@ variables:
### dynvariables entry
The **dynvariables** entry (optional) contains a list of interpreted variables
(see [Interpreted variables](#interpreted-variables))
(see [Interpreted variables](#entry-dynvariables))
```yaml
dynvariables:
<variable-name>: <shell-oneliner>
```
## Actions
## Variables
Multiple variables can be used within the config file to
parametrize following elements of the config:
* dotfiles `src` and `dst` paths (see [Dynamic dotfile paths](#dynamic-dotfile-paths))
* external path specifications
* `import_variables`
* `import_actions`
* `import_configs`
* profiles's `import`
`actions` and `transformations` also support the use of variables
but those are resolved when the action/transformation is executed
(see [Dynamic actions](#dynamic-actions),
[Dynamic transformations](#dynamic-transformations) and [Templating](templating.md)).
Following variables are available in the config files:
* [variables defined in the config](#entry-variables)
* [interpreted variables defined in the config](#entry-dynvariables)
* [profile variables defined in the config](#profile-variables)
* environment variables: `{{@@ env['MY_VAR'] @@}}`
* dotdrop header: `{{@@ header() @@}}` (see [Dotdrop header](templating.md#dotdrop-header))
As well as all template methods (see [Available methods](templating.md#available-methods))
## Symlink dotfiles
Dotdrop is able to install dotfiles in three different ways
which are controlled by the `link` config attribute of each dotfile:
* `link: nolink`: the dotfile (file or directory) is copied to its destination
* `link: link`: the dotfile (file or directory) is symlinked to its destination
* `link: link_children`: the files/directories found under the dotfile (directory) are symlinked to their destination
For more see [this how-to](howto/symlink-dotfiles.md)
## Entry actions
**Note**: any action with a key starting with an underscore (`_`) won't be shown in output.
This can be useful when working with sensitive data containing passwords for example.
@@ -368,7 +406,7 @@ dotfiles:
- always_action
```
## Transformations
## Entry transformations
For examples of transformation uses, see
@@ -394,7 +432,7 @@ There are two types of transformations available:
* **{1}** will be replaced with a temporary file to store the result of the transformation
A typical use-case for transformations is when dotfiles need to be
stored encrypted or compressed. For more see below [the howto](howto/README.md).
stored encrypted or compressed. For more see [the howto](howto/README.md).
Note that transformations cannot be used if the dotfiles is to be linked (when `link: link` or `link: link_children`).
@@ -417,34 +455,7 @@ profiles:
will result in `abc; f_abc; p1; lastarg`
## Variables
Multiple variables can be used within the config file to
parametrize following elements of the config:
* dotfiles `src` and `dst` paths (see [Dynamic dotfile paths](#dynamic-dotfile-paths))
* external path specifications
* `import_variables`
* `import_actions`
* `import_configs`
* profiles's `import`
`actions` and `transformations` also support the use of variables
but those are resolved when the action/transformation is executed
(see [Dynamic actions](#dynamic-actions),
[Dynamic transformations](#dynamic-transformations) and [Templating](templating.md)).
Following variables are available in the config files:
* [variables defined in the config](#variables)
* [interpreted variables defined in the config](#interpreted-variables)
* [profile variables defined in the config](#profile-variables)
* environment variables: `{{@@ env['MY_VAR'] @@}}`
* dotdrop header: `{{@@ header() @@}}` (see [Dotdrop header](templating.md#dotdrop-header))
As well as all template methods (see [Available methods](templating.md#available-methods))
### config variables
## Entry variables
Variables defined in the `variables` entry are made available within the config file.
@@ -464,6 +475,7 @@ dynvariables:
```
will result in the following available variables:
* var1: `var1`
* var2: `var1 var2`
* var3: `var1 var2 var3`
@@ -495,7 +507,7 @@ profiles:
- f_gitconfig
```
### Interpreted variables
## Entry dynvariables
It is also possible to have *dynamic* variables in the sense that their
content will be interpreted by the shell before being substituted.
@@ -517,41 +529,7 @@ variables:
They have the same properties as [Variables](#variables).
## Symlinking dotfiles
Dotdrop is able to install dotfiles in three different ways
which are controlled by the `link` attribute of each dotfile:
* `link: nolink`: the dotfile (file or directory) is copied to its destination
* `link: link`: the dotfile (file or directory) is symlinked to its destination
* `link: link_children`: the files/directories found under the dotfile (directory) are symlinked to their destination
For more see [this how-to](howto/symlinked-dotfiles.md)
## All dotfiles for a profile
To use all defined dotfiles for a profile, simply use
the keyword `ALL`.
For example:
```yaml
dotfiles:
f_xinitrc:
dst: ~/.xinitrc
src: xinitrc
f_vimrc:
dst: ~/.vimrc
src: vimrc
profiles:
host1:
dotfiles:
- ALL
host2:
dotfiles:
- f_vimrc
```
## Include dotfiles from another profile
## Entry profile include
If one profile is using the entire set of another profile, one can use
the `include` entry to avoid redundancy.
@@ -574,7 +552,7 @@ profiles:
Here profile *host1* contains all the dotfiles defined for *host2* plus `f_xinitrc`.
For more advanced use-cases variables
([variables](#variables) and [dynvariables](#interpreted-variables))
([variables](#variables) and [dynvariables](#entry-dynvariables))
can be used to specify the profile to include in a profile
For example:
@@ -598,7 +576,7 @@ profiles:
- "profile_{{@@ var1 @@}}"
```
## Import profile dotfiles from file
## Entry profile import
Profile's dotfiles list can be loaded from external files
by specifying their paths in the config entry `import` under the specific profile.
@@ -638,7 +616,7 @@ import:
- profiles.d/{{@@ profile @@}}.yaml
```
## Import variables from file
## Entry import_variables
It is possible to load variables/dynvariables from external files by providing their
paths in the config entry `import_variables`.
@@ -670,7 +648,7 @@ import_variables:
- variables.d/myvars.yaml:optional
```
## Import actions from file
## Entry import_actions
It is possible to load actions from external files by providing their
paths in the config entry `import_actions`.
@@ -709,10 +687,10 @@ import_actions:
- actions.d/myactions.yaml:optional
```
## Import config files
## Entry import_configs
Entire config files can be imported. This means making the following available
from the imported config file in the original config file:
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
@@ -872,6 +850,30 @@ dotfiles:
trans_write: w_echo_var
```
## All dotfiles for a profile
To use all defined dotfiles for a profile, simply use
the keyword `ALL`.
For example:
```yaml
dotfiles:
f_xinitrc:
dst: ~/.xinitrc
src: xinitrc
f_vimrc:
dst: ~/.vimrc
src: vimrc
profiles:
host1:
dotfiles:
- ALL
host2:
dotfiles:
- f_vimrc
```
## Ignore patterns
It is possible to ignore specific patterns when using dotdrop. For example for `compare` when temporary
@@ -910,8 +912,6 @@ dotfiles:
...
```
examples
To completely ignore comparison of a specific dotfile:
```yaml
dotfiles:

2
docs/howto/README.md
View File

@@ -34,4 +34,4 @@
## Symlink dotfiles
[Symlink dotfiles](symlinked-dotfiles.md)
[Symlink dotfiles](symlink-dotfiles.md)

3
docs/howto/append.md
View File

@@ -1,7 +1,6 @@
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.md#actions).
and a temporary file.
[actions](../config.md#entry-actions) and a temporary file.
Below is a config example to append to a file:
```yaml

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

@@ -1,5 +1,5 @@
One way for creating symlinks (or any other special files) is to use a combination of
[actions](../config.md#actions) and a *fake* dotfile.
[actions](../config.md#entry-actions) and a *fake* dotfile.
Let's say for example you have a list of directories you want to link
from under `~/.original` to `~/symlinks`.
@@ -19,6 +19,7 @@ dir3
```
The config file would contain different elements
* a `dynvariables` that will read the above text file
* a few `variables` for the source and destination
* an action that will create the destination directory and symlink those directories

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

@@ -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.md#interpreted-variables)
[dynvariables](../config.md#entry-dynvariables)
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.md#interpreted-variables)
First define a [dynvariables](../config.md#entry-dynvariables)
in the config file which will look for files to include in the above directory:
```yaml
dynvariables:

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

@@ -1,16 +1,11 @@
# Sensitive dotfiles
* [Available solutions](#available-solutions)
* [Store encrypted dotfiles](#store-encrypted-dotfiles)
* [Load passphrase from file](#load-passphrase-from-file)
---
# Available solutions
Two solutions exist, the first one using an unversioned file (see [Environment variables](../templating.md#environment-variables))
and the second using transformations (see [Store encrypted dotfiles](#store-encrypted-dotfiles)).
* [Store encrypted dotfiles](#store-encrypted-dotfiles)
* [Load passphrase from file](#load-passphrase-from-file)
# Store encrypted dotfiles
Here's an example of part of a config file to use gpg encrypted dotfiles:

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

@@ -31,15 +31,15 @@ This is due to Jinja2 stripping CRLF.
One solution is to use `dos2unix` to re-format the dotfiles before adding them to dotdrop.
See https://github.com/deadc0de6/dotdrop/issues/42.
See <https://github.com/deadc0de6/dotdrop/issues/42>.
## Non-unicode chars
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.
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.
See https://github.com/deadc0de6/dotdrop/issues/42.
See <https://github.com/deadc0de6/dotdrop/issues/42>.
# Re-encode

5
docs/howto/symlinked-dotfiles.md → docs/howto/symlink-dotfiles.md
View File

@@ -13,11 +13,6 @@ Note that if the dotfile is using template directives, it will be symlinked into
`~/.config/dotdrop` instead of directly into your *dotpath*
(see [Templating symlinked dotfiles](#templating-symlinked-dotfiles))
* [Link children](#link-children)
* [Templating symlinked dotfiles](#templating-symlinked-dotfiles)
---
# Link children
This feature can be very useful for dotfiles when you don't want the entire

4
docs/installation.md
View File

@@ -96,8 +96,8 @@ Then follow the instructions under [With pypi](#with-pypi).
## Aur packages
Dotdrop is available on aur:
* stable: https://aur.archlinux.org/packages/dotdrop/
* git version: https://aur.archlinux.org/packages/dotdrop-git/
* stable: <https://aur.archlinux.org/packages/dotdrop/>
* git version: <https://aur.archlinux.org/packages/dotdrop-git/>
Then follow the [doc to setup your repository](#setup-your-repository).

3
docs/misc/migrate-from-submodule.md
View File

@@ -1,4 +1,3 @@
**WARNING**
Only do the following if you are using dotdrop version `< 0.7.1` or if you encounter an issue when running dotdrop that redirects you here.
@@ -67,4 +66,4 @@ $ git commit -m 'remove dotdrop.sh script'
* push upstream
```bash
$ git push
```
```

2
docs/templating.md
View File

@@ -30,7 +30,7 @@ Following variables are available in templates:
* `{{@@ _dotdrop_workdir @@}}` contains the [workdir](config.md) absolute path.
* dotfile specific variables (see [Dotfile variables](#dotfile-variables))
* config variables (see [Variables](config.md#variables)).
* config interpreted variables (see [Interpreted variables](config.md#interpreted-variables)).
* config interpreted variables (see [Interpreted variables](config.md#entry-dynvariables)).
## Dotfile variables

1
mkdocs.yml
View File

@@ -6,6 +6,7 @@ theme:
highlightjs: true
hljs_languages:
- yaml
collapse_navigation: false
use_directory_urls: true
nav:
- Home: 'README.md'