mirror of
https://github.com/deadc0de6/dotdrop.git
synced 2026-02-04 14:31:46 +00:00
doc update structure
This commit is contained in:
deadc0de6
@@ -1,4 +1,4 @@
|
||||
# Dotdrop documentation
|
||||
# Dotdrop
|
||||
|
||||
[Dotdrop](https://deadc0de.re/dotdrop/) is a dotfiles manager that provides efficient ways of managing your dotfiles.
|
||||
It is especially powerful when it comes to managing those across different hosts.
|
||||
|
||||
530
docs/config-details.md
Normal file
530
docs/config-details.md
Normal file
@@ -0,0 +1,530 @@
|
||||
# Config details
|
||||
|
||||
## 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.
|
||||
|
||||
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)
|
||||
|
||||
### Dotfile actions
|
||||
|
||||
It is sometimes useful to execute some kind of action
|
||||
when deploying a dotfile.
|
||||
|
||||
Note that dotfile actions are only
|
||||
executed when the dotfile is installed.
|
||||
|
||||
For example let's consider
|
||||
[Vundle](https://github.com/VundleVim/Vundle.vim) is 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
|
||||
```
|
||||
|
||||
If you don't specify neither `post` nor `pre`, the action will be executed
|
||||
after the dotfile deployment (which is equivalent to `post`).
|
||||
Actions cannot obviously be named `pre` or `post`.
|
||||
|
||||
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 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
|
||||
|
||||
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 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
|
||||
```
|
||||
|
||||
## Entry transformations
|
||||
|
||||
For examples of transformation uses, see
|
||||
|
||||
* [Store compressed directories](howto/store-compressed-directories.md)
|
||||
* [Sensitive dotfiles](howto/sensitive-dotfiles.md)
|
||||
|
||||
**Note**: 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.
|
||||
|
||||
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
|
||||
* Happens **before** the dotfile is templated with jinja2 (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/README.md).
|
||||
|
||||
Note that transformations cannot be used if the dotfiles 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 itself as well as its 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`
|
||||
|
||||
## Entry variables
|
||||
|
||||
Variables defined in the `variables` entry are made available within the config file.
|
||||
|
||||
Config variables are recursively evaluated what 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`
|
||||
|
||||
## 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.
|
||||
|
||||
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).
|
||||
|
||||
## Entry profile variables
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
## Entry profile include
|
||||
|
||||
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](#entry-dynvariables))
|
||||
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 @@}}"
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
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` and would allow to do something like
|
||||
```yaml
|
||||
import:
|
||||
- profiles.d/{{@@ profile @@}}.yaml
|
||||
```
|
||||
|
||||
## Entry import_variables
|
||||
|
||||
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 the path with `:optional`
|
||||
```yaml
|
||||
import_variables:
|
||||
- variables.d/myvars.yaml:optional
|
||||
```
|
||||
|
||||
## Entry import_actions
|
||||
|
||||
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 variables will take precedence over variables defined within
|
||||
the source 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 the path with `:optional`
|
||||
```yaml
|
||||
import_actions:
|
||||
- actions.d/myactions.yaml:optional
|
||||
```
|
||||
|
||||
## Entry import_configs
|
||||
|
||||
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 the path with `:optional`
|
||||
```yaml
|
||||
import_configs:
|
||||
- other-config.yaml:optional
|
||||
```
|
||||
153
docs/config-format.md
Normal file
153
docs/config-format.md
Normal file
@@ -0,0 +1,153 @@
|
||||
## Format
|
||||
|
||||
Dotdrop config file uses [yaml](https://yaml.org/) syntax.
|
||||
|
||||
### 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
|
||||
`cmpignore` | list of patterns to ignore when comparing, apply to all dotfiles (enclose in quotes when using wildcards, see [ignore patterns](config.md#ignore-patterns)) | -
|
||||
`create` | create directory hierarchy when installing dotfiles if it doesn't exist | true
|
||||
`default_actions` | list of action's keys to execute for all installed dotfile (see [actions](config-details.md#entry-actions)) | -
|
||||
`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)) | -
|
||||
`func_file` | list of paths to load templating functions from (see [Templating available methods](templating.md#template-methods)) | -
|
||||
`ignoreempty` | do not deploy template if empty | false
|
||||
`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#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](config-details.md#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](config-details.md#entry-import_variables)) | -
|
||||
`instignore` | list of patterns to ignore when installing, apply 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
|
||||
`link_dotfile_default` | set dotfile's `link` attribute to this value when undefined. Possible values: *nolink*, *link*, *link_children* (see [Symlinking dotfiles](config.md#symlink-dotfiles)) | `nolink`
|
||||
`link_on_import` | set dotfile's `link` attribute to this value when importing. Possible values: *nolink*, *link*, *link_children* (see [Symlinking dotfiles](config.md#symlink-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
|
||||
`upignore` | list of patterns to ignore when updating, apply 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 that value per default | false
|
||||
|
||||
### dotfiles entry
|
||||
|
||||
The **dotfiles** entry (mandatory) contains a list of dotfiles managed by dotdrop
|
||||
|
||||
Entry | Description
|
||||
-------- | -------------
|
||||
`dst` | where this dotfile needs to be deployed (dotfile with empty `dst` are ignored and considered installed, can use `variables` and `dynvariables`, make sure to quote)
|
||||
`src` | dotfile path within the `dotpath` (dotfile with empty `src` are ignored and considered installed, can use `variables` and `dynvariables`, make sure to quote)
|
||||
`link` | define how this dotfile is installed. Possible values: *nolink*, *link*, *link_children* (see [Symlinking dotfiles](config.md#symlink-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#entry-actions))
|
||||
`cmpignore` | list of patterns to ignore when comparing (enclose in quotes when using wildcards, see [ignore patterns](config.md#ignore-patterns))
|
||||
`ignoreempty` | if true empty template will not be deployed (defaults to value of `ignoreempty`)
|
||||
`instignore` | list of patterns to ignore when installing (enclose in quotes when using wildcards, see [ignore patterns](config.md#ignore-patterns))
|
||||
`trans_read` | transformation key to apply when installing this dotfile (must be defined in the **trans_read** entry below, see [transformations](config-details.md#entry-transformations))
|
||||
`trans_write` | transformation key to apply when updating this dotfile (must be defined in the **trans_write** entry below, see [transformations](config-details.md#entry-transformations))
|
||||
`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>
|
||||
trans_read: <transformation-key>
|
||||
trans_write: <transformation-key>
|
||||
```
|
||||
|
||||
### profiles entry
|
||||
|
||||
The **profiles** entry (mandatory) contains a list of profiles with the different dotfiles that
|
||||
need to be managed
|
||||
|
||||
Entry | Description
|
||||
-------- | -------------
|
||||
`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](config-details.md#entry-profile-import)).
|
||||
`include` | include all elements (dotfiles, actions, (dyn)variables, etc) from another profile (see [Include dotfiles from another profile](config-details.md#entry-profile-include))
|
||||
`variables` | profile specific variables (see [Variables](config.md#variables))
|
||||
`dynvariables` | profile specific interpreted variables (see [Interpreted variables](config-details.md#entry-dynvariables))
|
||||
`actions` | list of action keys that need to be defined in the **actions** entry below (see [actions](config-details.md#entry-actions))
|
||||
|
||||
```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 a list of actions (see [actions](config-details.md#entry-actions))
|
||||
|
||||
```yaml
|
||||
actions:
|
||||
<action-key>: <command-to-execute>
|
||||
```
|
||||
|
||||
### trans_read entry
|
||||
|
||||
The **trans_read** entry (optional) contains a list of transformations (see [transformations](config-details.md#entry-transformations))
|
||||
|
||||
```yaml
|
||||
trans_read:
|
||||
<trans-key>: <command-to-execute>
|
||||
```
|
||||
|
||||
### trans_write entry
|
||||
|
||||
The **trans_write** entry (optional) contains a list of write transformations (see [transformations](config-details.md#entry-transformations))
|
||||
|
||||
```yaml
|
||||
trans_write:
|
||||
<trans-key>: <command-to-execute>
|
||||
```
|
||||
|
||||
### variables entry
|
||||
|
||||
The **variables** entry (optional) contains a list of variables (see [variables](config.md#variables))
|
||||
|
||||
```yaml
|
||||
variables:
|
||||
<variable-name>: <variable-content>
|
||||
```
|
||||
|
||||
### dynvariables entry
|
||||
|
||||
The **dynvariables** entry (optional) contains a list of interpreted variables
|
||||
(see [Interpreted variables](config-details.md#entry-dynvariables))
|
||||
|
||||
```yaml
|
||||
dynvariables:
|
||||
<variable-name>: <shell-oneliner>
|
||||
```
|
||||
718
docs/config.md
718
docs/config.md
@@ -17,194 +17,6 @@ and use the first one found
|
||||
You can force dotdrop to use a different file either by using the `-c --cfg` cli switch
|
||||
or by defining the `DOTDROP_CONFIG` environment variable.
|
||||
|
||||
## Format
|
||||
|
||||
Dotdrop config file uses [yaml](https://yaml.org/) syntax.
|
||||
|
||||
### config entry
|
||||
|
||||
The **config** entry (mandatory) contains settings for the deployment
|
||||
|
||||
* `backup`: create a backup of the dotfile in case it differs from the
|
||||
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-patterns))
|
||||
* `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 [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)
|
||||
* `filter_file`: list of paths to load templating filters from
|
||||
(see [Templating available filters](templating.md#available-filters))
|
||||
* `func_file`: list of paths to load templating functions from
|
||||
(see [Templating available methods](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,
|
||||
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](#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](#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](#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](#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
|
||||
* `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-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, defaults to *~/.config/dotdrop*)
|
||||
* *DEPRECATED* `link_by_default`: when importing a dotfile set `link` to that value per default (default *false*)
|
||||
|
||||
### dotfiles entry
|
||||
|
||||
The **dotfiles** entry (mandatory) contains a list of dotfiles managed by dotdrop
|
||||
|
||||
* `dst`: where this dotfile needs to be deployed
|
||||
(dotfile with empty `dst` are ignored and considered installed,
|
||||
can use `variables` and `dynvariables`, make sure to quote)
|
||||
* `src`: dotfile path within the `dotpath`
|
||||
(dotfile with empty `src` are ignored and considered installed,
|
||||
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](#symlink-dotfiles))
|
||||
* `actions`: list of action keys that need to be defined in the **actions** entry below
|
||||
(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 [transformations](#entry-transformations))
|
||||
* `trans_write`: transformation key to apply when updating this dotfile
|
||||
(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`
|
||||
* *DEPRECATED* `trans`: 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>
|
||||
trans_read: <transformation-key>
|
||||
trans_write: <transformation-key>
|
||||
```
|
||||
|
||||
### profiles entry
|
||||
|
||||
The **profiles** entry (mandatory) contains a list of profiles with the different dotfiles that
|
||||
need to be managed
|
||||
|
||||
* `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](#entry-profile-import)).
|
||||
* `include`: include all elements (dotfiles, actions, (dyn)variables, etc) 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](#entry-dynvariables))
|
||||
* `actions`: list of action keys that need to be defined in the **actions** entry below
|
||||
(see [actions](#entry-actions))
|
||||
|
||||
```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 a list of actions (see [actions](#entry-actions))
|
||||
|
||||
```yaml
|
||||
actions:
|
||||
<action-key>: <command-to-execute>
|
||||
```
|
||||
|
||||
### trans_read entry
|
||||
|
||||
The **trans_read** entry (optional) contains a list of transformations (see [transformations](#entry-transformations))
|
||||
|
||||
```yaml
|
||||
trans_read:
|
||||
<trans-key>: <command-to-execute>
|
||||
```
|
||||
|
||||
### trans_write entry
|
||||
|
||||
The **trans_write** entry (optional) contains a list of write transformations (see [transformations](#entry-transformations))
|
||||
|
||||
```yaml
|
||||
trans_write:
|
||||
<trans-key>: <command-to-execute>
|
||||
```
|
||||
|
||||
### variables entry
|
||||
|
||||
The **variables** entry (optional) contains a list of variables (see [variables](#variables))
|
||||
|
||||
```yaml
|
||||
variables:
|
||||
<variable-name>: <variable-content>
|
||||
```
|
||||
|
||||
### dynvariables entry
|
||||
|
||||
The **dynvariables** entry (optional) contains a list of interpreted variables
|
||||
(see [Interpreted variables](#entry-dynvariables))
|
||||
|
||||
```yaml
|
||||
dynvariables:
|
||||
<variable-name>: <shell-oneliner>
|
||||
```
|
||||
|
||||
## Variables
|
||||
|
||||
Multiple variables can be used within the config file to
|
||||
@@ -224,13 +36,13 @@ but those are resolved when the action/transformation is executed
|
||||
|
||||
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)
|
||||
* [variables defined in the config](config-details.md#entry-variables)
|
||||
* [interpreted variables defined in the config](config-details.md#entry-dynvariables)
|
||||
* [profile variables defined in the config](config-details.md#entry-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))
|
||||
As well as all template methods (see [Available methods](templating.md#template-methods))
|
||||
|
||||
## Symlink dotfiles
|
||||
|
||||
@@ -243,528 +55,6 @@ which are controlled by the `link` config attribute of each dotfile:
|
||||
|
||||
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.
|
||||
|
||||
### Dotfile actions
|
||||
|
||||
It is sometimes useful to execute some kind of action
|
||||
when deploying a dotfile.
|
||||
|
||||
Note that dotfile actions are only
|
||||
executed when the dotfile is installed.
|
||||
|
||||
For example let's consider
|
||||
[Vundle](https://github.com/VundleVim/Vundle.vim) is 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
|
||||
```
|
||||
|
||||
If you don't specify neither `post` nor `pre`, the action will be executed
|
||||
after the dotfile deployment (which is equivalent to `post`).
|
||||
Actions cannot obviously be named `pre` or `post`.
|
||||
|
||||
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 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
|
||||
|
||||
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 can be created by specifying no `dst` and no `src` (see [config format](#format)).
|
||||
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
|
||||
```
|
||||
|
||||
## Entry transformations
|
||||
|
||||
For examples of transformation uses, see
|
||||
|
||||
* [Store compressed directories](howto/store-compressed-directories.md)
|
||||
* [Sensitive dotfiles](howto/sensitive-dotfiles.md)
|
||||
|
||||
**Note**: 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.
|
||||
|
||||
There are two types of transformations available:
|
||||
|
||||
* **read transformations**: used to transform dotfiles before they are installed ([format](#format) 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.md))
|
||||
|
||||
* **write transformations**: used to transform files before updating a dotfile ([format](#format) 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/README.md).
|
||||
|
||||
Note that transformations cannot be used if the dotfiles 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 itself as well as its 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`
|
||||
|
||||
## Entry variables
|
||||
|
||||
Variables defined in the `variables` entry are made available within the config file.
|
||||
|
||||
Config variables are recursively evaluated what 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`
|
||||
|
||||
### Profile variables
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
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](#variables).
|
||||
|
||||
## Entry profile include
|
||||
|
||||
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](#variables) and [dynvariables](#entry-dynvariables))
|
||||
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 @@}}"
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
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` and would allow to do something like
|
||||
```yaml
|
||||
import:
|
||||
- profiles.d/{{@@ profile @@}}.yaml
|
||||
```
|
||||
|
||||
## Entry import_variables
|
||||
|
||||
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 the path with `:optional`
|
||||
```yaml
|
||||
import_variables:
|
||||
- variables.d/myvars.yaml:optional
|
||||
```
|
||||
|
||||
## Entry import_actions
|
||||
|
||||
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 variables will take precedence over variables defined within
|
||||
the source 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 the path with `:optional`
|
||||
```yaml
|
||||
import_actions:
|
||||
- actions.d/myactions.yaml:optional
|
||||
```
|
||||
|
||||
## Entry import_configs
|
||||
|
||||
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 the path with `:optional`
|
||||
```yaml
|
||||
import_configs:
|
||||
- other-config.yaml:optional
|
||||
```
|
||||
|
||||
## Dynamic dotfile paths
|
||||
|
||||
Dotfile source (`src`) and destination (`dst`) can be dynamically constructed using
|
||||
|
||||
@@ -1 +0,0 @@
|
||||
see [the dedicated doc](https://github.com/deadc0de6/dotdrop/blob/master/CONTRIBUTING.md)
|
||||
@@ -1,12 +1,20 @@
|
||||
# HowTo
|
||||
|
||||
## Append to a dotfile
|
||||
## Append text to a dotfile on install
|
||||
|
||||
[Append to a dotfile](append.md)
|
||||
[Append text to a dotfile on install](append.md)
|
||||
|
||||
## Create special files
|
||||
## Create files on install
|
||||
|
||||
[Create special files](create-special-files.md)
|
||||
[Create files on install](create-special-files.md)
|
||||
|
||||
## Handle compressed directories
|
||||
|
||||
[Store compressed directories](store-compressed-directories.md)
|
||||
|
||||
## Handle secrets
|
||||
|
||||
[Handle secrets](sensitive-dotfiles.md)
|
||||
|
||||
## Handle special chars
|
||||
|
||||
@@ -16,6 +24,14 @@
|
||||
|
||||
[Improve git integration](improve-git-integration.md)
|
||||
|
||||
## Include file or template in template
|
||||
|
||||
[Include file or template in template](include-in-template.md)
|
||||
|
||||
## Manage system dotfiles
|
||||
|
||||
[Manage system dotfiles](global-config-files.md)
|
||||
|
||||
## Merge files on install
|
||||
|
||||
[Merge files on install](merge-files-when-installing.md)
|
||||
@@ -24,14 +40,6 @@
|
||||
|
||||
[Share content across dotfiles](sharing-content.md)
|
||||
|
||||
## Store compressed directories
|
||||
|
||||
[Store compressed directories](store-compressed-directories.md)
|
||||
|
||||
## Store secrets
|
||||
|
||||
[Store secrets](sensitive-dotfiles.md)
|
||||
|
||||
## Symlink dotfiles
|
||||
|
||||
[Symlink dotfiles](symlink-dotfiles.md)
|
||||
[Symlink dotfiles](symlink-dotfiles.md)
|
||||
@@ -1,6 +1,8 @@
|
||||
# Append text on install
|
||||
|
||||
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#entry-actions) and a temporary file.
|
||||
[actions](../config-details.md#entry-actions) and a temporary file.
|
||||
|
||||
Below is a config example to append to a file:
|
||||
```yaml
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# Create files on install
|
||||
|
||||
One way for creating symlinks (or any other special files) is to use a combination of
|
||||
[actions](../config.md#entry-actions) and a *fake* dotfile.
|
||||
[actions](../config-details.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`.
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# How to manage system wide config files with dotdrop
|
||||
# Manage system dotfiles
|
||||
|
||||
Dotdrop doesn't allow to handle file rights and permissions (at least not directly). Every operations (`mkdir`, `cp`, `mv`, `ln`, file creation) are executed with the rights of the user calling dotdrop. The rights of the stored dotfile are mirrored on the deployed dotfile (`chmod` like). It works well for local/user dotfiles but doesn't allow to manage global/system config files (`/etc` or `/var` for example) directly.
|
||||
|
||||
|
||||
14
docs/howto/include-in-template.md
Normal file
14
docs/howto/include-in-template.md
Normal file
@@ -0,0 +1,14 @@
|
||||
# Include file or template in template
|
||||
|
||||
[Jinja2](http://jinja.pocoo.org/docs/2.10/templates/) provides the ability to include an external file/template from within a template with the directive `include`. See the [related doc](http://jinja.pocoo.org/docs/2.10/templates/#include) for more. The path must be relative to the `dotpath`.
|
||||
|
||||
For example:
|
||||
```yaml
|
||||
{%@@ include 'colors/black.colors' @@%}
|
||||
```
|
||||
|
||||
Of course, paths could be also dynamically generated using variables.
|
||||
For example:
|
||||
```yaml
|
||||
{%@@ include colors_path + '/black.colors' @@%}
|
||||
```
|
||||
@@ -1,3 +1,5 @@
|
||||
# Merge files on install
|
||||
|
||||
Dotdrop allows to merge multiple files into one using the jinja2's `include` directive.
|
||||
|
||||
For example let's consider you want to keep your `vimrc` split into multiple parts in dotdrop
|
||||
@@ -43,15 +45,15 @@ The `include` path parameter needs to be relative to your `dotpath`.
|
||||
|
||||
Dotdrop will then automagically include the files into your vimrc when handling `f_vimrc`.
|
||||
|
||||
# Merge all files in a directory
|
||||
## Merge all files in a directory
|
||||
|
||||
To include all files in a directory, a combination of
|
||||
[dynvariables](../config.md#entry-dynvariables)
|
||||
[dynvariables](../config-details.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#entry-dynvariables)
|
||||
First define a [dynvariables](../config-details.md#entry-dynvariables)
|
||||
in the config file which will look for files to include in the above directory:
|
||||
```yaml
|
||||
dynvariables:
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# Sensitive dotfiles
|
||||
# Handle secrets
|
||||
|
||||
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)).
|
||||
@@ -6,7 +6,7 @@ and the second using transformations (see [Store encrypted dotfiles](#store-encr
|
||||
* [Store encrypted dotfiles](#store-encrypted-dotfiles)
|
||||
* [Load passphrase from file](#load-passphrase-from-file)
|
||||
|
||||
# Store encrypted dotfiles
|
||||
## Store encrypted dotfiles
|
||||
|
||||
Here's an example of part of a config file to use gpg encrypted dotfiles:
|
||||
```yaml
|
||||
@@ -47,7 +47,7 @@ $ cp <encrypted-version-of-secret> dotfiles/secret
|
||||
|
||||
* commit and push the changes
|
||||
|
||||
# Load passphrase from file
|
||||
## Load passphrase from file
|
||||
|
||||
Passphrase is retrieved using a script:
|
||||
```yaml
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
# Share content across dotfiles
|
||||
|
||||
There are cases in which two or more dotfiles are very similar. For example,
|
||||
two files exporting environment variables for two projects built with the same
|
||||
technology (eg. two node.js web servers deployed on AWS). In these cases it's
|
||||
@@ -9,7 +11,7 @@ are a few suggestions about how to achieve this.
|
||||
* [Profile variables](#profile-variables)
|
||||
* [Jinja macros](#jinja-macros)
|
||||
|
||||
# Brute force templating
|
||||
## Brute force templating
|
||||
|
||||
The first approach is sheer use of templating and variables
|
||||
In order to do this, we need to:
|
||||
@@ -59,12 +61,12 @@ export DB_HOST='super-duper.host'
|
||||
export DB_PORT='4521'
|
||||
```
|
||||
|
||||
# Profile variables
|
||||
## Profile variables
|
||||
|
||||
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.md#profile-variables). This is achieved by:
|
||||
[profile variables](../config-details.md#entry-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.
|
||||
@@ -122,7 +124,7 @@ export DB_HOST='cheaper.host'
|
||||
export DB_PORT='9632'
|
||||
```
|
||||
|
||||
# Jinja macros
|
||||
## Jinja macros
|
||||
|
||||
Even though it has cleaner dotfiles, the profile-variable-based procedure can't
|
||||
be used in two scenarios: when the dotfiles belong to the same profile, and
|
||||
|
||||
@@ -1,10 +1,12 @@
|
||||
# Handle special chars
|
||||
|
||||
* [Detect encoding](#detect-encoding)
|
||||
* [Special chars](#special-chars)
|
||||
* [Re-encode](#re-encode)
|
||||
|
||||
---
|
||||
|
||||
# Detect encoding
|
||||
## Detect encoding
|
||||
|
||||
Text file encoding can be identified using for example `file -b <file-path>` or in vim
|
||||
with `:set fileencoding`
|
||||
@@ -21,9 +23,9 @@ $ file -b <some-file>
|
||||
ISO-8859 text, with escape sequences
|
||||
```
|
||||
|
||||
# Special chars
|
||||
## Special chars
|
||||
|
||||
## CRLF
|
||||
### CRLF
|
||||
|
||||
The use of dotfiles with DOS/Windows line ending (CRLF, `\r\n`) will result in
|
||||
the comparison (`compare`) returning a difference while there is none.
|
||||
@@ -33,7 +35,7 @@ One solution is to use `dos2unix` to re-format the dotfiles before adding them
|
||||
|
||||
See <https://github.com/deadc0de6/dotdrop/issues/42>.
|
||||
|
||||
## Non-unicode chars
|
||||
### 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.
|
||||
|
||||
@@ -41,6 +43,6 @@ Either replace the non-unicode chars (see below [Re-encode](#re-encode)) or acce
|
||||
|
||||
See <https://github.com/deadc0de6/dotdrop/issues/42>.
|
||||
|
||||
# Re-encode
|
||||
## 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`.
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# Store compressed directories
|
||||
# Handle compressed directories
|
||||
|
||||
This is an example on how to use transformations (`trans_read` and `trans_write`) to store
|
||||
compressed directories and deploy them with dotdrop.
|
||||
|
||||
@@ -13,7 +13,7 @@ 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
|
||||
|
||||
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
|
||||
@@ -77,7 +77,7 @@ $ tree -L 1 ~/.vim
|
||||
└── vimrc -> ~/.dotfiles/vim/vimrc
|
||||
```
|
||||
|
||||
# Templating symlinked dotfiles
|
||||
## Templating symlinked dotfiles
|
||||
|
||||
For dotfiles not using any templating directives, those are directly linked
|
||||
to dotdrop's `dotpath` directory (see [Config](../config.md)).
|
||||
|
||||
@@ -4,7 +4,7 @@ Installing dotdrop [as a submodule](#as-a-submodule) is the recommended way.
|
||||
|
||||
If you want to keep your python environment clean, use the virtualenv installation instructions
|
||||
(see [As a submodule in a virtualenv](#as-a-submodule-in-a-virtualenv) and
|
||||
[With pypi in a virtualenv](#with-pypi-in-a-virtualenv)).
|
||||
[Pypi package in a virtualenv](#pypi-package-in-a-virtualenv)).
|
||||
In that case, the virtualenv environment might need to be loaded before any attempt to use dotdrop.
|
||||
|
||||
## As a submodule
|
||||
@@ -66,16 +66,16 @@ $ ./dotdrop.sh --help
|
||||
|
||||
Then follow the instructions under [As a submodule](#as-a-submodule).
|
||||
|
||||
## With pypi
|
||||
## Pypi package
|
||||
|
||||
Install dotdrop
|
||||
```bash
|
||||
$ pip3 install dotdrop --user
|
||||
```
|
||||
|
||||
and then [setup your repository](#setup-your-repository).
|
||||
and then [setup your repository](repository-setup.md).
|
||||
|
||||
## With pypi in a virtualenv
|
||||
## Pypi package in a virtualenv
|
||||
|
||||
Install dotdrop in a virtualenv from pypi
|
||||
```bash
|
||||
@@ -91,7 +91,7 @@ $ source env/bin/activate
|
||||
$ dotdrop --help
|
||||
```
|
||||
|
||||
Then follow the instructions under [With pypi](#with-pypi).
|
||||
Then follow the instructions under [Pypi package](#pypi-package).
|
||||
|
||||
## Aur packages
|
||||
|
||||
@@ -99,7 +99,7 @@ Dotdrop is available on aur:
|
||||
* 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).
|
||||
Then follow the [doc to setup your repository](repository-setup.md).
|
||||
|
||||
## Snap package
|
||||
|
||||
@@ -110,7 +110,7 @@ Install it with
|
||||
snap install dotdrop
|
||||
```
|
||||
|
||||
Then follow the [doc to setup your repository](#setup-your-repository).
|
||||
Then follow the [doc to setup your repository](repository-setup.md).
|
||||
|
||||
## Dependencies
|
||||
|
||||
@@ -150,49 +150,6 @@ Or if installed through pypi:
|
||||
$ pip3 install dotdrop --upgrade --user
|
||||
```
|
||||
|
||||
## Setup your repository
|
||||
|
||||
Either create a 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`)
|
||||
and a directory containing all your dotfiles managed by dotdrop.
|
||||
```bash
|
||||
## clone your repository (my-dotfiles)
|
||||
$ git clone <some-url>/my-dotfiles
|
||||
$ cd my-dotfiles
|
||||
|
||||
## within the repository create a directory to store your dotfiles
|
||||
## (refered by "dotpath" in the config, which defaults to "dotfiles")
|
||||
$ mkdir dotfiles
|
||||
```
|
||||
|
||||
Then add a config file. You can get a
|
||||
[minimal config file](https://github.com/deadc0de6/dotdrop/blob/master/config.yaml)
|
||||
from dotdrop's repository with
|
||||
```bash
|
||||
$ 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.
|
||||
|
||||
```bash
|
||||
$ tree my-dotfiles
|
||||
my-dotfiles
|
||||
├── config.yaml
|
||||
└── dotfiles
|
||||
```
|
||||
|
||||
If your config file is in an exotic location, you can add an alias
|
||||
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).
|
||||
|
||||
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).
|
||||
|
||||
## Shell completion
|
||||
|
||||
Completion scripts exist for `bash`, `zsh` and `fish`,
|
||||
|
||||
42
docs/repository-setup.md
Normal file
42
docs/repository-setup.md
Normal file
@@ -0,0 +1,42 @@
|
||||
# Repository setup
|
||||
|
||||
Either create a 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`)
|
||||
and a directory containing all your dotfiles managed by dotdrop.
|
||||
```bash
|
||||
## clone your repository (my-dotfiles)
|
||||
$ git clone <some-url>/my-dotfiles
|
||||
$ cd my-dotfiles
|
||||
|
||||
## within the repository create a directory to store your dotfiles
|
||||
## (refered by "dotpath" in the config, which defaults to "dotfiles")
|
||||
$ mkdir dotfiles
|
||||
```
|
||||
|
||||
Then add a config file. You can get a
|
||||
[minimal config file](https://github.com/deadc0de6/dotdrop/blob/master/config.yaml)
|
||||
from dotdrop's repository with
|
||||
```bash
|
||||
$ 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.
|
||||
|
||||
```bash
|
||||
$ tree my-dotfiles
|
||||
my-dotfiles
|
||||
├── config.yaml
|
||||
└── dotfiles
|
||||
```
|
||||
|
||||
If your config file is in an exotic location, you can add an alias
|
||||
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).
|
||||
|
||||
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).
|
||||
@@ -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#entry-dynvariables)).
|
||||
* config interpreted variables (see [Interpreted variables](config-details.md#entry-dynvariables)).
|
||||
|
||||
## Dotfile variables
|
||||
|
||||
@@ -83,28 +83,7 @@ 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.
|
||||
|
||||
## 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:
|
||||
```
|
||||
This dotfile is managed using dotdrop
|
||||
```
|
||||
|
||||
The header can be automatically added with:
|
||||
```
|
||||
{{@@ header() @@}}
|
||||
```
|
||||
|
||||
Properly commenting the header in templates is the responsibility of the user
|
||||
as [jinja2](http://jinja.pocoo.org/) 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 result is equivalent.
|
||||
|
||||
## Available methods
|
||||
## Template methods
|
||||
|
||||
Beside [jinja2 global functions](http://jinja.pocoo.org/docs/2.10/templates/#list-of-global-functions)
|
||||
the following methods can be used within the templates:
|
||||
@@ -159,7 +138,7 @@ this should exist
|
||||
{%@@ endif @@%}
|
||||
```
|
||||
|
||||
## Available filters
|
||||
## Template filters
|
||||
|
||||
Beside [jinja2 builtin filters](https://jinja.palletsprojects.com/en/2.10.x/templates/#builtin-filters)
|
||||
custom user-defined filter functions can be loaded using the config entry `filter_file`:
|
||||
@@ -195,28 +174,26 @@ Macros must be imported `with context` in order to have access to the variables:
|
||||
|
||||
For more see the [dedicated jinja2 doc](https://jinja.palletsprojects.com/en/2.11.x/templates/#macros).
|
||||
|
||||
## Ignore empty template
|
||||
## Dotdrop header
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
For more see the [Config](config.md).
|
||||
|
||||
## Include file or template in template
|
||||
|
||||
[Jinja2](http://jinja.pocoo.org/docs/2.10/templates/) provides the ability to include an external file/template from within a template with the directive `include`. See the [related doc](http://jinja.pocoo.org/docs/2.10/templates/#include) for more. The path must be relative to the `dotpath`.
|
||||
|
||||
For example:
|
||||
```yaml
|
||||
{%@@ include 'colors/black.colors' @@%}
|
||||
Here's what it looks like:
|
||||
```
|
||||
This dotfile is managed using dotdrop
|
||||
```
|
||||
|
||||
Of course, paths could be also dynamically generated using variables.
|
||||
For example:
|
||||
```yaml
|
||||
{%@@ include colors_path + '/black.colors' @@%}
|
||||
The header can be automatically added with:
|
||||
```
|
||||
{{@@ header() @@}}
|
||||
```
|
||||
|
||||
Properly commenting the header in templates is the responsibility of the user
|
||||
as [jinja2](http://jinja.pocoo.org/) 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 result is equivalent.
|
||||
|
||||
## Debug templates
|
||||
|
||||
|
||||
@@ -9,13 +9,14 @@ theme:
|
||||
collapse_navigation: false
|
||||
use_directory_urls: true
|
||||
nav:
|
||||
- Home: '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/README.md'
|
||||
- Contributing: 'contributing.md'
|
||||
markdown_extensions:
|
||||
- meta
|
||||
- tables
|
||||
|
||||
Reference in New Issue
Block a user