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

Proofread docs

Browse Source
This commit is contained in:
John T. Wodder II
2021-10-05 12:14:42 -04:00
parent 2c7ac514e0
commit 60550424ca
27 changed files with 624 additions and 631 deletions
Download Patch File Download Diff File Expand all files Collapse all files

180
CONTRIBUTING.md
View File

@@ -1,147 +1,147 @@
Content
Contents
* [code base](#code-base)
* [config parsing](#config-parsing)
* [lower layer](#lower-layer)
* [higher layer](#higher-layer)
* [Code base](#code-base)
* [Config parsing](#config-parsing)
* [Lower layer](#lower-layer)
* [Higher layer](#higher-layer)
* [Precedence](#precedence)
* [variables resolution](#variables-resolution)
* [rules](#rules)
* [testing](#testing)
* [testing with unittest](#testing-with-unittest)
* [testing with bash scripts](#testing-with-bash-scripts)
* [documentation](#documentation)
* [Variable resolution](#variable-resolution)
* [Rules](#rules)
* [Testing](#testing)
* [Testing with unittest](#testing-with-unittest)
* [Testing with bash scripts](#testing-with-bash-scripts)
* [Documentation](#documentation)
Thanks for helping out!
Feature requests, bug reports and PRs are always welcome!
Feature requests, bug reports, and PRs are always welcome!
This file provides a few pointers on how to contribute to dotdrop
and where to find information. For any question, feel free to open an issue.
and where to find information. For any questions, feel free to open an issue.
For PR adding new features, I'd be very thankful if you could add either
For PRs adding new features, I'd be very thankful if you could add either
a unittest for the added feature or a bash script test (see [testing](#testing)), thanks!
# code base
# Code base
Dotdrop's code base is located in the [dotdrop directory](/dotdrop).
Here's an overview of the different files and their role:
Here's an overview of the different files and their roles:
* **action.py**: represent the actions and transformations
* **action.py**: represents the actions and transformations
* **cfg_yaml.py**: the lower level config parser (see [lower layer](#lower-layer))
* **cfg_aggregator.py**: the higher level config parser (see [higher layer](#higher-layer))
* **comparator.py**: the class handling the comparison for `compare`
* **dictparser.py**: abstract class for parsing dictionaries
* **dotdrop.py**: the entry point and where the different cli commands are executed
* **dotdrop.py**: the entry point and where the different CLI commands are executed
* **dotfile.py**: represent a dotfile
* **installer.py**: the class handling the installation of dotfile for `install`
* **jhelpers.py**: list of methods available in templates with jinja2
* **jhelpers.py**: list of methods available in templates with Jinja2
* **linktypes.py**: enum for the three types of linking (none, symlink, children)
* **logger.py**: the custom logger
* **options.py**: the class embedding all the different options across dotdrop
* **profile.py**: represent a profile
* **settings.py**: represent the config settings
* **templategen.py**: the jinja2 templating class
* **profile.py**: represents a profile
* **settings.py**: represents the config settings
* **templategen.py**: the Jinja2 templating class
* **updater.py**: the class handling the update of dotfiles for `update`
* **utils.py**: some useful methods used across the code base
# config parsing
# Config parsing
The configuration file (yaml) is parsed using two layers:
The configuration file (YAML) is parsed using two layers:
* first in the lower layer in [cfg_yaml.py](/dotdrop/cfg_yaml.py)
* then in the higher layer in [cfg_aggregator.py](/dotdrop/cfg_aggregator.py)
* First in the lower layer in [cfg_yaml.py](/dotdrop/cfg_yaml.py)
* Then in the higher layer in [cfg_aggregator.py](/dotdrop/cfg_aggregator.py)
Only the higher layer is accessible to other classes of dotdrop.
## lower layer
## Lower layer
This is done in [cfg_yaml.py](/dotdrop/cfg_yaml.py)
This is done in [cfg_yaml.py](/dotdrop/cfg_yaml.py).
The lower layer part is only taking care of basic types
The lower layer part only takes care of basic types
and does the following:
* normalize all config entries
* resolve paths (dotfiles src, dotpath, etc)
* refactor actions/transformations to a common format
* etc
* import any data from external files (configs, variables, etc)
* apply variable substitutions
* complete any data if needed (add the "profile" variable, etc)
* execute intrepreted variables through the shell
* write new entries (dotfile, profile) into the dictionary and save it to a file
* fix any deprecated entries (link_by_default, etc)
* clear empty entries
* Normalize all config entries
* Resolve paths (dotfiles src, dotpath, etc)
* Refactor actions/transformations to a common format
* Etc.
* Import any data from external files (configs, variables, etc)
* Apply variable substitutions
* Complete any data if needed (add the "profile" variable, etc)
* Execute intrepreted variables through the shell
* Write new entries (dotfile, profile) into the dictionary and save it to a file
* Fix any deprecated entries (link_by_default, etc)
* Clear empty entries
In the end it builds a cleaned and normalized dictionary to be accessed by the higher layer.
In the end, it builds a cleaned and normalized dictionary to be accessed by the higher layer.
## higher layer
## Higher layer
This is done in [cfg_aggregator.py](/dotdrop/cfg_aggregator.py)
This is done in [cfg_aggregator.py](/dotdrop/cfg_aggregator.py).
The higher layer will transform the dictionary parsed by the lower layer
into objects (profiles, dotfiles, actions, transformations, etc).
The higher layer has no notion of inclusion (profile included for example) or
file importing (import actions, etc) or even interpreted variables
The higher layer has no notion of inclusion (profile included, for example) or
file importing (import actions etc.) or even interpreted variables
(it only sees variables that have already been interpreted).
It does the following:
* transform dictionaries into objects
* patch list of keys with its corresponding object (for example dotfile's actions)
* provide getters for every other classes of dotdrop needing to access elements
* Transform dictionaries into objects
* Patch lists of keys with their corresponding objects (For example, dotfile's actions)
* Provide getters for every dotdrop class that needs to access elements
Note that any change to the yaml dictionary (adding a new profile or a new dotfile for
Note that any changes to the YAML dictionary (adding a new profile or a new dotfile for
example) won't be *seen* by the higher layer until the config is reloaded. Consider the
`dirty` flag as a sign the file needs to be written and its representation in higher
levels in not accurate anymore.
## precedence
## Precedence
* `dynvariables` > `variables`
* profile `(dyn)variables` > any other `(dyn)variables`
* profile `(dyn)variables` > profile's included `(dyn)variables`
* imported `variables`/`dynvariables` > `(dyn)variables`
* Profile `(dyn)variables` > any other `(dyn)variables`
* Profile `(dyn)variables` > profile's included `(dyn)variables`
* Imported `variables`/`dynvariables` > `(dyn)variables`
## variables resolution
## Variable resolution
How variables are resolved (through jinja2's
How variables are resolved (through Jinja2's
templating) in the config file.
* resolve main config file variables
* merge `variables` and `dynvariables` (allowing cycling reference)
* recursively template merged `variables` and `dynvariables`
* Resolve main config file variables
* Merge `variables` and `dynvariables` (allowing cyclic references)
* Recursively template merged `variables` and `dynvariables`
* `dynvariables` are executed
* profile's `variables` and `dynvariables` are merged
* resolve *included* entries (see below)
* paths and entries are templated
(allows to use something like `include {{@@ os @@}}.variables.yaml`)
* Profile's `variables` and `dynvariables` are merged
* Resolve *included* entries (see below)
* Paths and entries are templated
(allows using something like `include {{@@ os @@}}.variables.yaml`)
* *included* entries are processed
* dyn-/variables are all resolved in their own file
potential *included* entries
Potential *included* entries:
* entry *import_actions*
* entry *import_configs*
* entry *import_variables*
* profile's *import*
* profile's *include*
* Entry *import_actions*
* Entry *import_configs*
* Entry *import_variables*
* Profile's *import*
* Profile's *include*
Variables are then used to resolve different elements in the config file:
see [this](docs/config.md#variables)
see [this](docs/config.md#variables).
## rules
## Rules
* `dynvariables` are executed in their own config file
* since `variables` and `dynvariables` are templated before the `dynvariables`
are executed, this means that `dynvariables` can safely reference `variables` however
`variables` referencing `dynvariables` will result with the *not-executed* value of the
referenced `dynvariables` (see examples below)
* profile cannot include profiles defined above in the import tree
* config files do not have access to variables defined above in the import tree
* actions/transformations using variables are resolved at runtime
(when action/transformation is executed) and not when loading the config
* Since `variables` and `dynvariables` are templated before the `dynvariables`
are executed, this means that `dynvariables` can safely reference `variables`; however,
`variables` referencing `dynvariables` will result in the *not-executed* value of the
referenced `dynvariables` (see examples below).
* Profiles cannot include profiles defined above in the import tree
* Config files do not have access to variables defined above in the import tree
* Actions/transformations using variables are resolved at runtime
(when the action/transformation is executed) and not when loading the config
This will result with `dvar0 = "test"` and `var0 = "echo test"` (**not** `var0 = test`)
This will result in `dvar0 = "test"` and `var0 = "echo test"` (**not** `var0 = test`):
```yaml
variables:
var0: "{{@@ dvar0 @@}}"
@@ -149,7 +149,7 @@ dynvariables:
dvar0: "echo test"
```
This will result with `dvar0 = "test"` and `var0 = "test"`
This will result in `dvar0 = "test"` and `var0 = "test"`:
```yaml
variables:
var0: "test"
@@ -158,31 +158,31 @@ dynvariables:
```
# testing
# Testing
Dotdrop is tested with the use of the [tests.sh](/tests.sh) script.
* test for PEP8 compliance with `pycodestyle` and `pyflakes`
* run the unittest available in [tests directory](/tests)
* run the bash script tests in [tests-ng directory](tests-ng)
* Test for PEP8 compliance with `pycodestyle` and `pyflakes`
* Run the unittest available in [tests directory](/tests)
* Run the bash script tests in [tests-ng directory](tests-ng)
## testing with unittest
## Testing with unittest
All unittests are available in [tests directory](/tests)
and use [python unittest](https://docs.python.org/3/library/unittest.html).
All unittests are available in [the tests directory](/tests)
and use [Python's unittest](https://docs.python.org/3/library/unittest.html).
The file [helpers.py](/tests/helpers.py) provides different helper methods
for the tests.
## testing with bash scripts
## Testing with bash scripts
The bash scripts are available in [tests-ng directory](tests-ng).
These test entire workflows by simulating the use of dotdrop from end to end
for different use-cases (usually described in their filename or in the file header).
Each script starts with the same boiler plate code that you can paste at the
Each script starts with the same boilerplate code that you can paste at the
start of your new test (see the head of the file down to `# this is the test`).
# documentation
# Documentation
Dotdrop documentation is available under [https://dotdrop.readthedocs.io/](https://dotdrop.readthedocs.io/).

108
README.md
View File

@@ -15,33 +15,33 @@
*Save your dotfiles once, deploy them everywhere*
[Dotdrop](https://github.com/deadc0de6/dotdrop) makes the management of dotfiles between different hosts easy.
It allows to store your dotfiles on git and automagically deploy
It allows you to store your dotfiles in Git and automagically deploy
different versions of the same file on different setups.
It also allows to manage different *sets* of dotfiles.
For example you can have a set of dotfiles for your home laptop and
a different set for your office desktop. Those sets may overlap and different
versions of the same dotfiles can be deployed on different predefined *profiles*.
It also allows you to manage different *sets* of dotfiles.
For example, you can have a set of dotfiles for your home laptop and
a different set for your office desktop. Those sets may overlap, and different
versions of the same dotfiles can be deployed using different predefined *profiles*.
Or you may have a main set of dotfiles for your
everyday's host and a sub-set you only need to deploy to temporary
hosts (cloud VM, etc) that may be using
everyday host and a subset you only need to deploy to temporary
hosts (cloud VM etc.) that may be using
a slightly different version of some of the dotfiles.
Features:
* Sync once every dotfile on git for different usages
* Allow dotfiles templating by leveraging [jinja2](https://palletsprojects.com/p/jinja/)
* Sync once every dotfile in Git for different usages
* Allow dotfile templating by leveraging [Jinja2](https://palletsprojects.com/p/jinja/)
* Dynamically generated dotfile contents with pre-defined variables
* Comparison between deployed and stored dotfiles
* Handling multiple profiles with different sets of dotfiles
* Easy import and update dotfiles
* Easily import and update dotfiles
* Handle files and directories
* Support symlink of dotfiles
* Support symlinking of dotfiles
* Associate actions to the deployment of specific dotfiles
* Associate transformations for storing encrypted/compressed dotfiles
* Provide solutions for handling dotfiles containing sensitive information
Check also the [blog post](https://deadc0de.re/articles/dotfiles.html),
Also check out the [blog post](https://deadc0de.re/articles/dotfiles.html),
the [example](#getting-started), the [documentation](https://dotdrop.readthedocs.io/) or
how [people are using dotdrop](https://dotdrop.readthedocs.io/en/latest/misc/people-using-dotdrop/)
for more.
@@ -56,16 +56,16 @@ pip3 install -r dotdrop/requirements.txt --user
./dotdrop.sh --help
```
A mirror of this repository is available on gitlab under <https://gitlab.com/deadc0de6/dotdrop>.
A mirror of this repository is available on GitLab under <https://gitlab.com/deadc0de6/dotdrop>.
## Why dotdrop ?
## Why dotdrop?
There exist many tools to manage dotfiles however not
many allow to deploy different versions of the same dotfile
on different hosts. Moreover dotdrop allows to specify the
set of dotfiles that need to be deployed on a specific profile.
There exist many tools to manage dotfiles; however, not
many allow you to deploy different versions of the same dotfile
on different hosts. Moreover, dotdrop allows you to specify the
set of dotfiles that need to be deployed for a specific profile.
See the [example](#getting-started) for a concrete example on
See the [example](#getting-started) for a concrete example of
why [dotdrop](https://github.com/deadc0de6/dotdrop) rocks.
---
@@ -81,14 +81,14 @@ why [dotdrop](https://github.com/deadc0de6/dotdrop) rocks.
There are multiple ways to install and use dotdrop.
It is recommended to install dotdrop [as a submodule](#as-a-submodule)
to your dotfiles git tree. Having dotdrop as a submodule guarantees that anywhere
you are cloning your dotfiles git tree from you'll have dotdrop shipped with it.
to your dotfiles Git tree. Having dotdrop as a submodule guarantees that anywhere
you are cloning your dotfiles Git tree from you'll have dotdrop shipped with it.
Below instructions show how to install dotdrop as a submodule. For alternative
installation instructions see the
The below instructions show how to install dotdrop as a submodule. For alternative
installation instructions, see the
[installation documentation](https://dotdrop.readthedocs.io/en/latest/installation/).
Dotdrop is also available on
Dotdrop is also available on:
* pypi: https://pypi.org/project/dotdrop/
* aur (stable): https://aur.archlinux.org/packages/dotdrop/
* aur (git version): https://aur.archlinux.org/packages/dotdrop-git/
@@ -112,22 +112,22 @@ $ ./dotdrop/bootstrap.sh
$ ./dotdrop.sh --help
```
For MacOS users, make sure to install `realpath` through homebrew
For macOS users, make sure to install `realpath` through Homebrew
(part of *coreutils*).
Using dotdrop as a submodule will need you to work with dotdrop by
Using dotdrop as a submodule will require you to work with dotdrop by
using the generated script `dotdrop.sh` at the root
of your dotfiles repository. Note that this script updates the submodule
automatically, unless called with the environment variable `DOTDROP_AUTOUPDATE`
automatically unless called with the environment variable `DOTDROP_AUTOUPDATE`
set to `no`.
To ease the use of dotdrop, it is recommended to add an alias to it in your
shell (*~/.bashrc*, *~/.zshrc*, etc) with the config file path, for example
shell (*~/.bashrc*, *~/.zshrc*, etc.) with the config file path, for example:
```
alias dotdrop='<absolute-path-to-dotdrop.sh> --cfg=<path-to-your-config.yaml>'
```
Completion scripts exist for `bash`, `zsh` and `fish`, see [the related doc](completion/README.md).
Completion scripts exist for `bash`, `zsh` and `fish`; see [the related doc](completion/README.md).
# Getting started
@@ -137,21 +137,21 @@ to store your dotfiles with dotdrop. *Init* or *clone* that new repository and
Then import any dotfiles (files or directories) you want to manage with dotdrop.
You can either use the default profile (which resolves to the *hostname* of the host
you are running dotdrop on) or provide it specifically using the switch `-p --profile`.
you are running dotdrop on) or provide it explicitly using the switch `-p`/`--profile`.
Import dotfiles on host *home*
Import dotfiles on host *home*:
```bash
$ dotdrop import ~/.vimrc ~/.xinitrc ~/.config/polybar
```
Dotdrop does two things:
* Copy the dotfiles in the *dotpath* directory
* Copy the dotfiles to the *dotpath* directory
(defined in `config.yaml`, defaults to *dotfiles*)
* Create the associated entries in the `config.yaml` file
(in the `dotfiles` and `profiles` entries)
Your config file will look something similar to this
Your config file will look like something similar to this:
```yaml
config:
backup: true
@@ -186,16 +186,16 @@ see the [config doc](https://dotdrop.readthedocs.io/en/latest/config-format/).
Commit and push your changes with git.
Then go to another host where your dotfiles need to be managed as well,
clone the previously setup repository
clone the previously set up repository,
and compare the local dotfiles with the ones stored in dotdrop:
```bash
$ dotdrop compare --profile=home
```
Now you might want to adapt the `config.yaml` file to your likings on
that second host. Let's say for example that you only want `d_polybar` and
Now you might want to adapt the `config.yaml` file to your liking on
that second host. Let's say, for example, that you only want `d_polybar` and
`f_xinitrc` to be deployed on that second host. You would then change your config
to something like this (considering that the second host's hostname is *office*):
to something like this (assuming that the second host's hostname is *office*):
```yaml
…
profiles:
@@ -211,9 +211,9 @@ profiles:
```
Then adapt any dotfile using the [templating](https://dotdrop.readthedocs.io/en/latest/templating/)
feature (if needed). For example you might want different fonts sizes on polybar for each host.
feature (if needed). For example, you might want different fonts sizes in Polybar for each host.
edit `<dotpath>/config/polybar/config`
Edit `<dotpath>/config/polybar/config`:
```bash
…
{%@@ if profile == "home" @@%}
@@ -227,10 +227,10 @@ font2 = "unifont:size=6;0"
```
You also want to have the correct interface set on the wireless network in
the polybar config.
the Polybar config.
Add a [variable](https://dotdrop.readthedocs.io/en/latest/config/#variables)
to the config file (with below example *home* gets the default `wlan0` value for
to the config file (In the below example, *home* gets the default `wlan0` value for
the variable `wifi` while *office* gets `wlp2s0`):
```yaml
…
@@ -251,19 +251,19 @@ profiles:
wifi: "wlp2s0"
```
Then you can adapt the polybar config file so that the
variable `wifi` gets correctly replaced during installation
Then you can adapt the Polybar config file so that the
variable `wifi` gets correctly replaced during installation:
```bash
[module/wireless-network]
type = internal/network
interface = {{@@ wifi @@}}
```
Also the home computer is running [awesomeWM](https://awesomewm.org/)
Also, the home computer is running [awesomeWM](https://awesomewm.org/),
and the office computer [bspwm](https://github.com/baskerville/bspwm).
The `~/.xinitrc` file will therefore be different while still sharing some lines.
edit `<dotpath>/xinitrc`
Edit `<dotpath>/xinitrc`:
```bash
#!/bin/bash
@@ -282,7 +282,7 @@ exec bspwm
```
Finally you want everything installed with the *office* profile
to be logged, you thus add an action to the config file:
to be logged; you thus add an action to the config file:
```yaml
…
actions:
@@ -304,7 +304,7 @@ profiles:
- loginstall "/tmp/dotdrop-installation.log"
```
When done, you can install your dotfiles using
When done, you can install your dotfiles using:
```bash
$ dotdrop install
```
@@ -315,17 +315,17 @@ how your local dotfiles would be updated by dotdrop before running
That's it, a single repository with all your dotfiles for your different hosts.
For more see the [doc](https://dotdrop.readthedocs.io)
For more, see the [docs](https://dotdrop.readthedocs.io):
* [create actions](https://dotdrop.readthedocs.io/en/latest/config-details/#entry-actions)
* [use transformations](https://dotdrop.readthedocs.io/en/latest/config-details/#entry-transformations)
* [use variables](https://dotdrop.readthedocs.io/en/latest/config/#variables)
* [symlink dotfiles](https://dotdrop.readthedocs.io/en/latest/config/#symlink-dotfiles)
* [Create actions](https://dotdrop.readthedocs.io/en/latest/config-details/#entry-actions)
* [Use transformations](https://dotdrop.readthedocs.io/en/latest/config-details/#entry-transformations)
* [Use variables](https://dotdrop.readthedocs.io/en/latest/config/#variables)
* [Symlink dotfiles](https://dotdrop.readthedocs.io/en/latest/config/#symlink-dotfiles)
* [and more](https://dotdrop.readthedocs.io/en/latest/howto/howto/)
# Documentation
Dotdrop's documentation is hosted on [readthedocs](https://dotdrop.readthedocs.io/en/latest/).
Dotdrop's documentation is hosted on [Read the Docs](https://dotdrop.readthedocs.io/en/latest/).
# Thank you
@@ -338,7 +338,7 @@ If you are having trouble installing or using dotdrop,
If you want to contribute, feel free to do a PR (please follow PEP8).
Have a look at the
[contribution guidelines](https://github.com/deadc0de6/dotdrop/blob/master/CONTRIBUTING.md)
[contribution guidelines](https://github.com/deadc0de6/dotdrop/blob/master/CONTRIBUTING.md).
# License

12
completion/README.md
View File

@@ -1,6 +1,6 @@
Here are completion files for `bash`, `zsh` and `fish`
for the use of dotdrop through the bash script `dotdrop.sh`
or through the python script `dotdrop` (pypi, snap, setup.py, etc).
or through the Python script `dotdrop` (PyPI, snap, setup.py, etc.).
`bash` and `zsh` scripts are generated using
[infi.docopt_completion](https://github.com/Infinidat/infi.docopt_completion).
@@ -9,15 +9,15 @@ or through the python script `dotdrop` (pypi, snap, setup.py, etc).
Source the file
* if using `dotdrop.sh` [dotdrop.sh-completion.bash](dotdrop.sh-completion.bash)
* if using `dotdrop`: [dotdrop-completion.bash](dotdrop-completion.bash)
* if using `dotdrop.sh`: [dotdrop.sh-completion.bash](dotdrop.sh-completion.bash)
* If using `dotdrop`: [dotdrop-completion.bash](dotdrop-completion.bash)
# zsh
Copy the file in a path within `${fpath}`
Copy the file to a path within `${fpath}`
* if using `dotdrop.sh`: [_dotdrop.sh-completion.zsh](_dotdrop.sh-completion.zsh)
* if using `dotdrop`: [_dotdrop-completion.zsh](_dotdrop-completion.zsh)
* If using `dotdrop.sh`: [_dotdrop.sh-completion.zsh](_dotdrop.sh-completion.zsh)
* If using `dotdrop`: [_dotdrop-completion.zsh](_dotdrop-completion.zsh)
# fish

22
docs/README.md
View File

@@ -1,21 +1,21 @@
# 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.
[Dotdrop](https://deadc0de.re/dotdrop/) is a dotfiles manager that provides efficient ways to manage your dotfiles.
It is especially powerful when it comes to managing them across different hosts.
The idea of dotdrop is to have the ability to store each dotfile only once and deploy them with a different
The idea of dotdrop is to have the ability to store each dotfile only once and deploy them with different
content on different hosts/setups.
To achieve this, it uses [jinja2](https://palletsprojects.com/p/jinja/) which is a templating engine that allows to specify
To achieve this, it uses [Jinja2](https://palletsprojects.com/p/jinja/), which is a templating engine that allows you to specify
during the dotfile installation how (with what content) each dotfile will be installed based on a selected profile.
Most information on using dotdrop are described in this documentation
Most information on using dotdrop is described in this documentation
and in the [readme](https://github.com/deadc0de6/dotdrop/blob/master/README.md).
For more check
For more, check:
* [a quick overview of dotdrop features](https://deadc0de.re/dotdrop/)
* [the blogpost on dotdrop](https://deadc0de.re/articles/dotfiles.html)
* [an example](https://github.com/deadc0de6/dotdrop#getting-started)
* [how people are using dotdrop](misc/people-using-dotdrop.md)
* [A quick overview of dotdrop features](https://deadc0de.re/dotdrop/)
* [The blogpost on dotdrop](https://deadc0de.re/articles/dotfiles.html)
* [An example](https://github.com/deadc0de6/dotdrop#getting-started)
* [How people are using dotdrop](misc/people-using-dotdrop.md)
For more examples of config file, [search github](https://github.com/search?q=filename%3Aconfig.yaml+dotdrop&type=Code).
For more examples of config file, [search GitHub](https://github.com/search?q=filename%3Aconfig.yaml+dotdrop&type=Code).

116
docs/config-details.md
View File

@@ -1,13 +1,13 @@
# Config details
## Entry actions
## actions entry
Actions can be either `post` or `pre`
Actions can be either `post` or `pre`.
* `post` action will be executed after the dotfile deployment
* `pre` action will be executed before the dotfile deployment
* `post` action will be executed after the dotfile deployment.
* `pre` action will be executed before the dotfile deployment.
If you don't specify neither `post` nor `pre`, the action will be executed
If you don't specify either `post` or `pre`, the action will be executed
after the dotfile deployment (which is equivalent to `post`).
Actions cannot obviously be named `pre` or `post`.
@@ -20,10 +20,10 @@ Four types of actions can be defined:
**Notes**:
* 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.
* 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.
* Make sure to quote your actions to avoid bad surprises
* Actions are executed using the default shell (`$SHELL`)
* To use shell variables in your actions you need to escape the curly brackets (`${HOME}` becomes `${{HOME}}`)
* To use shell variables in your actions, you need to escape the curly brackets (`${HOME}` becomes `${{HOME}}`)
### Dotfile actions
@@ -31,13 +31,13 @@ It is sometimes useful to execute some kind of action
when deploying a dotfile.
Note that a dotfile's actions are only
executed when the dotfile is installed (that is when
executed when the dotfile is installed (that is, when
the version present in dotdrop differs from the one
in the filesystem).
For example let's consider
[Vundle](https://github.com/VundleVim/Vundle.vim) is used
to manage vim's plugins, the following action could
For example, let's consider
[Vundle](https://github.com/VundleVim/Vundle.vim), used
to manage Vim's plugins. The following action could
be set to update and install the plugins when `vimrc` is
deployed:
@@ -60,7 +60,7 @@ profiles:
- f_vimrc
```
Thus when `f_vimrc` is installed, the command
Thus, when `f_vimrc` is installed, the command
`vim +VundleClean! +VundleInstall +VundleInstall! +qall` will
be executed.
@@ -135,7 +135,7 @@ 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`).
Dotdrop allows you 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.
@@ -161,8 +161,8 @@ profiles:
### Profile actions
A profile action can be either `pre` or `post` action (see [actions](config-details.md#entry-actions)).
Those are executed before any dotfile installation (for `pre`) and after all dotfiles installation (for `post`)
A profile action can be either a `pre` or `post` action (see [actions](config-details.md#actions-entry)).
These are executed before any dotfile installation (for `pre`) and after all dotfile installations (for `post`)
only if at least one dotfile has been installed.
### Fake dotfile and actions
@@ -182,43 +182,43 @@ dotfiles:
- always_action
```
## Entry transformations
## transformations entry
For examples of transformation uses, see
For examples of transformation uses, see:
* [Handle compressed directories](howto/store-compressed-directories.md)
* [Handle secrets](howto/sensitive-dotfiles.md)
**Notes**:
* 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.
* 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.
* Make sure to quote your transformations to avoid bad surprises
* Transformations are executed using the default shell (`$SHELL`)
* To use shell variables in your transformations you need to escape the curly brackets (`${HOME}` becomes `${{HOME}}`)
There are two types of transformations available:
* **read transformations**: used to transform dotfiles before they are installed ([format](config-format.md) key `trans_read`)
* **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))
* 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`)
* **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/howto.md).
stored encrypted or compressed. For more, see [the howto](howto/howto.md).
Note that transformations cannot be used if the dotfiles is to be linked (when `link: link` or `link: link_children`).
Note that transformations cannot be used if the dotfile 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.
Transformations also support additional positional arguments that must start from 2 (since `{0}` and `{1}` are added automatically). The transformations themselves as well as their arguments can also be templated.
For example
For example:
```yaml
trans_read:
targ: echo "$(basename {0}); {{@@ _dotfile_key @@}}; {2}; {3}" > {1}
@@ -233,14 +233,14 @@ profiles:
- f_abc
```
will result in `abc; f_abc; p1; lastarg`
will result in `abc; f_abc; p1; lastarg`.
## Entry variables
## variables entry
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
Config variables are recursively evaluated, which means that
a config like the below:
```yaml
variables:
var1: "var1"
@@ -265,9 +265,9 @@ will result in the following available variables:
* dvar3: `dvar1 dvar2 dvar3`
* dvar4: `var1 var2 var3`
## Entry dynvariables
## dynvariables entry
It is also possible to have *dynamic* variables in the sense that their
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`.
@@ -287,12 +287,12 @@ variables:
They have the same properties as [Variables](config.md#variables).
## Entry uservariables
## uservariables entry
If you want to manually enter variables values, you can use the
If you want to manually enter variables' values, you can use the
`uservariables` entry. Each variable will be prompted to the user.
For example
For example:
```yaml
uservariables:
emailvar: "email"
@@ -304,11 +304,11 @@ Please provide the value for "email":
```
And store the entered text as the value for the variable `email`.
The variable can then be used as any other [variables](config.md#variables).
The variable can then be used as any other [variable](config.md#variables).
`uservariables` are eventually saved to `uservariables.yaml` (relatively to the
config file).
This allow to use the following construct to prompt once for some specific variables and
This allows you to use the following construct to prompt once for some specific variables and
then store them in a file. You might also want to add `uservariables.yaml` to your `.gitignore`.
```yaml
uservariables:
@@ -318,9 +318,9 @@ config:
- uservariables.yaml:optional
```
For an example, see [prompt user for variables](howto/prompt-user-for-variables.md)
For an example, see [prompt user for variables](howto/prompt-user-for-variables.md).
## Entry profile variables
## Profile variables entry
Profile variables will take precedence over globally defined variables.
This means that you could do something like this:
@@ -342,7 +342,7 @@ profiles:
- f_gitconfig
```
## Entry profile include
## Profile include entry
If one profile is using the entire set of another profile, one can use
the `include` entry to avoid redundancy.
@@ -364,9 +364,9 @@ profiles:
```
Here profile *host1* contains all the dotfiles defined for *host2* plus `f_xinitrc`.
For more advanced use-cases variables
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
can be used to specify the profile to include in a profile:
For example:
```yaml
@@ -389,12 +389,12 @@ profiles:
- "profile_{{@@ var1 @@}}"
```
Note that profile cannot include other profiles defined above in
the import tree (profile exists in another file and is imported using `import_configs` for example).
Note that profiles cannot include other profiles defined above in
the import tree (for example, when a profile exists in another file and is imported using `import_configs`).
## Entry profile import
## Profile import entry
Profile's dotfiles list can be loaded from external files
A 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.
@@ -426,13 +426,13 @@ dotfiles:
- f_xyz
```
Variables can be used in `import` and would allow to do something like
Variables can be used in `import`, which allow you to do something like:
```yaml
import:
- profiles.d/{{@@ profile @@}}.yaml
```
## Entry import_variables
## import_variables entry
It is possible to load variables/dynvariables from external files by providing their
paths in the config entry `import_variables`.
@@ -458,13 +458,13 @@ dynvariables:
```
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`
It is possible to make non-existing paths not fatal by appending `:optional` to the path:
```yaml
import_variables:
- variables.d/myvars.yaml:optional
```
## Entry import_actions
## import_actions entry
It is possible to load actions from external files by providing their
paths in the config entry `import_actions`.
@@ -497,13 +497,13 @@ External/imported variables will take precedence over variables defined
inside the main 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`
It is possible to make non-existing paths not fatal by appending `:optional` to the path:
```yaml
import_actions:
- actions.d/myactions.yaml:optional
```
## Entry import_configs
## import_configs entry
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:
@@ -569,13 +569,13 @@ actions:
show: less
```
In this example `config.yaml` imports `other-config.yaml`. The dotfile `f_def`
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`
It is possible to make non-existing paths not fatal by appending `:optional` to the path.
```yaml
import_configs:
- other-config.yaml:optional
@@ -583,10 +583,10 @@ import_configs:
## Dynamic dotfile paths
Dotfile source (`src`) and destination (`dst`) can be dynamically constructed using
Dotfile source (`src`) and destination (`dst`) paths can be dynamically constructed using
defined variables ([variables and dynvariables](config.md#variables)).
For example to have a dotfile deployed on the unique firefox profile where the
For example, to have a dotfile deployed on a unique Firefox profile where the
profile path is dynamically found using a shell oneliner stored in a dynvariable:
```yaml
dynvariables:
@@ -603,10 +603,10 @@ profiles:
## Dynamic dotfile link value
Dotfile `link` value can be dynamically constructed using
define variables ([variables and dynvariables](config.md#variables)).
Dotfile `link` values can be dynamically constructed using
defined variables ([variables and dynvariables](config.md#variables)).
For example
For example:
```yaml
variables:
link_value: "nolink"

127
docs/config-format.md
View File

@@ -1,65 +1,65 @@
# Config format
Dotdrop config file uses [yaml](https://yaml.org/) syntax.
The dotdrop config file uses [YAML](https://yaml.org/) syntax.
Here is a minimal config file to start with:
[config.yaml](https://github.com/deadc0de6/dotdrop/blob/master/config.yaml).
## config entry
The **config** entry (mandatory) contains settings for the deployment
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)) | -
`force_chmod` | if true, do not ask confirmation to apply permissions on install | false
`func_file` | list of paths to load templating functions from (see [Templating available methods](templating.md#template-methods)) | -
`ignore_missing_in_dotdrop` | ignore missing files in dotdrop when comparing and importing (see [Ignore missing](usage.md#ignore-missing)) | false
`ignoreempty` | do not deploy template if empty | false
`impignore` | list of patterns to ignore when importing (enclose in quotes when using wildcards, see [ignore patterns](config.md#ignore-patterns)) | -
`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* (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* [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
`template_dotfile_default` | disable templating on all dotfiles when set to false | true
`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
`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, applied to all dotfiles (enclose in quotes when using wildcards; see [ignore patterns](config.md#ignore-patterns)) | -
`create` | Create a directory hierarchy when installing dotfiles if it doesn't exist | true
`default_actions` | List of action keys to execute for all installed dotfiles (See [actions](config-details.md#actions-entry)) | -
`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)) | -
`force_chmod` | If true, do not ask confirmation to apply permissions on install | false
`func_file` | List of paths to load templating functions from (See [Templating available methods](templating.md#template-methods)) | -
`ignore_missing_in_dotdrop` | Ignore missing files in dotdrop when comparing and importing (See [Ignore missing](usage.md#ignore-missing)) | false
`ignoreempty` | Do not deploy template if empty | false
`impignore` | List of patterns to ignore when importing (enclose in quotes when using wildcards; see [ignore patterns](config.md#ignore-patterns)) | -
`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#import_actions-entry)) | -
`import_configs` | List of config file paths to be imported into the current config (absolute paths or relative to the current config file location; see [Import config files](config-details.md#import_configs-entry)) | -
`import_variables` | List of paths to load variables from (absolute paths or relative to the config file location; see [Import variables from file](config-details.md#import_variables-entry)) | -
`instignore` | List of patterns to ignore when installing, applied 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 a dotfile's `link` attribute to this value when undefined. Possible values: *nolink*, *link* (See [Symlinking dotfiles](config.md#symlink-dotfiles)) | `nolink`
`link_on_import` | Set a dotfile's `link` attribute to this value when importing. Possible values: *nolink*, *link* [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
`template_dotfile_default` | Disable templating on all dotfiles when set to false | true
`upignore` | List of patterns to ignore when updating, appled 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 this value by default | false
## dotfiles entry
The **dotfiles** entry (mandatory) contains a list of dotfiles managed by dotdrop
The **dotfiles** entry (mandatory) contains a YAML object with subobjects for the dotfiles managed by dotdrop. The entries in the subobjects are as follows:
Entry | Description
-------- | -------------
`dst` | where this dotfile needs to be deployed (dotfile with empty `dst` are ignored and considered installed, can use `variables`, make sure to quote)
`src` | dotfile path within the `dotpath` (dotfile with empty `src` are ignored and considered installed, can use `variables`, 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))
`chmod` | defines the file permissions in octal notation to apply during installation (see [permissions](config.md#permissions))
`cmpignore` | list of patterns to ignore when comparing (enclose in quotes when using wildcards, see [ignore patterns](config.md#ignore-patterns))
`ignore_missing_in_dotdrop` | ignore missing files in dotdrop when comparing and importing (see [Ignore missing](usage.md#ignore-missing))
`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))
`template` | if false disable template for this dotfile (defaults to value of `template_dotfile_default`)
`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`
`dst` | Where this dotfile needs to be deployed (dotfiles with empty `dst` are ignored and considered installed, can use `variables`, make sure to quote)
`src` | Dotfile path within the `dotpath` (dotfiles with empty `src` are ignored and considered installed, can use `variables`, make sure to quote)
`link` | Defines 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#actions-entry))
`chmod` | Defines the file permissions in octal notation to apply during installation (See [permissions](config.md#permissions))
`cmpignore` | List of patterns to ignore when comparing (enclose in quotes when using wildcards; see [ignore patterns](config.md#ignore-patterns))
`ignore_missing_in_dotdrop` | Ignore missing files in dotdrop when comparing and importing (see [Ignore missing](usage.md#ignore-missing))
`ignoreempty` | If true, an empty template will not be deployed (defaults to the value of `ignoreempty`)
`instignore` | List of patterns to ignore when installing (enclose in quotes when using wildcards; see [ignore patterns](config.md#ignore-patterns))
`template` | If false, disable templating for this dotfile (defaults to the value of `template_dotfile_default`)
`trans_read` | Transformation key to apply when installing this dotfile (must be defined in the **trans_read** entry below; see [transformations](config-details.md#transformations-entry))
`trans_write` | Transformation key to apply when updating this dotfile (must be defined in the **trans_write** entry below; see [transformations](config-details.md#transformations-entry))
`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>:
@@ -84,17 +84,16 @@ Entry | Description
## profiles entry
The **profiles** entry (mandatory) contains a list of profiles with the different dotfiles that
need to be managed
The **profiles** entry (mandatory) contains a YAML object with subobjects for the profiles for the different dotfiles that need to be managed. The entries in the subobjects are as follows:
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))
`dotfiles` | The dotfiles associated with this profile
`import` | List of paths containing dotfile keys for this profile (absolute path or relative to the config file location; see [Import profile dotfiles from file](config-details.md#profile-import-entry)).
`include` | Include all elements (dotfiles, actions, (dyn)variables, etc) from another profile (See [Include dotfiles from another profile](config-details.md#profile-include-entry))
`variables` | Profile-specific variables (See [Variables](config.md#variables))
`dynvariables` | Profile-specific interpreted variables (See [Interpreted variables](config-details.md#dynvariables-entry))
`actions` | List of action keys that need to be defined in the **actions** entry below (See [actions](config-details.md#actions-entry))
```yaml
<some-profile-name-usually-the-hostname>:
@@ -120,21 +119,21 @@ Entry | Description
## actions entry
The **actions** entry (optional) contains a list of actions (see [actions](config-details.md#entry-actions))
The **actions** entry (optional) contains an actions mapping (See [actions](config-details.md#actions-entry)).
```yaml
actions:
<action-key>: <command-to-execute>
```
*pre* actions
*pre* actions:
```yaml
actions:
pre:
<action-key>: <command-to-execute>
```
*post* actions
*post* actions:
```yaml
actions:
post:
@@ -143,7 +142,7 @@ actions:
## trans_read entry
The **trans_read** entry (optional) contains a list of transformations (see [transformations](config-details.md#entry-transformations))
The **trans_read** entry (optional) contains a transformations mapping (See [transformations](config-details.md#transformations-entry)).
```yaml
trans_read:
@@ -152,7 +151,7 @@ trans_read:
## trans_write entry
The **trans_write** entry (optional) contains a list of write transformations (see [transformations](config-details.md#entry-transformations))
The **trans_write** entry (optional) contains a write transformations mapping (See [transformations](config-details.md#transformations-entry)).
```yaml
trans_write:
@@ -161,7 +160,7 @@ trans_write:
## variables entry
The **variables** entry (optional) contains a list of variables (see [variables](config.md#variables))
The **variables** entry (optional) contains a variables mapping (See [variables](config.md#variables)).
```yaml
variables:
@@ -170,8 +169,8 @@ variables:
## dynvariables entry
The **dynvariables** entry (optional) contains a list of interpreted variables
(see [Interpreted variables](config-details.md#entry-dynvariables))
The **dynvariables** entry (optional) contains an interpreted variables mapping
(See [Interpreted variables](config-details.md#dynvariables-entry)).
```yaml
dynvariables:
@@ -180,9 +179,9 @@ dynvariables:
## uservariables entry
The **uservariables** entry (optional) contains a list of variables
to be queried to the user for their values.
(see [User variables](config-details.md#entry-uservariables))
The **uservariables** entry (optional) contains a collection of variables
whose values are queried from the user
(See [User variables](config-details.md#uservariables-entry)).
```yaml
uservariables:

156
docs/config.md
View File

@@ -5,73 +5,73 @@
The config file used by dotdrop is
[config.yaml](https://github.com/deadc0de6/dotdrop/blob/master/config.yaml).
Unless specified dotdrop will look in following places for its config file
and use the first one found
Unless specified otherwise, dotdrop will look in the following places for its config file
and use the first one found:
* current/working directory or the directory where [dotdrop.sh](https://github.com/deadc0de6/dotdrop/blob/master/dotdrop.sh) is located if used
* Current/working directory or the directory where [dotdrop.sh](https://github.com/deadc0de6/dotdrop/blob/master/dotdrop.sh) is located if used
* `${XDG_CONFIG_HOME}/dotdrop/`
* `~/.config/dotdrop/`
* `/etc/xdg/dotdrop/`
* `/etc/dotdrop/`
You can force dotdrop to use a different file either by using the `-c --cfg` cli switch
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.
## Variables
Multiple variables can be used within the config file to
parametrize following elements of the config:
parametrize the following elements of the config:
* dotfiles `src` and `dst` paths (see [Dynamic dotfile paths](config-details.md#dynamic-dotfile-paths))
* external path specifications
* Dotfile `src` and `dst` paths (See [Dynamic dotfile paths](config-details.md#dynamic-dotfile-paths))
* External path specifications
* `import_variables`
* `import_actions`
* `import_configs`
* profiles's `import`
* profiles's `include`
* Profiles' `import`
* Profiles' `include`
`actions` and `transformations` also support the use of variables
`actions` and `transformations` also support the use of variables,
but those are resolved when the action/transformation is executed
(see [Dynamic actions](config-details.md#dynamic-actions),
(See [Dynamic actions](config-details.md#dynamic-actions),
[Dynamic transformations](config-details.md#dynamic-transformations) and [Templating](templating.md)).
Following variables are available in the config files:
The following variables are available in the config files:
* [variables defined in the config](config-details.md#entry-variables)
* [interpreted variables defined in the config](config-details.md#entry-dynvariables)
* [user variables defined in the config](config-details.md#entry-uservariables)
* [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))
* [Variables defined in the config](config-details.md#entry-variables)
* [Interpreted variables defined in the config](config-details.md#entry-dynvariables)
* [User variables defined in the config](config-details.md#entry-uservariables)
* [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](templating.md#template-methods) and [template filters](templating.md#template-filters).
as well as all [template methods](templating.md#template-methods) and [template filters](templating.md#template-filters).
Note that all variables available in the config file will
then be available during [templating](templating.md).
Here are some rules on the use of variables in configs:
* [interpreted variables](config-details.md#entry-dynvariables) are executed in their own file
* [interpreted variables](config-details.md#entry-dynvariables) and
* [Interpreted variables](config-details.md#entry-dynvariables) are executed in their own file.
* [Interpreted variables](config-details.md#entry-dynvariables) and
[variables](config-details.md#entry-variables) are templated before
[interpreted variables](config-details.md#entry-dynvariables) are executed
* config files do not have access to variables defined above in the import tree
* `dynvariables` take precedence over `variables`
* profile `(dyn)variables` take precedence over any other `(dyn)variables`
* profile `(dyn)variables` take precedence over profile's included `(dyn)variables`
* external/imported `(dyn)variables` take precedence over
`(dyn)variables` defined inside the main config file
* [user variables](config-details.md#entry-uservariables) are ignored if
any other variable with the same key is defined
[interpreted variables](config-details.md#entry-dynvariables) are executed.
* Config files do not have access to variables defined above in the import tree.
* `dynvariables` take precedence over `variables`.
* Profile `(dyn)variables` take precedence over any other `(dyn)variables`.
* Profile `(dyn)variables` take precedence over profile's included `(dyn)variables`.
* External/imported `(dyn)variables` take precedence over
`(dyn)variables` defined inside the main config file.
* [User variables](config-details.md#entry-uservariables) are ignored if
any other variable with the same key is defined.
## Permissions
Dotdrop allows to control the permissions applied to a dotfile using the
Dotdrop allows you to control the permissions applied to a dotfile using the
config dotfile entry [chmod](config-format.md#dotfiles-entry).
A [chmod](config-format.md#dotfiles-entry) entry on a directory
is applied to the directory only, not recursively.
For example
For example:
```yaml
dotfiles:
f_file:
@@ -84,59 +84,59 @@ dotfiles:
chmod: 744
```
On `import` the following rules are applied:
On `import`, the following rules are applied:
* if the `-m --preserve-mode` switch is provided the imported file permissions are
* If the `-m`/`--preserve-mode` switch is provided, the imported file's permissions are
stored in a `chmod` entry
* if imported file permissions differ from umask then its permissions are automatically
stored in the `chmod` entry
* otherwise no `chmod` entry is added
* If the imported file's permissions differ from the umask, then the permissions are automatically
stored in the `chmod` entry.
* Otherwise, no `chmod` entry is added
On `install` the following rules are applied:
On `install`, the following rules are applied:
* if `chmod` is specified in the dotfile, it will be applied to the installed dotfile
* otherwise the permissions of the dotfile in the `dotpath` are applied.
* if the global setting `force_chmod` is set to true dotdrop will not ask
for confirmation to apply permission
* If `chmod` is specified in the dotfile, it will be applied to the installed dotfile.
* Otherwise, the permissions of the dotfile in the `dotpath` are applied.
* If the global setting `force_chmod` is set to true, dotdrop will not ask
for confirmation to apply permissions.
On `update`:
* if the permissions of the file in the filesystem differ from the dotfile in the `dotpath`
then the dotfile entry `chmod` is added/updated accordingly
* If the permissions of the file in the filesystem differ from the dotfile in the `dotpath`,
then the dotfile entry `chmod` is added/updated accordingly.
## Symlink dotfiles
## Symlinking dotfiles
Dotdrop is able to install dotfiles in three different ways
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
* `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)
For more, see [this how-to](howto/symlink-dotfiles.md).
## Template config entries
Some entries in the config can use the templating feature (see [templating](templating.md)):
Some entries in the config can use the templating feature (See [templating](templating.md)):
Entry | Related doc
-------- | -------------
dotfile src | [dynamic dotfile paths](config-details.md#dynamic-dotfile-paths)
dotfile dst | [dynamic dotfile paths](config-details.md#dynamic-dotfile-paths)
dotfile link | [dynamic dotfile link value](config-details.md#dynamic-dotfile-link-value)
variables | [variables](config-details.md#entry-variables)
dynvariables | [dynvariables](config-details.md#entry-dynvariables)
dotfile src | [Dynamic dotfile paths](config-details.md#dynamic-dotfile-paths)
dotfile dst | [Dynamic dotfile paths](config-details.md#dynamic-dotfile-paths)
dotfile link | [Dynamic dotfile link value](config-details.md#dynamic-dotfile-link-value)
variables | [variables](config-details.md#variables-entry)
dynvariables | [dynvariables](config-details.md#dynvariables-entry)
actions | [dynamic actions](config-details.md#dynamic-actions)
profile include | [profile include](config-details.md#entry-profile-include)
profile import | [profile import](config-details.md#entry-profile-import)
import_variables | [import_variables](config-details.md#entry-import_variables)
import_actions | [import_actions](config-details.md#entry-import_actions)
import_configs | [import_configs](config-details.md#entry-import_configs)
profile include | [Profile include](config-details.md#profile-include-entry)
profile import | [Profile import](config-details.md#profile-import-entry)
import_variables | [import_variables](config-details.md#import_variables-entry)
import_actions | [import_actions](config-details.md#import_actions-entry)
import_configs | [import_configs](config-details.md#import_configs-entry)
## All dotfiles for a profile
To use all defined dotfiles for a profile, simply use
To use all defined dotfiles in a profile, simply use
the keyword `ALL`.
For example:
@@ -161,27 +161,27 @@ profiles:
It is possible to ignore specific patterns when using dotdrop.
* for [install](usage.md#install-dotfiles)
* using `instignore` in the config file
* for [import](usage.md#import-dotfiles)
* using `impignore` in the config file
* for [compare](usage.md#compare-dotfiles)
* using `cmpignore` in the config file
* using the command line switch `-i --ignore`
* for [update](usage.md#update-dotfiles)
* using `upignore` in the config file
* using the command line switch `-i --ignore`
* For [install](usage.md#install-dotfiles):
* Using `instignore` in the config file
* For [import](usage.md#import-dotfiles):
* Using `impignore` in the config file
* For [compare](usage.md#compare-dotfiles):
* Using `cmpignore` in the config file
* Using the command line switch `-i`/`--ignore`
* For [update](usage.md#update-dotfiles):
* Using `upignore` in the config file
* Using the command line switch `-i`/`--ignore`
The ignore pattern must follow Unix shell-style wildcards like for example `*/path/to/file`.
Make sure to quote those when using wildcards in the config file.
The ignore pattern must follow Unix shell-style wildcards, like, for example `*/path/to/file`.
Make sure to quote these when using wildcards in the config file.
Patterns used on a specific dotfile can be specified relative to the dotfile destination (`dst`).
Patterns used for a specific dotfile can be specified relative to the dotfile destination (`dst`).
Similar to a `.gitignore` file, you can prefix ignore patterns with an exclamation point (`!`).
This so-called "negative ignore pattern" will cause any files that match that pattern to __not__ be ignored,
provided they *would have* been ignored by an earlier ignore pattern (dotdrop will warn if that is not the
case). This feature allows you to, for example, ignore all files within a certain directory, except for one
particular one (see example below).
particular one (See example below).
```yaml
config:
@@ -212,7 +212,7 @@ dotfiles:
- "*"
```
To ignore specific directory when updating
To ignore a specific directory when updating:
```yaml
dotfiles:
d_colorpicker:
@@ -222,7 +222,7 @@ dotfiles:
- '*sub_directory_to_ignore'
```
To ignore specific file `testfile` and directory `testdir` when importing:
To ignore a specific file `testfile` and directory `testdir` when importing:
```yaml
config:
impignore:

4
docs/howto/append.md
View File

@@ -23,9 +23,9 @@ actions:
post:
append: "cat {0} >> {1}; rm -f {0}"
```
During installation, the `strip` action is executed before the installation and strips everything from the pattern `# my pattern` to the end of the file. Then the dotfile `somefile` is installed in a temporary location (here `tmpfile`) and finally the post action `append` will append the content of the `tmpfile` to the final dotfile pointed by `somefile_final`
During installation, the `strip` action is executed before the installation, and it strips everything from the pattern `# my pattern` to the end of the file. Then the dotfile `somefile` is installed in a temporary location (here `tmpfile`) and finally the post action `append` will append the contents of the `tmpfile` to the final dotfile pointed to by `somefile_final`.
Obviously the dotfile in the dotpath should start with a unique pattern (here `# my pattern`):
Obviously, the dotfile in the dotpath should start with a unique pattern (here `# my pattern`):
```
# my pattern
this is the end

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

@@ -1,9 +1,9 @@
# Create files on install
One way for creating symlinks (or any other special files) is to use a combination of
One way to create symlinks (or any other special file) is to use a combination of
[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
Let's say, for example, you have a list of directories you want to link
from under `~/.original` to `~/symlinks`.
```bash
$ tree ~/.original
@@ -13,19 +13,19 @@ $ tree ~/.original
└── dir3
```
First you would store these directories names in a text file in your `<dotpath>/links.txt`
First you would store these directory names in a text file in your `<dotpath>/links.txt`:
```
dir1
dir2
dir3
```
The config file would contain different elements
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
* a *fake* dotfile (with no `src` and no `dst` values) that will be always installed with the above action
* 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
* A *fake* dotfile (with no `src` and no `dst` values) that will be always installed with the above action
```yaml
dynvariables:
@@ -45,7 +45,7 @@ actions:
- symlink_them '{{@@ links_list @@}}' '{{@@ links_dst @@}}'
```
The result would be
The result would be:
```bash
$ tree ~/.symlinks
/home/user/.symlinks
@@ -54,4 +54,4 @@ $ tree ~/.symlinks
└── dir3 -> /home/user/.original/dir3
```
For reference, see [issue 243](https://github.com/deadc0de6/dotdrop/issues/243)
For reference, see [issue 243](https://github.com/deadc0de6/dotdrop/issues/243).

10
docs/howto/howto.md
View File

@@ -1,4 +1,4 @@
# HowTo
# How To
## Append text to a dotfile on install
@@ -20,13 +20,13 @@
[Handle special chars](special-chars.md)
## Improve git integration
## Improve Git integration
[Improve git integration](improve-git-integration.md)
[Improve Git integration](improve-git-integration.md)
## Include file or template in template
## Include files or templates in templates
[Include file or template in template](include-in-template.md)
[Include files or templates in templates](include-in-template.md)
## Manage system dotfiles

6
docs/howto/improve-git-integration.md
View File

@@ -1,6 +1,6 @@
# Improve git integration
# Improve Git integration
The below aliases can help with the process of updating your dotfiles between multiple hosts. Add those to your `~/.zshrc` or `~/.bashrc`. You can then simply run `dotsync` to push or pull from your dotfile repository.
The below aliases can help with the process of updating your dotfiles between multiple hosts. Add them to your `~/.zshrc` or `~/.bashrc`. You can then simply run `dotsync` to push or pull from your dotfile repository.
```
# Your dotdrop git repository location
@@ -11,4 +11,4 @@ alias dotgit="git -C $DOTREPO"
alias dotsync="dotgit pull && dotgit add -A && dotgit commit && dotgit push; dotdrop install"
```
Provided by [ReekyMarko](https://github.com/ReekyMarko)
Provided by [ReekyMarko](https://github.com/ReekyMarko).

4
docs/howto/include-in-template.md
View File

@@ -1,6 +1,6 @@
# Include file or template in template
# Include files or templates in templates
[Jinja2](https://jinja.palletsprojects.com/en/2.11.x/templates/) provides the ability to include an external file/template from within a template with the directive `include`. See the [related doc](https://jinja.palletsprojects.com/en/2.11.x/templates/#include) for more. The path must be relative to the `dotpath`.
[Jinja2](https://jinja.palletsprojects.com/en/2.11.x/templates/) provides the ability to include an external file/template from within a template with the directive `include`. See the [related docs](https://jinja.palletsprojects.com/en/2.11.x/templates/#include) for more. The path must be relative to the `dotpath`.
For example:
```yaml

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

@@ -1,14 +1,14 @@
# Merge files on install
Dotdrop allows to merge multiple files into one using the jinja2's `include` directive.
Dotdrop allows you to merge multiple files into one using Jinja2's `include` directive.
For example let's consider you want to keep your `vimrc` split into multiple parts in dotdrop
For example, let's assume you want to keep your `.vimrc` split into multiple parts in dotdrop:
* `<dotpath>/vimrc.d/top`: top part of the file
* `<dotpath>/vimrc.d/bottom`: bottom part of the file
And you want dotdrop to merge all those files into `~/.vimrc` whenever you process your vimrc with dotdrop.
And you want dotdrop to merge all those files into `~/.vimrc` whenever you process your .vimrc with dotdrop.
First make sure `~/.vimrc` is present in your config file
First make sure `~/.vimrc` is present in your config file:
```yaml
...
dotfiles:
@@ -49,7 +49,7 @@ Dotdrop will then automagically include the files into your vimrc when handling
To include all files in a directory, a combination of
[dynvariables](../config-details.md#entry-dynvariables)
and [jinja2 directives](https://jinja.palletsprojects.com/en/2.11.x/) have to be used.
and [Jinja2 directives](https://jinja.palletsprojects.com/en/2.11.x/) have to be used.
Let's say all files in `<dotpath>/toinclude` need to be included into a dotfile.
@@ -61,9 +61,9 @@ dynvariables:
```
Note that `_dotdrop_dotpath` is part of the built-in variables
(for more see [template variables](../templating.md#template-variables)).
(For more, see [template variables](../templating.md#template-variables)).
And then use the generated list in the dotfile template:
Then use the generated list in the dotfile template:
```
{%@@ for f in allfiles.split() @@%}
{%@@ include f @@%}

2
docs/howto/prompt-user-for-variables.md
View File

@@ -8,7 +8,7 @@ The provided values are then automatically saved by dotdrop to `uservariables.ya
which can be included in the main config as a file from which variables are imported
using [import_variables](../config-details.md#entry-import_variables).
Let's say for example that you want to provide manually the email value
Let's say, for example, that you want to manually provide the email value
on new hosts you deploy your dotfiles to.
You'd add the following elements to your config:

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

@@ -19,33 +19,33 @@ trans_read:
_gpg: gpg2 -q --for-your-eyes-only --no-tty -d {0} > {1}
```
The above config allows to store the dotfile `~/.secret` encrypted in the *dotpath*
The above config allows you to store the dotfile `~/.secret` encrypted in the *dotpath*
directory and uses gpg to decrypt it when `install` is run.
Here's how to deploy above solution:
Here's how to deploy the above solution:
* import the clear dotfile (what creates the correct entries in the config file)
* Import the clear dotfile (what creates the correct entries in the config file):
```bash
$ dotdrop import ~/.secret
```
* encrypt the original dotfile
* Encrypt the original dotfile:
```bash
$ <some-gpg-command> ~/.secret
```
* overwrite the dotfile with the encrypted version
* Overwrite the dotfile with the encrypted version:
```bash
$ cp <encrypted-version-of-secret> dotfiles/secret
```
* edit the config file and add the transformation to the dotfile
* Edit the config file and add the transformation to the dotfile
(as shown in the example above)
* commit and push the changes
* Commit and push the changes
See [transformations](../config-details.md#entry-transformations).
@@ -59,7 +59,7 @@ trans_read:
_gpg: "gpg2 --batch --yes --passphrase-file <({{@@ gpg_password @@}}) -q --for-your-eyes-only --no-tty -d {0} > {1}"
```
Passphrase is stored in a file directly
Passphrase is stored in a file directly:
```yaml
variables:
gpg_password_file: "/tmp/the-password"

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

@@ -3,9 +3,9 @@
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
nice to share as much code as possible across the dotfiles, by leveraging
templating and merging them in the same dotfile in Dotdrop's `dotpath`. Here
are a few suggestions about how to achieve this.
nice to share as much code as possible across the dotfiles by leveraging
templating and merging them into the same dotfile in dotdrop's `dotpath`. Here
are a few suggestions about how to achieve this:
* [Brute force templating](#brute-force-templating)
* [Profile variables](#profile-variables)
@@ -13,7 +13,7 @@ are a few suggestions about how to achieve this.
## Brute force templating
The first approach is sheer use of templating and variables
The first approach is sheer use of templating and variables.
In order to do this, we need to:
1. Create the merged dotfile with an arbitrary name somewhere in `dotpath`.
@@ -38,7 +38,7 @@ export DB_HOST='{{@@ aws_db_host @@}}'
export DB_PORT='{{@@ aws_db_port @@}}'
```
Part of Dotdrop `config.yaml` file:
Part of dotdrop `config.yaml` file:
```yaml
# config.yaml
@@ -63,9 +63,9 @@ export DB_PORT='4521'
## Profile variables
Albeit flexible, the previous method is a bit cumbersome for some use cases.
The previous method, albeit flexible, is a bit cumbersome for some use cases.
For example, when the dotfiles belong to different profiles, the cleanest
solution consists in using
solution consists of using
[profile variables](../config-details.md#entry-profile-variables). This is achieved by:
1. Creating the merged dotfile with an arbitrary name somewhere in `dotpath`.
@@ -79,7 +79,7 @@ solution consists in using
An example:
The merged dotfile (`dotpath/projects/env`)
The merged dotfile (`dotpath/projects/env`):
```bash
# .env
@@ -87,7 +87,7 @@ export DB_HOST='{{@@ aws_db_host @@}}'
export DB_PORT='{{@@ aws_db_port @@}}'
```
Part of Dotdrop `config.yaml` file:
Part of dotdrop `config.yaml` file:
```yaml
# config.yaml
@@ -128,26 +128,26 @@ export DB_PORT='9632'
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
when variable values require some complex computations. In both cases the brute
when variable values require some complex computations. In both cases, the brute
force templating approach can be used, but in the latter one it also makes the
dotfiles bloated with "bookkeeping" logic, thus hard to read.
A solution for this relies in leveraging Jinja macros. This method is a
variation of the brute force templating one, where the merged dotfile is
included from many different dotfiles in `dotpath` via jinja macros, rather
variation of the brute force templating one where the merged dotfile is
included from many different dotfiles in `dotpath` via Jinja macros rather
than via many `dotfile` entries with the same `src` attribute. This way, the
merged original dotfiles stays clean as in the profile variables solution,
merged original dotfiles stays clean as in the profile variables solution
because computations are in other files.
The steps to achieve this are:
1. Creating the merged dotfile with an arbitrary name somewhere in `dotpath`.
2. Wrapping the whole content of the merged dotfile in a jinja macro, with the
2. Wrapping the whole content of the merged dotfile in a Jinja macro with the
necessary parameters.
3. Calling the macro in each original dotfiles, computing the parameters there.
3. Calling the macro in each original dotfile, computing the parameters there.
**NOTE**: The merged dotfile will be empty, as it only contains a jinja macro.
If it needs not to be deployed, the `ignoreempty` entry can be set to
**NOTE**: The merged dotfile will be empty, as it only contains a Jinja macro.
If it needs to not be deployed, the `ignoreempty` entry can be set to
`true` in `config.yaml`.
As usual, an example:
@@ -162,7 +162,7 @@ export DB_PORT='{{@@ db_port @@}}'
{%@@ endmacro @@%}
```
Server0's environment file (`projects/server0/.env`)
Server0's environment file (`projects/server0/.env`):
```jinja2
{%@@ from projects/env import env @@%}
@@ -182,14 +182,14 @@ Server0's environment file (`projects/server0/.env`)
{{@@ env(db_host, db_port) @@}}
```
Server1's environment file (`projects/server1/.env`)
Server1's environment file (`projects/server1/.env`):
```jinja2
{%@@ from projects/env import env @@%}
{{@@ env('average-host.com', 9632) @@}}
```
Part of Dotdrop `config.yaml` file:
Part of dotdrop `config.yaml` file:
```yaml
# config.yaml
@@ -203,7 +203,6 @@ dotfiles:
server1-env:
src: projects/server1/.env
dst: ~/projects/server1/.env
```
With this configuration, installing the dotfile `server0-env-local-dbg` will

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

@@ -8,8 +8,8 @@
## Detect encoding
Text file encoding can be identified using for example `file -b <file-path>` or in vim
with `:set fileencoding`
Text file encoding can be identified using, for example, `file -b <file-path>` or in vim
with `:set fileencoding`.
Here's an example of encoding that will fully work with dotdrop:
```bash
@@ -27,19 +27,20 @@ ISO-8859 text, with escape sequences
### 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.
The use of dotfiles with DOS/Windows line endings (CRLF, `\r\n`) will result in
the comparison (`compare`) returning a difference where there is none.
This is due to Jinja2 stripping CRLF.
One solution is to use `dos2unix` to re-format the dotfiles before adding them to dotdrop.
One solution is to use `dos2unix` to re-format the dotfiles before adding them
to dotdrop.
See <https://github.com/deadc0de6/dotdrop/issues/42>.
### Non-unicode chars
### Non-Unicode chars
Jinja2 is not able to process non-unicode chars (<https://jinja.palletsprojects.com/en/2.11.x/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 (<https://jinja.palletsprojects.com/en/2.11.x/api/>). This means that dotfiles using non-Unicode chars can still be fully managed by dotdrop; however, when comparing the local file with the one stored in dotdrop, `compare` will return a difference even if there is none.
Either replace the non-unicode chars (see below [Re-encode](#re-encode)) or accept the fact the comparison shows a difference while there's none.
Either replace the non-Unicode chars (see below [Re-encode](#re-encode)) or accept the fact the comparison shows a difference while there's none.
See <https://github.com/deadc0de6/dotdrop/issues/42>.

8
docs/howto/store-compressed-directories.md
View File

@@ -1,6 +1,6 @@
# Handle compressed directories
This is an example on how to use transformations (`trans_read` and `trans_write`) to store
This is an example of how to use transformations (`trans_read` and `trans_write`) to store
compressed directories and deploy them with dotdrop.
Config file:
@@ -25,12 +25,12 @@ profiles:
- d_somedir
```
The *read* transformation `uncompress` is used to execute below command before deploying the dotfile (where `{0}` is the source and `{1}` the destination)
The *read* transformation `uncompress` is used to execute the below command before deploying the dotfile (where `{0}` is the source and `{1}` the destination):
```
mkdir -p {1} && tar -xf {0} -C {1}
```
And the *write* transformation `compress` is run when updating the dotfile directory by compressing it (where `{0}` is the source and `{1}` the destination)
And the *write* transformation `compress` is run when updating the dotfile directory by compressing it (where `{0}` is the source and `{1}` the destination):
```
tar -cf {1} -C {0} .
```
```

50
docs/howto/symlink-dotfiles.md
View File

@@ -1,34 +1,34 @@
# Symlink dotfiles
Dotdrop offers two ways to symlink a dotfile through its
config entry `link`
config entry `link`:
* setting `link: link` for a dotfile will symlink `dst` to `src`
* setting `link: link_children` will, for every direct children of `src`, symlink `dst/<childrenX>` to `src/<childrenX>` (see [Link children](#link-children))
* Setting `link: link` for a dotfile will symlink `dst` to `src`
* Setting `link: link_children` will, for every direct child of `src`, symlink `dst/<childrenX>` to `src/<childrenX>` (See [Link children](#link-children))
Where `src` is considered as the file stored in your *dotpath* and
`dst` as the file located in your `$HOME`.
where `src` is the file stored in your *dotpath* and
`dst` is the file located in your `$HOME`.
Note that if the dotfile is using template directives, it will be symlinked into
Note that if the dotfile uses template directives, it will be symlinked into
`~/.config/dotdrop` instead of directly into your *dotpath*
(see [Templating symlinked dotfiles](#templating-symlinked-dotfiles))
Although the config entries `link_on_import` and `link_dotfile_default` can be set to the value `link_children`,
it is not recommended since operations on a dotfile that is not a directory with the option `link_children`
it is not recommended, since operations on a dotfile that is not a directory with the option `link_children`
will fail.
## Symlink a dotfile
Below is the ad-hoc way when [link_dotfile_default](https://dotdrop.readthedocs.io/en/latest/config-format/#config-entry)
Below is an ad-hoc way to symlink a dotfile when [link_dotfile_default](https://dotdrop.readthedocs.io/en/latest/config-format/#config-entry)
and [link_on_import](https://dotdrop.readthedocs.io/en/latest/config-format/#config-entry) use their default values.
import the file
Import the file:
```bash
$ ./dotdrop.sh import ~/.bashrc
-> "/home/user/.bashrc" imported
```
edit the `config.yaml` and set the `link` value to `link`
Edit the `config.yaml` and set the `link` value to `link`:
```yaml
dotfiles:
f_bashrc:
@@ -37,7 +37,7 @@ dotfiles:
link: link
```
install the dotfile what will remove your `~/.bashrc` and replace it with a link to the file stored in dotdrop
Install the dotfile, which will remove your `~/.bashrc` and replace it with a link to the file stored in dotdrop:
```bash
$ ./dotdrop.sh install
Remove "/home/user/.bashrc" for link creation? [y/N] ? y
@@ -46,7 +46,7 @@ Remove "/home/user/.bashrc" for link creation? [y/N] ? y
1 dotfile(s) installed.
```
The dotfile then points to the file in dotdrop
The dotfile then points to the file in dotdrop:
```bash
$ readlink ~/.bashrc
/home/user/dotdrop/dotfiles/bashrc
@@ -55,16 +55,16 @@ $ readlink ~/.bashrc
## Link children
The `link_children` option 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
directory to be symlinked but still want to keep a clean config file (with a
limited number of entries).
This option set on a file that is not a directory will make any operation on the dotfile fail.
Setting this option on a file that is not a directory will make any operation on the dotfile fail.
*Make sure to do a backup of your dotfiles with something like `cp -r <my-important-dotfile>{,.bak}`*
*Make sure to do a backup of your dotfiles with something like `cp -r <my-important-dotfile>{,.bak}`.*
A good example of its use is when managing `~/.vim` with dotdrop.
Here's what it looks like when using `link: link`.
Here's what it looks like when using `link: link`:
```yaml
config:
dotpath: dotfiles
@@ -75,7 +75,7 @@ dotfiles:
link: link
```
The top directory `~/.vim` is symlinked to the `<dotpath>/vim` location
The top directory `~/.vim` is symlinked to the `<dotpath>/vim` location:
```bash
$ readlink ~/.vim
~/.dotfiles/vim/
@@ -84,12 +84,12 @@ after autoload plugged plugin snippets spell swap vimrc
```
As a result, all files under `~/.vim` will be managed by
dotdrop (including unwanted directories like `spell`, `swap`, etc).
dotdrop (including unwanted directories like `spell`, `swap`, etc.).
A cleaner solution is to use `link_children` which allows to only symlink
A cleaner solution is to use `link_children` which allows you to only symlink
files under the dotfile directory. Let's say only `after`, `plugin`, `snippets`, and `vimrc`
need to be managed in dotdrop. `~/.vim` is imported in dotdrop, cleaned off all unwanted
files/directories and then the `link` entry is set to `link_children` in the config file.
need to be managed in dotdrop. `~/.vim` is imported in dotdrop and cleaned of all unwanted
files/directories, and then the `link` entry is set to `link_children` in the config file:
```yaml
config:
dotpath: dotfiles
@@ -120,15 +120,15 @@ $ tree -L 1 ~/.vim
## Templating symlinked dotfiles
For dotfiles not using any templating directives, those are directly linked
Dotfiles not using any templating directives are directly linked
to dotdrop's `dotpath` directory (see [Config](../config.md)).
When using templating directives however the dotfiles are first installed into
`workdir` (defaults to *~/.config/dotdrop*, see [Config](../config.md))
When using templating directives, however, the dotfiles are first installed into
`workdir` (defaults to *~/.config/dotdrop*; see [Config format](../config-format.md))
and then symlinked there.
This applies to both dotfiles with `link: link` and `link: link_children`.
For example
For example:
```bash
# with template
/home/user/.xyz -> /home/user/.config/dotdrop/.xyz

14
docs/howto/system-config-files.md
View File

@@ -1,18 +1,18 @@
# Manage system dotfiles
Dotdrop doesn't allow to handle file owernership (at least not directly). Every file operations (create/copy file/directory, create symlinks, etc) are executed with the rights of the user calling dotdrop.
Dotdrop doesn't allow you to handle file owernership (at least not directly). Every file operation (create/copy file/directory, create symlinks, etc.) is executed with the rights of the user calling dotdrop.
Using dotdrop with `sudo` to unprivileged and privileged files in the same *session* is a bad idea as the resulting files will all have messed up owners.
Using dotdrop with `sudo` to manage unprivileged and privileged files in the same *session* is a bad idea as the resulting files will all have messed-up owners.
It is therefore recommended to have two different config files (and thus two different *dotpath*)
It is therefore recommended to have two different config files (and thus two different *dotpath*s)
for handling these two uses cases:
For example:
* one `config-user.yaml` for the local/user dotfiles (with its dedicated *dotpath*, for example `dotfiles-user`)
* one `config-root.yaml` for the system/root dotfiles (with its dedicated *dotpath*, for example `dotfiles-root`)
* One `config-user.yaml` for the local/user dotfiles (with its dedicated *dotpath*, for example `dotfiles-user`)
* One `config-root.yaml` for the system/root dotfiles (with its dedicated *dotpath*, for example `dotfiles-root`)
`config-user.yaml` is used when managing the user's dotfiles
`config-user.yaml` is used when managing the user's dotfiles:
```bash
## user config file is config-user.yaml
$ ./dotdrop.sh import --cfg config-user.yaml <some-dotfile>
@@ -20,7 +20,7 @@ $ ./dotdrop.sh install --cfg config-user.yaml
...
```
`config-root.yaml` is used when managing system's dotfiles and is to be used with `sudo` or directly by the root user
`config-root.yaml` is used when managing the system's dotfiles and is to be used with `sudo` or directly by the root user:
```bash
## root config file is config-root.yaml
$ sudo ./dotdrop.sh import --cfg=config-root.yaml <some-dotfile>

54
docs/installation.md
View File

@@ -2,14 +2,14 @@
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
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
[Pypi package in a virtualenv](#pypi-package-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
The following will create a git repository for your dotfiles and
The following will create a Git repository for your dotfiles and
keep dotdrop as a submodule:
```bash
## create the repository
@@ -25,15 +25,15 @@ $ ./dotdrop/bootstrap.sh
$ ./dotdrop.sh --help
```
For MacOS users, make sure to install `realpath` through homebrew
For macOS users, make sure to install `realpath` through Homebrew
(part of *coreutils*).
Using this solution will need you to work with dotdrop by
Using this solution will require you to work with dotdrop by
using the generated script `dotdrop.sh` at the root
of your dotfiles repository.
To ease the use of dotdrop, it is recommended to add an alias to it in your
shell with the config file path, for example
shell with the config file path; for example:
```
alias dotdrop=<absolute-path-to-dotdrop.sh> --cfg=<path-to-your-config.yaml>'
```
@@ -58,7 +58,7 @@ $ ./dotdrop/bootstrap.sh
$ ./dotdrop.sh --help
```
When using a virtualenv, make sure to source the environment before using dotdrop
When using a virtualenv, make sure to source the environment before using dotdrop:
```bash
$ source env/bin/activate
$ ./dotdrop.sh --help
@@ -66,18 +66,18 @@ $ ./dotdrop.sh --help
Then follow the instructions under [As a submodule](#as-a-submodule).
## Pypi package
## PyPI package
Install dotdrop
Install dotdrop:
```bash
$ pip3 install dotdrop --user
```
and then [setup your repository](repository-setup.md).
and then [set up your repository](repository-setup.md).
## Pypi package in a virtualenv
## PyPI package in a virtualenv
Install dotdrop in a virtualenv from pypi
Install dotdrop from PyPI in a virtualenv:
```bash
$ virtualenv -p python3 env
$ source env/bin/activate
@@ -91,14 +91,14 @@ $ source env/bin/activate
$ dotdrop --help
```
Then follow the instructions under [Pypi package](#pypi-package).
Then follow the instructions under [PyPI package](#pypi-package).
## 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/>
Make sure to install the [python-magic-ahupp](https://aur.archlinux.org/packages/python-magic-ahupp/) from aur.
@@ -106,16 +106,16 @@ Then follow the [doc to setup your repository](repository-setup.md).
## Snap package
Dotdrop is available as a snap package: <https://snapcraft.io/dotdrop>
Dotdrop is available as a snap package: <https://snapcraft.io/dotdrop>.
Install it with
Install it with:
```bash
snap install dotdrop
```
Then follow the [doc to setup your repository](repository-setup.md).
If you encounter warnings like `Warning: using regular magic file`
If you encounter warnings like `Warning: using regular magic file`,
try defining the following environment variable:
```bash
export MAGIC=$SNAP/usr/share/file/magic.mgc
@@ -123,7 +123,7 @@ export MAGIC=$SNAP/usr/share/file/magic.mgc
## From source
Clone the repository
Clone the repository:
```bash
$ git clone https://github.com/deadc0de6/dotdrop.git
```
@@ -138,14 +138,14 @@ $ ./dotdrop.sh --cfg <my-config-file> files
## Dependencies
Beside the python dependencies defined in [requirements.txt](https://github.com/deadc0de6/dotdrop/blob/master/requirements.txt),
dotdrop depends on following tools:
Beside the Python dependencies defined in [requirements.txt](https://github.com/deadc0de6/dotdrop/blob/master/requirements.txt),
dotdrop depends on the following tools:
* `diff`
* `git` (only if using the entry point script [dotdrop.sh](https://github.com/deadc0de6/dotdrop/blob/master/dotdrop.sh))
* `readlink` or `realpath` (only if using the entry point script [dotdrop.sh](https://github.com/deadc0de6/dotdrop/blob/master/dotdrop.sh))
For MacOS users, make sure to install below packages through [homebrew](https://brew.sh/):
For macOS users, make sure to install the below packages through [Homebrew](https://brew.sh/):
* [coreutils](https://formulae.brew.sh/formula/coreutils) (only if using the entry point script [dotdrop.sh](https://github.com/deadc0de6/dotdrop/blob/master/dotdrop.sh) which uses realpath)
* [libmagic](https://formulae.brew.sh/formula/libmagic) (for python-magic)
@@ -162,13 +162,13 @@ is auto-updated through the [dotdrop.sh](https://github.com/deadc0de6/dotdrop/bl
script by defining the environment variable `DOTDROP_AUTOUPDATE=yes`.
If undefined, `DOTDROP_AUTOUPDATE` will take the value `yes`.
If used as a submodule, update it with
If used as a submodule, update it with:
```bash
$ git submodule update --init --recursive
$ git submodule update --remote dotdrop
```
You will then need to commit the changes with
You will then need to commit the changes with:
```bash
$ git add dotdrop
$ git commit -m 'update dotdrop'
@@ -180,7 +180,7 @@ $ git push
If you wish to get a specific version of dotdrop when using
it as a submodule, the following operations can be done.
Here dotdrop is downgraded to the latest stable version
Here dotdrop is downgraded to the latest stable version:
```bash
## enter the repository containing the dotdrop submodule
$ cd my-dotfiles
@@ -197,11 +197,9 @@ automatically update dotdrop back to the latest commit.
## Shell completion
Completion scripts exist for `bash`, `zsh` and `fish`,
Completion scripts exist for `bash`, `zsh` and `fish`;
see [the related doc](https://github.com/deadc0de6/dotdrop/blob/master/completion/README.md).
## Highlighters
Highlighters for dotdrop templates are available [here](https://github.com/deadc0de6/dotdrop/tree/master/highlighters).

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

@@ -5,10 +5,10 @@ Only do the following if you are using dotdrop version `< 0.7.1` or if you encou
---
Initially dotdrop was only available as a submodule directly in the
dotfiles git tree. When updated to work with pypi, some code changed
dotfiles git tree. When updated to work with PyPI, some code changed
that brought some issues to older versions.
If you want to keep it as a submodule (recommended), simply do the following
If you want to keep it as a submodule (recommended), simply do the following:
```bash
$ cd <dotfiles-directory>
@@ -30,40 +30,40 @@ $ git commit -m 'update dotdrop.sh'
$ git push
```
Otherwise, simply install it from pypi as shown below:
Otherwise, simply install it from PyPI as shown below:
* move to the dotfiles directory where dotdrop is used as a submodule
* Move to the dotfiles directory where dotdrop is used as a submodule
```bash
$ cd <dotfiles-repository>
```
* remove the entire `submodule "dotdrop"` section in `.gitmodules`
* stage the changes
* Remove the entire `submodule "dotdrop"` section in `.gitmodules`
* Stage the changes
```bash
$ git add .gitmodules
```
* remove the entire `submodule "dotdrop"` section in `.git/config`
* remove the submodule
* Remove the entire `submodule "dotdrop"` section in `.git/config`
* Remove the submodule
```bash
$ git rm --cached dotdrop
```
* remove the submodule from .git
* Remove the submodule from .git
```bash
$ rm -rf .git/modules/dotdrop
```
* commit the changes
* Commit the changes
```bash
$ git commit -m 'removing dotdrop submodule'
```
* remove any remaining files from the dotdrop submodule
* Remove any remaining files from the dotdrop submodule
```bash
$ rm -rf dotdrop
```
* remove `dotdrop.sh`
* Remove `dotdrop.sh`
```bash
$ git rm dotdrop.sh
$ git commit -m 'remove dotdrop.sh script'
```
* push upstream
* Push upstream
```bash
$ git push
```

6
docs/misc/people-using-dotdrop.md
View File

@@ -1,4 +1,4 @@
For more examples, see how people are using dotdrop
For more examples, see how people are using dotdrop:
* [https://github.com/open-dynaMIX/dotfiles](https://github.com/open-dynaMIX/dotfiles)
* [https://github.com/moyiz/dotfiles](https://github.com/moyiz/dotfiles)
@@ -7,6 +7,6 @@ For more examples, see how people are using dotdrop
* [https://github.com/Eluminae/dotfiles](https://github.com/Eluminae/dotfiles)
* [https://github.com/davla/dotfiles](https://github.com/davla/dotfiles) and [https://github.com/davla/setup](https://github.com/davla/setup)
Dotfiles repository using dotdrop on [github](https://github.com/topics/dotdrop?o=desc&s=updated) and [gitlab](https://gitlab.com/search?search=dotdrop).
Dotfiles repositories using dotdrop on [GitHub](https://github.com/topics/dotdrop?o=desc&s=updated) and [GitLab](https://gitlab.com/search?search=dotdrop).
Or search directly on [github](https://github.com/search?q=filename%3Aconfig.yaml+dotdrop&type=Code) for config examples.
Or search directly on [GitHub](https://github.com/search?q=filename%3Aconfig.yaml+dotdrop&type=Code) for config examples.

6
docs/repository-setup.md
View File

@@ -1,6 +1,6 @@
# Repository setup
Either create a git repository on your prefered platform and clone it or create one locally.
Either create a Git 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
@@ -15,12 +15,12 @@ $ 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
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,
(*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

92
docs/templating.md
View File

@@ -1,49 +1,49 @@
# Templating
Dotdrop leverage the power of [jinja2](https://palletsprojects.com/p/jinja/) to handle the
templating of dotfiles. See [jinja2 template doc](https://jinja.palletsprojects.com/en/2.11.x/templates/)
Dotdrop leverages the power of [Jinja2](https://palletsprojects.com/p/jinja/) to handle the
templating of dotfiles. See [the Jinja2 templates docs](https://jinja.palletsprojects.com/en/2.11.x/templates/)
or the below sections for more information on how to template your dotfiles.
## Templating or not templating
The dotfile config entry [template](config-format.md#dotfiles-entry)
and the global config entry [template_dotfile_default](config-format.md#config-entry)
allow to control if a dotfile is being process by the templating engine.
allow you to control whether a dotfile is processed by the templating engine.
Obviously if the dotfile uses template directives, it needs to be templated. However if it
Obviously, if the dotfile uses template directives, it needs to be templated. However, if it
is not, disabling templating will speed up its installation (since it won't have to be
processed by the engine).
For dotfiles being symlinked (`link` or `link_children`), see
[the dedicated doc](howto/symlink-dotfiles.md#templating-symlinked-dotfiles)
[the dedicated doc](howto/symlink-dotfiles.md#templating-symlinked-dotfiles).
## Delimiters
Dotdrop uses different delimiters than
[jinja2](https://palletsprojects.com/p/jinja/)'s defaults:
[Jinja2](https://palletsprojects.com/p/jinja/)'s defaults:
* block/statement start = `{%@@`
* block/statement end = `@@%}`
* variable/expression start = `{{@@`
* variable/expression end = `@@}}`
* comment start = `{#@@`
* comment end = `@@#}`
* Block/statement start = `{%@@`
* Block/statement end = `@@%}`
* Variable/expression start = `{{@@`
* Variable/expression end = `@@}}`
* Comment start = `{#@@`
* Comment end = `@@#}`
More info in [jinja2 templating doc](https://jinja.palletsprojects.com/en/2.11.x/templates/?highlight=delimiter)
More info in [Jinja2 templating docs](https://jinja.palletsprojects.com/en/2.11.x/templates/?highlight=delimiter)
## Template variables
Following variables are available in templates:
The following variables are available in templates:
* `{{@@ profile @@}}` contains the profile provided to dotdrop.
* `{{@@ env['MY_VAR'] @@}}` contains environment variables (see [Environment variables](#environment-variables)).
* `{{@@ header() @@}}` contains dotdrop header (see [Dotdrop header](#dotdrop-header)).
* `{{@@ header() @@}}` contains the dotdrop header (see [Dotdrop header](#dotdrop-header)).
* `{{@@ _dotdrop_dotpath @@}}` contains the [dotpath](config-format.md) absolute path.
* `{{@@ _dotdrop_cfgpath @@}}` contains the absolute path to the [config file](config.md).
* `{{@@ _dotdrop_workdir @@}}` contains the [workdir](config-format.md) absolute path.
* dotfile specific variables (see [Dotfile variables](#dotfile-variables))
* all defined config variables (see [Variables](config.md#variables)).
* all defined config interpreted variables (see [Interpreted variables](config-details.md#entry-dynvariables)).
* Dotfile specific variables (see [Dotfile variables](#dotfile-variables))
* All defined config variables (see [Variables](config.md#variables))
* All defined config interpreted variables (see [Interpreted variables](config-details.md#dynvariables-entry))
## Dotfile variables
@@ -54,20 +54,20 @@ When a dotfile is handled by dotdrop, the following variables are added:
* `{{@@ _dotfile_key @@}}` contains the processed dotfile key.
* `{{@@ _dotfile_link @@}}` contains the processed dotfile `link` string value.
Additionally to the above, the following variables are set in each file processed by dotdrop.
In addition to the above, the following variables are set in each file processed by dotdrop:
* `{{@@ _dotfile_sub_abs_src @@}}` contains the absolute source path of each file when handled by dotdrop.
* `{{@@ _dotfile_sub_abs_dst @@}}` contains the absolute destination path of each file when handled by dotdrop.
For example a directory dotfile (like `~/.ssh`) would process several files
For example, a directory dotfile (like `~/.ssh`) would process several files
(`~/.ssh/config` and `~/.ssh/authorized_keys`, for example). In `~/.ssh/config`:
(`~/.ssh/config` and `~/.ssh/authorized_keys` for example). In `~/.ssh/config`:
* `_dotfile_abs_dst` would be `/home/user/.ssh`
* `_dotfile_sub_abs_dst` would be `/home/user/.ssh/config`
## Environment variables
It's possible to access environment variables inside the templates.
It's possible to access environment variables inside the templates:
```
{{@@ env['MY_VAR'] @@}}
```
@@ -75,14 +75,14 @@ It's possible to access environment variables inside the templates.
This allows for storing host-specific properties and/or secrets in environment variables.
It is recommended to use `variables` (see [config variables](config.md#variables))
instead of environment variables unless these contain sensitive information that
shouldn't be versioned in git.
shouldn't be versioned in Git.
For example you can have a `.env` file in the directory where your `config.yaml` lies:
For example, you can have an `.env` file in the directory where your `config.yaml` lies:
```
## Some secrets
pass="verysecurepassword"
```
If this file contains secrets that should not be tracked by git,
If this file contains secrets that should not be tracked by Git,
put it in your `.gitignore`.
You can then invoke dotdrop with the help of an alias
@@ -99,30 +99,30 @@ The above aliases load all the variables from `~/dotfiles/.env`
## Template methods
Beside [jinja2 global functions](https://jinja.palletsprojects.com/en/2.11.x/templates/#list-of-global-functions)
the following methods can be used within the templates:
Besides [Jinja2 global functions](https://jinja.palletsprojects.com/en/2.11.x/templates/#list-of-global-functions),
the following methods can be used within templates:
* `exists(path)`: return true when path exists
* `exists(path)`: returns true when path exists
```
{%@@ if exists('/dev/null') @@%}
it does exist
{%@@ endif @@%}
```
* `exists_in_path(name, path=None)`: return true when executable exists in `$PATH`
* `exists_in_path(name, path=None)`: returns true when executable exists in `$PATH`
```
{%@@ if exists_in_path('exa') @@%}
alias ls='exa --git --color=always'
{%@@ endif @@%}
```
* `basename(path)`: return the `basename` of the path argument
* `basename(path)`: returns the `basename` of the path argument
```
{%@@ set dotfile_filename = basename( _dotfile_abs_dst ) @@%}
dotfile dst filename: {{@@ dotfile_filename @@}}
```
* `dirname(path)`: return the `dirname` of the path argument
* `dirname(path)`: returns the `dirname` of the path argument
```
{%@@ set dotfile_dirname = dirname( _dotfile_abs_dst ) @@%}
dotfile dst dirname: {{@@ dotfile_dirname @@}}
@@ -133,20 +133,20 @@ config entry `func_file`.
Example:
the config file
The config file:
```yaml
config:
func_file:
- /tmp/myfuncs_file.py
```
the python function under `/tmp/myfuncs_file.py`
The python function under `/tmp/myfuncs_file.py`:
```python
def myfunc(arg):
return not arg
```
the dotfile content
The dotfile content:
```
{%@@ if myfunc(False) @@%}
this should exist
@@ -155,44 +155,44 @@ this should exist
## Template filters
Beside [jinja2 builtin filters](https://jinja.palletsprojects.com/en/2.11.x/templates/#builtin-filters)
Besides [Jinja2 builtin filters](https://jinja.palletsprojects.com/en/2.11.x/templates/#builtin-filters),
custom user-defined filter functions can be loaded using the config entry `filter_file`:
Example:
the config file
The config file:
```yaml
config:
filter_file:
- /tmp/myfilter_file.py
```
the python filter under `/tmp/myfilter_file.py`
The python filter under `/tmp/myfilter_file.py`:
```python
def myfilter(arg1):
return str(int(arg1) - 10)
```
the dotfile content
The dotfile content:
```
{{@@ "13" | myfilter() @@}}
```
For more information on how to create filters,
see [jinja2 official doc](https://jinja.palletsprojects.com/en/2.11.x/api/#writing-filters).
see [the Jinja2 official docs](https://jinja.palletsprojects.com/en/2.11.x/api/#writing-filters).
## Import macros
## Importing macros
Macros must be imported `with context` in order to have access to the variables:
```
{%@@ from 'macro_file' import macro with context @@%}
```
For more see the [dedicated jinja2 doc](https://jinja.palletsprojects.com/en/2.11.x/templates/#macros).
For more information, see the [dedicated Jinja2 docs](https://jinja.palletsprojects.com/en/2.11.x/templates/#macros).
## Dotdrop header
Dotdrop is able to insert a header in the generated dotfiles. This allows
Dotdrop is able to insert a header in the generated dotfiles. This allows you
to remind anyone opening the file for editing that this file is managed by dotdrop.
Here's what it looks like:
@@ -205,13 +205,13 @@ The header can be automatically added with:
{{@@ header() @@}}
```
Properly commenting the header in templates is the responsibility of the user
as [jinja2](https://palletsprojects.com/p/jinja/) has no way of knowing what is the proper char(s) used for comments.
Properly commenting the header in templates is the responsibility of the user,
as [Jinja2](https://palletsprojects.com/p/jinja/) has no way of knowing what is the proper char(s) used for comments.
Either prepend the directive with the commenting char(s) used in the dotfile
(for example `# {{@@ header() @@}}`) or provide it as an argument `{{@@ header('# ') @@}}`.
The result is equivalent.
The results are equivalent.
## Debug templates
## Debugging templates
To debug the result of a template, one can install the dotfiles to a temporary
directory with the `install` command and the `-t` switch:

140
docs/usage.md
View File

@@ -4,18 +4,18 @@ Run `dotdrop --help` to see all available options.
## Basic usage
The basic use of dotdrop is
The basic use of dotdrop is:
* import a file/directory to manage (this will copy the files from the filesystem to your `dotpath`): `dotdrop import <somefile>`
* install the dotfiles (will *copy/link* those from your `dotpath` to the filesystem): `dotdrop install`
* Import a file/directory to manage (this will copy the files from the filesystem to your `dotpath`): `dotdrop import <somefile>`
* Install the dotfiles (this will *copy/link* them from your `dotpath` to the filesystem): `dotdrop install`
Then if you happen to update the file/directory directly on the filesystem (add new file/dir, edit content, etc) you can use the `update` command to mirror back those changes in dotdrop.
Then if you happen to update the file/directory directly on the filesystem (add a new file/dir, edit content, etc.) you can use the `update` command to mirror back those changes in dotdrop.
For more advanced uses:
* `dotdrop --help` for the cli usage.
* [the example](https://github.com/deadc0de6/dotdrop#getting-started)
* [the howto](howto/howto.md)
* `dotdrop --help` for the CLI usage.
* [The example](https://github.com/deadc0de6/dotdrop#getting-started)
* [The howto](howto/howto.md)
## Profile
@@ -23,17 +23,17 @@ The default profile used by dotdrop is the *hostname* of the host you are runnin
It can be changed:
* using the command line switch `-p --profile=<profile>`
* by defining it in the env variable `DOTDROP_PROFILE`
* Using the command line switch `-p`/`--profile=<profile>`
* By defining it in the env variable `DOTDROP_PROFILE`
## Import dotfiles
The `import` command imports dotfiles to be managed by dotdrop.
It copies the dotfile to your `dotpath` and updates the config file with the new entry.
Dotdrop will ask for dereferencing symlinks on import unless `-f --force` is used.
Dotdrop will ask whether to dereference symlinks on import unless `-f`/`--force` is used.
For example to import `~/.xinitrc`
For example, to import `~/.xinitrc`:
```bash
$ dotdrop import ~/.xinitrc
-> "/home/user/.xinitrc" imported
@@ -42,35 +42,35 @@ $ dotdrop import ~/.xinitrc
```
You can control how the dotfile key is generated in the config file
with the config entry `longkey` (per default to *false*).
with the config entry `longkey` (defaults to *false*).
Two formats are available:
* *short format* (default): take the shortest unique path
* *long format*: take the full path
For example `~/.config/awesome/rc.lua` gives
For example, `~/.config/awesome/rc.lua` gives:
* `f_rc.lua` in the short format
* `f_config_awesome_rc.lua` in the long format
Importing `~/.mutt/colors` and then `~/.vim/colors` will result in
Importing `~/.mutt/colors` and then `~/.vim/colors` will result in:
* `d_colors` and `d_vim_colors` in the short format
* `d_mutt_colors` and `d_vim_colors` in the long format
Dotfiles can be imported as a different file with the use
A dotfile can be imported as a different file with the use
of the command line switch `--as` (effectively selecting the `src` part
of the dotfile in the config). It is however recommended
to use [templating](templating.md) to avoid duplicates and optimize
dotfiles management.
dotfile management.
```bash
$ dotdrop import ~/.zshrc --as=~/.zshrc.test
```
To ignore specific pattern during import see [the ignore patterns](config.md#ignore-patterns)
To ignore specific patterns during import, see [the ignore patterns](config.md#ignore-patterns).
For more options, see the usage with `dotdrop --help`
For more options, see the usage with `dotdrop --help`.
## Install dotfiles
@@ -79,49 +79,45 @@ The `install` command installs/deploys dotfiles managed by dotdrop from the `dot
$ dotdrop install
```
The dotfile will be installed only if it differs from the version already present on its destination.
A dotfile will be installed only if it differs from the version already present at its destination.
some available options
Some available options:
* `-t --temp`: install the dotfile(s) to a temporary directory for review (it helps to debug templating issues for example).
Note that actions are not executed in that mode.
* `-a --force-actions`: force the execution of actions even if the dotfiles are not installed
* `-f --force`: do not ask any confirmation
* `-t`/`--temp`: Install the dotfile(s) to a temporary directory for review (helping to debug templating issues, for example).
Note that actions are not executed in this mode.
* `-a`/`--force-actions`: Force the execution of actions even if the dotfiles are not installed
* `-f`/`--force`: Do not ask for any confirmation
To ignore specific pattern during installation see [the ignore patterns](config.md#ignore-patterns)
To ignore specific patterns during installation, see [the ignore patterns](config.md#ignore-patterns).
For more options, see the usage with `dotdrop --help`
For more options, see the usage with `dotdrop --help`.
## Compare dotfiles
The `compare` command compares dotfiles on their destination with the one stored in your `dotpath`.
The `compare` command compares dotfiles at their destinations with the ones stored in your `dotpath`.
```bash
$ dotdrop compare
```
The diffing is done by the unix tool `diff` in the backend, one can provide its specific
The diffing is done with the UNIX tool `diff` as the backend; one can provide a specific
diff command using the config entry `diff_command`.
To ignore specific pattern, see [the ignore patterns](config.md#ignore-patterns)
To ignore specific patterns, see [the ignore patterns](config.md#ignore-patterns).
To completely ignore all files not present in `dotpath` see [ignore missing](#ignore-missing).
It is also possible to install all dotfiles for a specific profile
in a temporary directory in order to manually compare them with
the local version by using `install` and the `-t` switch.
To completely ignore all files not present in `dotpath` see [Ignore missing](#ignore-missing).
For more options, see the usage with `dotdrop --help`.
## List profiles
The `profiles` command lists defined profiles in the config file
The `profiles` command lists the profiles defined in the config file.
```bash
$ dotdrop profiles
```
Dotdrop allows to choose which profile to use
Dotdrop allows you to choose which profile to use
with the `--profile` switch if you use something
else than the default (the hostname).
other than the default (the hostname).
The default profile can also be changed by defining the
`DOTDROP_PROFILE` environment variable.
@@ -137,10 +133,10 @@ f_xinitrc
-> link: nolink
```
By using the `-T --template` switch, only the dotfiles that
By using the `-T`/`--template` switch, only the dotfiles that
are using [templating](templating.md) are listed.
It is also possible to list all files related to each dotfile entries
It is also possible to list all the files related to each dotfile entry
by invoking the `detail` command, for example:
```bash
$ dotdrop detail
@@ -151,19 +147,19 @@ f_xinitrc (dst: "/home/user/.xinitrc", link: nolink)
This is especially useful when the dotfile entry is a directory
and one wants to have information on the different files it contains
(does a specific file uses templating, etc).
(does a specific file uses templating, etc.).
For more options, see the usage with `dotdrop --help`
For more options, see the usage with `dotdrop --help`.
## Update dotfiles
The `update` commands will updates a dotfile managed by dotdrop by copying the dotfile
The `update` command updates a dotfile managed by dotdrop by copying the dotfile
from the filesystem to the `dotpath`. Only dotfiles that have differences with the stored version are updated.
A confirmation is requested from the user before any overwrite/update unless the `-f --force` switch is used.
A confirmation is requested from the user before any overwrite/update unless the `-f`/`--force` switch is used.
Either provide the path of the file containing the new version of the dotfile or
provide the dotfile key to update (as found in the config file) along with the `-k --key` switch.
When using the `-k --key` switch and no key is provided, all dotfiles for that profile are updated.
provide the dotfile key to update (as found in the config file) along with the `-k`/`--key` switch.
When using the `-k`/`--key` switch and no key is provided, all dotfiles for that profile are updated.
```bash
## update by path
$ dotdrop update ~/.vimrc
@@ -174,16 +170,16 @@ $ dotdrop update --key f_vimrc
If not argument is provided, all dotfiles for the selected profile are updated.
To ignore specific pattern, see [the dedicated page](config.md#ignore-patterns)
To ignore specific patterns, see [the dedicated page](config.md#ignore-patterns).
To completely ignore all files not present in `dotpath` see [ignore missing](#ignore-missing).
To completely ignore all files not present in `dotpath`, see [Ignore missing](#ignore-missing).
There are two cases when updating a dotfile:
### The dotfile doesn't use [templating](templating.md)
The new version of the dotfile is copied to the *dotpath* directory and overwrites
the old version. If git is used to version the dotfiles stored by dotdrop, the git command
the old version. If Git is used to version the dotfiles stored by dotdrop, the Git command
`diff` can be used to view the changes.
```bash
@@ -193,18 +189,18 @@ $ git diff
### The dotfile uses [templating](templating.md)
The dotfile must be manually updated, three solutions can be used to identify the
The dotfile must be manually updated; three solutions can be used to identify the
changes to apply to the template:
* Use the `compare` command
* Use the `compare` command:
```bash
## use compare to identify change(s)
$ dotdrop compare --file=~/.vimrc
```
* Call `update` with the `-P --show-patch` switch that will provide with an ad-hoc solution
to manually patch the template file using a temporary generated version of the template
(this isn't a bullet proof solution and might need manual checking)
* Call `update` with the `-P`/`--show-patch` switch, which provides an ad-hoc solution
to manually patch the template file using a temporary generated version of the template.
(This isn't a bullet-proof solution and might need manual checking.)
```bash
## get an ad-hoc solution to manually patch the template
$ dotdrop update --show-patch ~/.vimrc
@@ -213,7 +209,7 @@ $ dotdrop update --show-patch ~/.vimrc
```
* Install the dotfiles to a temporary directory (using the `install` command and the
`-t` switch) and compare the generated dotfile with the local one.
`-t` switch) and compare the generated dotfile with the local one:
```bash
## use install to identify change(s)
$ dotdrop install -t -t f_vimrc
@@ -223,17 +219,17 @@ $ diff ~/.vimrc /tmp/dotdrop-6ajz7565/home/user/.vimrc
## Remove dotfiles
The command `remove` allows to stop managing a specific dotfile with
The command `remove` allows you to stop managing a specific dotfile with
dotdrop. It will:
* remove the entry in the config file (under `dotfiles` and `profile`)
* remove the entry from the config file (under `dotfiles` and `profile`)
* remove the file from the `dotpath`
For more options, see the usage with `dotdrop --help`
For more options, see the usage with `dotdrop --help`.
## Concurrency
The command line switch `-w --workers` if set to a value greater than one allows to use
The command line switch `-w`/`--workers`, if set to a value greater than one, allows you to use
multiple concurrent workers to execute an operation. It can be applied to the following
commands:
@@ -244,37 +240,37 @@ commands:
It should be set to a maximum of the number of cores available (usually returned
on linux by the command `nproc`).
It may speed up the operation but cannot be used interractively (it needs `-f --force` to be set
except for `compare`) and cannot be used with `-d --dry`. Also information printed to stdout/stderr
It may speed up the operation but cannot be used interactively (it needs `-f`/`--force` to be set
except for `compare`) and cannot be used with `-d`/`--dry`. Also, information printed to stdout/stderr
will probably be messed up.
**WARNING** this feature hasn't been extensively tested and is to be used at your own risk.
If you try it out and find any issue, please [report it](https://github.com/deadc0de6/dotdrop/issues).
Also if you find it useful and have been able to successfully speed up your operation when using
`-w --workers`, do please also report it [in an issue](https://github.com/deadc0de6/dotdrop/issues).
**WARNING:** This feature hasn't been extensively tested and is to be used at your own risk.
If you try it out and find any issues, please [report them](https://github.com/deadc0de6/dotdrop/issues).
Also, if you find it useful and have been able to successfully speed up your operation when using
`-w`/`--workers`, do please also report it [in an issue](https://github.com/deadc0de6/dotdrop/issues).
## Environment variables
Following environment variables can be used to specify different CLI options.
The following environment variables can be used to specify different CLI options.
Note that CLI switches take precedence over environment variables (except for `DOTDROP_FORCE_NODEBUG`)
* `DOTDROP_PROFILE`: `-p --profile`
* `DOTDROP_PROFILE`: `-p`/`--profile`
```bash
export DOTDROP_PROFILE="my-fancy-profile"
```
* `DOTDROP_CONFIG`: `-c --cfg`
* `DOTDROP_CONFIG`: `-c`/`--cfg`
```bash
export DOTDROP_CONFIG="/home/user/dotdrop/config.yaml"
```
* `DOTDROP_NOBANNER`: `-b --no-banner`
* `DOTDROP_NOBANNER`: `-b`/`--no-banner`
```bash
export DOTDROP_NOBANNER=
```
* `DOTDROP_DEBUG`: `-V --verbose`
* `DOTDROP_DEBUG`: `-V`/`--verbose`
```bash
export DOTDROP_DEBUG=
```
* `DOTDROP_FORCE_NODEBUG`: disable debug outputs even if `-V --verbose` is provided or `DOTDROP_DEBUG` is set
* `DOTDROP_FORCE_NODEBUG`: disable debug output even if `-V`/`--verbose` is provided or `DOTDROP_DEBUG` is set
```bash
export DOTDROP_FORCE_NODEBUG=
```
@@ -286,7 +282,7 @@ export DOTDROP_TMPDIR="/tmp/dotdrop-tmp"
```bash
export DOTDROP_WORKDIR="/tmp/dotdrop-workdir"
```
* `DOTDROP_WORKERS`: overwrite the `-w --workers` cli argument
* `DOTDROP_WORKERS`: overwrite the `-w`/`--workers` cli argument
```bash
export DOTDROP_WORKERS="10"
```
@@ -303,7 +299,7 @@ such as a cache.
Maybe you only want to change one file and don't want the others cluttering your repository.
Maybe the program changes these files quite often and creates unnecessary diffs in your dotfiles.
In these cases, you can use the [ingore-missing](config-format.md) option.
In these cases, you can use the [ignore-missing](config-format.md) option.
This option is available as a flag (`--ignore-missing` or `-z`) to the `update` and `compare` commands,
or [as a configuration option either globally or on a specific dotfile](config-format.md).

4
tests-ng/README.md
View File

@@ -1,8 +1,8 @@
These are tests for testing entire behavior through shell scripts more easily than
the overly complicated python tests.
the overly complicated Python tests.
For adding your own test, create a new script, copy the beginning of an
existing test script (before the *this is the test*) and complete it
existing test script (before the *this is the test*), and complete it
with your test.
Helper functions are available in `helpers`.