mirrors/dotdrop
1
0
Fork 0
mirror of https://github.com/deadc0de6/dotdrop.git synced 2026-02-09 18:09:17 +00:00
Code Activity

Merge pull request #322 from jwodder/proofreading

Browse Source 
Proofread docs
This commit is contained in:
deadc0de
2021-10-05 20:36:22 +02:00
committed by GitHub
parent 2c7ac514e0 7c32b1a2fc
commit e6a4e9d93d
27 changed files with 635 additions and 642 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) * [Code base](#code-base)
* [config parsing](#config-parsing) * [Config parsing](#config-parsing)
* [lower layer](#lower-layer) * [Lower layer](#lower-layer)
* [higher layer](#higher-layer) * [Higher layer](#higher-layer)
* [Precedence](#precedence) * [Precedence](#precedence)
* [variables resolution](#variables-resolution) * [Variable resolution](#variable-resolution)
* [rules](#rules) * [Rules](#rules)
* [testing](#testing) * [Testing](#testing)
* [testing with unittest](#testing-with-unittest) * [Testing with unittest](#testing-with-unittest)
* [testing with bash scripts](#testing-with-bash-scripts) * [Testing with bash scripts](#testing-with-bash-scripts)
* [documentation](#documentation) * [Documentation](#documentation)
Thanks for helping out! 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 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! 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). 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_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)) * **cfg_aggregator.py**: the higher level config parser (see [higher layer](#higher-layer))
* **comparator.py**: the class handling the comparison for `compare` * **comparator.py**: the class handling the comparison for `compare`
* **dictparser.py**: abstract class for parsing dictionaries * **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 * **dotfile.py**: represent a dotfile
* **installer.py**: the class handling the installation of dotfile for `install` * **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) * **linktypes.py**: enum for the three types of linking (none, symlink, children)
* **logger.py**: the custom logger * **logger.py**: the custom logger
* **options.py**: the class embedding all the different options across dotdrop * **options.py**: the class embedding all the different options across dotdrop
* **profile.py**: represent a profile * **profile.py**: represents a profile
* **settings.py**: represent the config settings * **settings.py**: represents the config settings
* **templategen.py**: the jinja2 templating class * **templategen.py**: the Jinja2 templating class
* **updater.py**: the class handling the update of dotfiles for `update` * **updater.py**: the class handling the update of dotfiles for `update`
* **utils.py**: some useful methods used across the code base * **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) * 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) * Then in the higher layer in [cfg_aggregator.py](/dotdrop/cfg_aggregator.py)
Only the higher layer is accessible to other classes of dotdrop. 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: and does the following:
* normalize all config entries * Normalize all config entries
* resolve paths (dotfiles src, dotpath, etc) * Resolve paths (dotfiles src, dotpath, etc)
* refactor actions/transformations to a common format * Refactor actions/transformations to a common format
* etc * Etc.
* import any data from external files (configs, variables, etc) * Import any data from external files (configs, variables, etc)
* apply variable substitutions * Apply variable substitutions
* complete any data if needed (add the "profile" variable, etc) * Complete any data if needed (add the "profile" variable, etc)
* execute intrepreted variables through the shell * Execute intrepreted variables through the shell
* write new entries (dotfile, profile) into the dictionary and save it to a file * Write new entries (dotfile, profile) into the dictionary and save it to a file
* fix any deprecated entries (link_by_default, etc) * Fix any deprecated entries (link_by_default, etc)
* clear empty entries * 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 The higher layer will transform the dictionary parsed by the lower layer
into objects (profiles, dotfiles, actions, transformations, etc). into objects (profiles, dotfiles, actions, transformations, etc).
The higher layer has no notion of inclusion (profile included for example) or The higher layer has no notion of inclusion (profile included, for example) or
file importing (import actions, etc) or even interpreted variables file importing (import actions etc.) or even interpreted variables
(it only sees variables that have already been interpreted). (it only sees variables that have already been interpreted).
It does the following: It does the following:
* transform dictionaries into objects * Transform dictionaries into objects
* patch list of keys with its corresponding object (for example dotfile's actions) * Patch lists of keys with their corresponding objects (For example, dotfile's actions)
* provide getters for every other classes of dotdrop needing to access elements * 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 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 `dirty` flag as a sign the file needs to be written and its representation in higher
levels in not accurate anymore. levels in not accurate anymore.
## precedence ## Precedence
* `dynvariables` > `variables` * `dynvariables` > `variables`
* profile `(dyn)variables` > any other `(dyn)variables` * Profile `(dyn)variables` > any other `(dyn)variables`
* profile `(dyn)variables` > profile's included `(dyn)variables` * Profile `(dyn)variables` > profile's included `(dyn)variables`
* imported `variables`/`dynvariables` > `(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. templating) in the config file.
* resolve main config file variables * Resolve main config file variables
* merge `variables` and `dynvariables` (allowing cycling reference) * Merge `variables` and `dynvariables` (allowing cyclic references)
* recursively template merged `variables` and `dynvariables` * Recursively template merged `variables` and `dynvariables`
* `dynvariables` are executed * `dynvariables` are executed
* profile's `variables` and `dynvariables` are merged * Profile's `variables` and `dynvariables` are merged
* resolve *included* entries (see below) * Resolve *included* entries (see below)
* paths and entries are templated * Paths and entries are templated
(allows to use something like `include {{@@ os @@}}.variables.yaml`) (allows using something like `include {{@@ os @@}}.variables.yaml`)
* *included* entries are processed * *included* entries are processed
* dyn-/variables are all resolved in their own file * dyn-/variables are all resolved in their own file
potential *included* entries Potential *included* entries:
* entry *import_actions* * Entry *import_actions*
* entry *import_configs* * Entry *import_configs*
* entry *import_variables* * Entry *import_variables*
* profile's *import* * Profile's *import*
* profile's *include* * Profile's *include*
Variables are then used to resolve different elements in the config file: 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 * `dynvariables` are executed in their own config file
* since `variables` and `dynvariables` are templated before the `dynvariables` * Since `variables` and `dynvariables` are templated before the `dynvariables`
are executed, this means that `dynvariables` can safely reference `variables` however are executed, this means that `dynvariables` can safely reference `variables`; however,
`variables` referencing `dynvariables` will result with the *not-executed* value of the `variables` referencing `dynvariables` will result in the *not-executed* value of the
referenced `dynvariables` (see examples below) referenced `dynvariables` (see examples below).
* profile cannot include profiles defined above in the import tree * Profiles cannot include profiles defined above in the import tree
* config files do not have access to variables 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 * Actions/transformations using variables are resolved at runtime
(when action/transformation is executed) and not when loading the config (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 ```yaml
variables: variables:
var0: "{{@@ dvar0 @@}}" var0: "{{@@ dvar0 @@}}"
@@ -149,7 +149,7 @@ dynvariables:
dvar0: "echo test" dvar0: "echo test"
``` ```
This will result with `dvar0 = "test"` and `var0 = "test"` This will result in `dvar0 = "test"` and `var0 = "test"`:
```yaml ```yaml
variables: variables:
var0: "test" var0: "test"
@@ -158,31 +158,31 @@ dynvariables:
``` ```
# testing # Testing
Dotdrop is tested with the use of the [tests.sh](/tests.sh) script. Dotdrop is tested with the use of the [tests.sh](/tests.sh) script.
* test for PEP8 compliance with `pycodestyle` and `pyflakes` * Test for PEP8 compliance with `pycodestyle` and `pyflakes`
* run the unittest available in [tests directory](/tests) * Run the unittest available in [tests directory](/tests)
* run the bash script tests in [tests-ng directory](tests-ng) * 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) All unittests are available in [the tests directory](/tests)
and use [python unittest](https://docs.python.org/3/library/unittest.html). and use [Python's unittest](https://docs.python.org/3/library/unittest.html).
The file [helpers.py](/tests/helpers.py) provides different helper methods The file [helpers.py](/tests/helpers.py) provides different helper methods
for the tests. for the tests.
## testing with bash scripts ## Testing with bash scripts
The bash scripts are available in [tests-ng directory](tests-ng). 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 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). 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`). 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/). 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* *Save your dotfiles once, deploy them everywhere*
[Dotdrop](https://github.com/deadc0de6/dotdrop) makes the management of dotfiles between different hosts easy. [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. different versions of the same file on different setups.
It also allows to manage different *sets* of dotfiles. It also allows you to manage different *sets* of dotfiles.
For example you can have a set of dotfiles for your home laptop and 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 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*. versions of the same dotfiles can be deployed using different predefined *profiles*.
Or you may have a main set of dotfiles for your 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 everyday host and a subset you only need to deploy to temporary
hosts (cloud VM, etc) that may be using hosts (cloud VM etc.) that may be using
a slightly different version of some of the dotfiles. a slightly different version of some of the dotfiles.
Features: Features:
* Sync once every dotfile on git for different usages * Sync once every dotfile in Git for different usages
* Allow dotfiles templating by leveraging [jinja2](https://palletsprojects.com/p/jinja/) * Allow dotfile templating by leveraging [Jinja2](https://palletsprojects.com/p/jinja/)
* Dynamically generated dotfile contents with pre-defined variables * Dynamically generated dotfile contents with pre-defined variables
* Comparison between deployed and stored dotfiles * Comparison between deployed and stored dotfiles
* Handling multiple profiles with different sets of dotfiles * Handling multiple profiles with different sets of dotfiles
* Easy import and update dotfiles * Easily import and update dotfiles
* Handle files and directories * Handle files and directories
* Support symlink of dotfiles * Support symlinking of dotfiles
* Associate actions to the deployment of specific dotfiles * Associate actions to the deployment of specific dotfiles
* Associate transformations for storing encrypted/compressed dotfiles * Associate transformations for storing encrypted/compressed dotfiles
* Provide solutions for handling dotfiles containing sensitive information * 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 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/) how [people are using dotdrop](https://dotdrop.readthedocs.io/en/latest/misc/people-using-dotdrop/)
for more. for more.
@@ -56,16 +56,16 @@ pip3 install -r dotdrop/requirements.txt --user
./dotdrop.sh --help ./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 There exist many tools to manage dotfiles; however, not
many allow to deploy different versions of the same dotfile many allow you to deploy different versions of the same dotfile
on different hosts. Moreover dotdrop allows to specify the on different hosts. Moreover, dotdrop allows you to specify the
set of dotfiles that need to be deployed on a specific profile. 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. 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. There are multiple ways to install and use dotdrop.
It is recommended to install dotdrop [as a submodule](#as-a-submodule) 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 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. 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 The below instructions show how to install dotdrop as a submodule. For alternative
installation instructions see the installation instructions, see the
[installation documentation](https://dotdrop.readthedocs.io/en/latest/installation/). [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/ * pypi: https://pypi.org/project/dotdrop/
* aur (stable): https://aur.archlinux.org/packages/dotdrop/ * aur (stable): https://aur.archlinux.org/packages/dotdrop/
* aur (git version): https://aur.archlinux.org/packages/dotdrop-git/ * aur (git version): https://aur.archlinux.org/packages/dotdrop-git/
@@ -112,22 +112,22 @@ $ ./dotdrop/bootstrap.sh
$ ./dotdrop.sh --help $ ./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*). (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 using the generated script `dotdrop.sh` at the root
of your dotfiles repository. Note that this script updates the submodule 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`. set to `no`.
To ease the use of dotdrop, it is recommended to add an alias to it in your 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>' 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 # 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. 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 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 ```bash
$ dotdrop import ~/.vimrc ~/.xinitrc ~/.config/polybar $ dotdrop import ~/.vimrc ~/.xinitrc ~/.config/polybar
``` ```
Dotdrop does two things: 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*) (defined in `config.yaml`, defaults to *dotfiles*)
* Create the associated entries in the `config.yaml` file * Create the associated entries in the `config.yaml` file
(in the `dotfiles` and `profiles` entries) (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 ```yaml
config: config:
backup: true 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. Commit and push your changes with git.
Then go to another host where your dotfiles need to be managed as well, 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: and compare the local dotfiles with the ones stored in dotdrop:
```bash ```bash
$ dotdrop compare --profile=home $ dotdrop compare --profile=home
``` ```
Now you might want to adapt the `config.yaml` file to your likings on 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 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 `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 ```yaml
… …
profiles: profiles:
@@ -211,9 +211,9 @@ profiles:
``` ```
Then adapt any dotfile using the [templating](https://dotdrop.readthedocs.io/en/latest/templating/) 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 ```bash
… …
{%@@ if profile == "home" @@%} {%@@ 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 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) 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`): the variable `wifi` while *office* gets `wlp2s0`):
```yaml ```yaml
… …
@@ -251,19 +251,19 @@ profiles:
wifi: "wlp2s0" wifi: "wlp2s0"
``` ```
Then you can adapt the polybar config file so that the Then you can adapt the Polybar config file so that the
variable `wifi` gets correctly replaced during installation variable `wifi` gets correctly replaced during installation:
```bash ```bash
[module/wireless-network] [module/wireless-network]
type = internal/network type = internal/network
interface = {{@@ wifi @@}} 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). and the office computer [bspwm](https://github.com/baskerville/bspwm).
The `~/.xinitrc` file will therefore be different while still sharing some lines. The `~/.xinitrc` file will therefore be different while still sharing some lines.
edit `<dotpath>/xinitrc` Edit `<dotpath>/xinitrc`:
```bash ```bash
#!/bin/bash #!/bin/bash
@@ -282,7 +282,7 @@ exec bspwm
``` ```
Finally you want everything installed with the *office* profile 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 ```yaml
… …
actions: actions:
@@ -304,7 +304,7 @@ profiles:
- loginstall "/tmp/dotdrop-installation.log" - loginstall "/tmp/dotdrop-installation.log"
``` ```
When done, you can install your dotfiles using When done, you can install your dotfiles using:
```bash ```bash
$ dotdrop install $ 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. 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) * [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 transformations](https://dotdrop.readthedocs.io/en/latest/config-details/#entry-transformations)
* [use variables](https://dotdrop.readthedocs.io/en/latest/config/#variables) * [Use variables](https://dotdrop.readthedocs.io/en/latest/config/#variables)
* [symlink dotfiles](https://dotdrop.readthedocs.io/en/latest/config/#symlink-dotfiles) * [Symlink dotfiles](https://dotdrop.readthedocs.io/en/latest/config/#symlink-dotfiles)
* [and more](https://dotdrop.readthedocs.io/en/latest/howto/howto/) * [and more](https://dotdrop.readthedocs.io/en/latest/howto/howto/)
# Documentation # 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 # 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). If you want to contribute, feel free to do a PR (please follow PEP8).
Have a look at the 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 # License

12
completion/README.md
View File

@@ -1,6 +1,6 @@
Here are completion files for `bash`, `zsh` and `fish` Here are completion files for `bash`, `zsh` and `fish`
for the use of dotdrop through the bash script `dotdrop.sh` 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 `bash` and `zsh` scripts are generated using
[infi.docopt_completion](https://github.com/Infinidat/infi.docopt_completion). [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 Source the file
* if using `dotdrop.sh` [dotdrop.sh-completion.bash](dotdrop.sh-completion.bash) * if using `dotdrop.sh`: [dotdrop.sh-completion.bash](dotdrop.sh-completion.bash)
* if using `dotdrop`: [dotdrop-completion.bash](dotdrop-completion.bash) * If using `dotdrop`: [dotdrop-completion.bash](dotdrop-completion.bash)
# zsh # 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.sh`: [_dotdrop.sh-completion.zsh](_dotdrop.sh-completion.zsh)
* if using `dotdrop`: [_dotdrop-completion.zsh](_dotdrop-completion.zsh) * If using `dotdrop`: [_dotdrop-completion.zsh](_dotdrop-completion.zsh)
# fish # fish

22
docs/README.md
View File

@@ -1,21 +1,21 @@
# Dotdrop # Dotdrop
[Dotdrop](https://deadc0de.re/dotdrop/) is a dotfiles manager that provides efficient ways of managing your dotfiles. [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 those across different hosts. 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. 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. 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). 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/) * [A quick overview of dotdrop features](https://deadc0de.re/dotdrop/)
* [the blogpost on dotdrop](https://deadc0de.re/articles/dotfiles.html) * [The blogpost on dotdrop](https://deadc0de.re/articles/dotfiles.html)
* [an example](https://github.com/deadc0de6/dotdrop#getting-started) * [An example](https://github.com/deadc0de6/dotdrop#getting-started)
* [how people are using dotdrop](misc/people-using-dotdrop.md) * [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).

118
docs/config-details.md
View File

@@ -1,13 +1,13 @@
# Config details # 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 * `post` action will be executed after the dotfile deployment.
* `pre` action will be executed before 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`). after the dotfile deployment (which is equivalent to `post`).
Actions cannot obviously be named `pre` or `post`. Actions cannot obviously be named `pre` or `post`.
@@ -20,10 +20,10 @@ Four types of actions can be defined:
**Notes**: **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 * Make sure to quote your actions to avoid bad surprises
* Actions are executed using the default shell (`$SHELL`) * 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 ### Dotfile actions
@@ -31,13 +31,13 @@ It is sometimes useful to execute some kind of action
when deploying a dotfile. when deploying a dotfile.
Note that a dotfile's actions are only 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 the version present in dotdrop differs from the one
in the filesystem). in the filesystem).
For example let's consider For example, let's consider
[Vundle](https://github.com/VundleVim/Vundle.vim) is used [Vundle](https://github.com/VundleVim/Vundle.vim), used
to manage vim's plugins, the following action could to manage Vim's plugins. The following action could
be set to update and install the plugins when `vimrc` is be set to update and install the plugins when `vimrc` is
deployed: deployed:
@@ -60,7 +60,7 @@ profiles:
- f_vimrc - f_vimrc
``` ```
Thus when `f_vimrc` is installed, the command Thus, when `f_vimrc` is installed, the command
`vim +VundleClean! +VundleInstall +VundleInstall! +qall` will `vim +VundleClean! +VundleInstall +VundleInstall! +qall` will
be executed. be executed.
@@ -135,7 +135,7 @@ when xinitrc is installed.
### Default actions ### 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. For example, the below action will log each dotfile installation to a file.
@@ -161,8 +161,8 @@ profiles:
### Profile actions ### Profile actions
A profile action can be either `pre` or `post` action (see [actions](config-details.md#entry-actions)). A profile action can be either a `pre` or `post` action (see [actions](config-details.md#actions-entry)).
Those are executed before any dotfile installation (for `pre`) and after all dotfiles installation (for `post`) 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. only if at least one dotfile has been installed.
### Fake dotfile and actions ### Fake dotfile and actions
@@ -182,43 +182,43 @@ dotfiles:
- always_action - 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 compressed directories](howto/store-compressed-directories.md)
* [Handle secrets](howto/sensitive-dotfiles.md) * [Handle secrets](howto/sensitive-dotfiles.md)
**Notes**: **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 * Make sure to quote your transformations to avoid bad surprises
* Transformations are executed using the default shell (`$SHELL`) * 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}}`) * To use shell variables in your transformations you need to escape the curly brackets (`${HOME}` becomes `${{HOME}}`)
There are two types of transformations available: 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` * Used for commands `install` and `compare`
* They have two arguments: * They have two arguments:
* **{0}** will be replaced with the dotfile to process * **{0}** will be replaced with the dotfile to process
* **{1}** will be replaced with a temporary file to store the result of the transformation * **{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` * Used for command `update`
* They have two arguments: * They have two arguments:
* **{0}** will be replaced with the file path to update the dotfile with * **{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 * **{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 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 ```yaml
trans_read: trans_read:
targ: echo "$(basename {0}); {{@@ _dotfile_key @@}}; {2}; {3}" > {1} targ: echo "$(basename {0}); {{@@ _dotfile_key @@}}; {2}; {3}" > {1}
@@ -233,14 +233,14 @@ profiles:
- f_abc - 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. Variables defined in the `variables` entry are made available within the config file.
Config variables are recursively evaluated what means that Config variables are recursively evaluated, which means that
a config like the below a config like the below:
```yaml ```yaml
variables: variables:
var1: "var1" var1: "var1"
@@ -265,9 +265,9 @@ will result in the following available variables:
* dvar3: `dvar1 dvar2 dvar3` * dvar3: `dvar1 dvar2 dvar3`
* dvar4: `var1 var2 var3` * 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. content will be interpreted by the shell before being substituted.
These need to be defined in the config file under the entry `dynvariables`. 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). 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. `uservariables` entry. Each variable will be prompted to the user.
For example For example:
```yaml ```yaml
uservariables: uservariables:
emailvar: "email" emailvar: "email"
@@ -304,11 +304,11 @@ Please provide the value for "email":
``` ```
And store the entered text as the value for the variable `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 `uservariables` are eventually saved to `uservariables.yaml` (relatively to the
config file). 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`. then store them in a file. You might also want to add `uservariables.yaml` to your `.gitignore`.
```yaml ```yaml
uservariables: uservariables:
@@ -318,9 +318,9 @@ config:
- uservariables.yaml:optional - 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. Profile variables will take precedence over globally defined variables.
This means that you could do something like this: This means that you could do something like this:
@@ -342,7 +342,7 @@ profiles:
- f_gitconfig - f_gitconfig
``` ```
## Entry profile include ## Profile include entry
If one profile is using the entire set of another profile, one can use If one profile is using the entire set of another profile, one can use
the `include` entry to avoid redundancy. the `include` entry to avoid redundancy.
@@ -364,9 +364,9 @@ profiles:
``` ```
Here profile *host1* contains all the dotfiles defined for *host2* plus `f_xinitrc`. 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)) ([variables](config.md#variables) and [dynvariables](#dynvariables-entry))
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: For example:
```yaml ```yaml
@@ -389,12 +389,12 @@ profiles:
- "profile_{{@@ var1 @@}}" - "profile_{{@@ var1 @@}}"
``` ```
Note that profile cannot include other profiles defined above in Note that profiles cannot include other profiles defined above in
the import tree (profile exists in another file and is imported using `import_configs` for example). 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. 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. The paths can be absolute or relative to the config file location.
@@ -426,13 +426,13 @@ dotfiles:
- f_xyz - 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 ```yaml
import: import:
- profiles.d/{{@@ profile @@}}.yaml - profiles.d/{{@@ profile @@}}.yaml
``` ```
## Entry import_variables ## import_variables entry
It is possible to load variables/dynvariables from external files by providing their It is possible to load variables/dynvariables from external files by providing their
paths in the config entry `import_variables`. 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. 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 ```yaml
import_variables: import_variables:
- variables.d/myvars.yaml:optional - variables.d/myvars.yaml:optional
``` ```
## Entry import_actions ## import_actions entry
It is possible to load actions from external files by providing their It is possible to load actions from external files by providing their
paths in the config entry `import_actions`. 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. inside the main config file.
Dotdrop will fail if an imported path points to a non-existing 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 ```yaml
import_actions: import_actions:
- actions.d/myactions.yaml:optional - actions.d/myactions.yaml:optional
``` ```
## Entry import_configs ## import_configs entry
Entire config files can be imported using the `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: This means making the following available from the imported config file in the original config file:
@@ -569,13 +569,13 @@ actions:
show: less 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 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 profile `other-host` included from `my-haskell`. The action `show` is defined
in `actions.yaml`, which is in turn imported by `other-config.yaml`. 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. 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 ```yaml
import_configs: import_configs:
- other-config.yaml:optional - other-config.yaml:optional
@@ -583,10 +583,10 @@ import_configs:
## Dynamic dotfile paths ## 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)). 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: profile path is dynamically found using a shell oneliner stored in a dynvariable:
```yaml ```yaml
dynvariables: dynvariables:
@@ -603,10 +603,10 @@ profiles:
## Dynamic dotfile link value ## Dynamic dotfile link value
Dotfile `link` value can be dynamically constructed using Dotfile `link` values can be dynamically constructed using
define variables ([variables and dynvariables](config.md#variables)). defined variables ([variables and dynvariables](config.md#variables)).
For example For example:
```yaml ```yaml
variables: variables:
link_value: "nolink" link_value: "nolink"

127
docs/config-format.md
View File

@@ -1,65 +1,65 @@
# Config format # 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: Here is a minimal config file to start with:
[config.yaml](https://github.com/deadc0de6/dotdrop/blob/master/config.yaml). [config.yaml](https://github.com/deadc0de6/dotdrop/blob/master/config.yaml).
## config entry ## config entry
The **config** entry (mandatory) contains settings for the deployment The **config** entry (mandatory) contains settings for the deployment.
Entry | Description | Default Entry | Description | Default
-------- | ------------- | ------------ -------- | ------------- | ------------
`backup` | create a backup of the dotfile in case it differs from the one that will be installed by dotdrop | true `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 `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)) | - `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 directory hierarchy when installing dotfiles if it doesn't exist | true `create` | Create a 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)) | - `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}` `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` `dotpath` | Path to the directory containing the dotfiles to be managed by dotdrop (absolute path or relative to the config file location) | `dotfiles`
`filter_file` | list of paths to load templating filters from (see [Templating available filters](templating.md#template-filters)) | - `filter_file` | List of paths to load templating filters from (See [Templating available filters](templating.md#template-filters)) | -
`force_chmod` | if true, do not ask confirmation to apply permissions on install | false `force_chmod` | If true, do not ask confirmation to apply permissions on install | false
`func_file` | list of paths to load templating functions from (see [Templating available methods](templating.md#template-methods)) | - `func_file` | List of paths to load templating functions from (See [Templating available methods](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 `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 `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)) | - `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_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 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_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 path or relative to the config file location see [Import variables from file](config-details.md#entry-import_variables)) | - `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, apply to all dotfiles (enclose in quotes when using wildcards, see [ignore patterns](config.md#ignore-patterns)) | - `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 `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_dotfile_default` | Set a dotfile's `link` attribute to this value when undefined. Possible values: *nolink*, *link* (See [Symlinking dotfiles](config.md#symlinking-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` `link_on_import` | Set a dotfile's `link` attribute to this value when importing. Possible values: *nolink*, *link* [Symlinking dotfiles](config.md#symlinking-dotfiles)) | `nolink`
`longkey` | use long keys for dotfiles when importing (see [Import dotfiles](usage.md#import-dotfiles)) | false `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 | - `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 `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 `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)) | - `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` `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 <s>link_by_default</s> | When importing a dotfile, set `link` to this value by default | false
## dotfiles entry ## 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 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) `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` (dotfile with empty `src` 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` | 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`) `link` | Defines how this dotfile is installed. Possible values: *nolink*, *link*, *link_children* (See [Symlinking dotfiles](config.md#symlinking-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)) `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)) `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)) `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)) `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`) `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)) `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`) `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#entry-transformations)) `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#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#transformations-entry))
`upignore` | list of patterns to ignore when updating (enclose in quotes when using wildcards, see [ignore patterns](config.md#ignore-patterns)) `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>link_children</s> | Replaced by `link: link_children`
<s>trans</s> | replaced by `trans_read` <s>trans</s> | Replaced by `trans_read`
```yaml ```yaml
<dotfile-key-name>: <dotfile-key-name>:
@@ -84,17 +84,16 @@ Entry | Description
## profiles entry ## profiles entry
The **profiles** entry (mandatory) contains a list of profiles with the different dotfiles that 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:
need to be managed
Entry | Description Entry | Description
-------- | ------------- -------- | -------------
`dotfiles` | the dotfiles associated to this profile `dotfiles` | The dotfiles associated with 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)). `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#entry-profile-include)) `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)) `variables` | Profile-specific variables (See [Variables](config.md#variables))
`dynvariables` | profile specific interpreted variables (see [Interpreted variables](config-details.md#entry-dynvariables)) `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#entry-actions)) `actions` | List of action keys that need to be defined in the **actions** entry below (See [actions](config-details.md#actions-entry))
```yaml ```yaml
<some-profile-name-usually-the-hostname>: <some-profile-name-usually-the-hostname>:
@@ -120,21 +119,21 @@ Entry | Description
## actions entry ## 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 ```yaml
actions: actions:
<action-key>: <command-to-execute> <action-key>: <command-to-execute>
``` ```
*pre* actions *pre* actions:
```yaml ```yaml
actions: actions:
pre: pre:
<action-key>: <command-to-execute> <action-key>: <command-to-execute>
``` ```
*post* actions *post* actions:
```yaml ```yaml
actions: actions:
post: post:
@@ -143,7 +142,7 @@ actions:
## trans_read entry ## 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 ```yaml
trans_read: trans_read:
@@ -152,7 +151,7 @@ trans_read:
## trans_write entry ## 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 ```yaml
trans_write: trans_write:
@@ -161,7 +160,7 @@ trans_write:
## variables entry ## 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 ```yaml
variables: variables:
@@ -170,8 +169,8 @@ variables:
## dynvariables entry ## dynvariables entry
The **dynvariables** entry (optional) contains a list of interpreted variables The **dynvariables** entry (optional) contains an interpreted variables mapping
(see [Interpreted variables](config-details.md#entry-dynvariables)) (See [Interpreted variables](config-details.md#dynvariables-entry)).
```yaml ```yaml
dynvariables: dynvariables:
@@ -180,9 +179,9 @@ dynvariables:
## uservariables entry ## uservariables entry
The **uservariables** entry (optional) contains a list of variables The **uservariables** entry (optional) contains a collection of variables
to be queried to the user for their values. whose values are queried from the user
(see [User variables](config-details.md#entry-uservariables)) (See [User variables](config-details.md#uservariables-entry)).
```yaml ```yaml
uservariables: uservariables:

158
docs/config.md
View File

@@ -5,73 +5,73 @@
The config file used by dotdrop is The config file used by dotdrop is
[config.yaml](https://github.com/deadc0de6/dotdrop/blob/master/config.yaml). [config.yaml](https://github.com/deadc0de6/dotdrop/blob/master/config.yaml).
Unless specified dotdrop will look in following places for its config file Unless specified otherwise, dotdrop will look in the following places for its config file
and use the first one found 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/` * `${XDG_CONFIG_HOME}/dotdrop/`
* `~/.config/dotdrop/` * `~/.config/dotdrop/`
* `/etc/xdg/dotdrop/` * `/etc/xdg/dotdrop/`
* `/etc/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. or by defining the `DOTDROP_CONFIG` environment variable.
## Variables ## Variables
Multiple variables can be used within the config file to 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)) * Dotfile `src` and `dst` paths (See [Dynamic dotfile paths](config-details.md#dynamic-dotfile-paths))
* external path specifications * External path specifications
* `import_variables` * `import_variables`
* `import_actions` * `import_actions`
* `import_configs` * `import_configs`
* profiles's `import` * Profiles' `import`
* profiles's `include` * 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 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)). [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) * [Variables defined in the config](config-details.md#variables-entry)
* [interpreted variables defined in the config](config-details.md#entry-dynvariables) * [Interpreted variables defined in the config](config-details.md#dynvariables-entry)
* [user variables defined in the config](config-details.md#entry-uservariables) * [User variables defined in the config](config-details.md#uservariables-entry)
* [profile variables defined in the config](config-details.md#entry-profile-variables) * [Profile variables defined in the config](config-details.md#profile-variables-entry)
* environment variables: `{{@@ env['MY_VAR'] @@}}` * Environment variables: `{{@@ env['MY_VAR'] @@}}`
* dotdrop header: `{{@@ header() @@}}` (see [Dotdrop header](templating.md#dotdrop-header)) * 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 Note that all variables available in the config file will
then be available during [templating](templating.md). then be available during [templating](templating.md).
Here are some rules on the use of variables in configs: 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#dynvariables-entry) are executed in their own file.
* [interpreted variables](config-details.md#entry-dynvariables) and * [Interpreted variables](config-details.md#dynvariables-entry) and
[variables](config-details.md#entry-variables) are templated before [variables](config-details.md#variables-entry) are templated before
[interpreted variables](config-details.md#entry-dynvariables) are executed [interpreted variables](config-details.md#dynvariables-entry) are executed.
* config files do not have access to variables defined above in the import tree * Config files do not have access to variables defined above in the import tree.
* `dynvariables` take precedence over `variables` * `dynvariables` take precedence over `variables`.
* profile `(dyn)variables` take precedence over any other `(dyn)variables` * Profile `(dyn)variables` take precedence over any other `(dyn)variables`.
* profile `(dyn)variables` take precedence over profile's included `(dyn)variables` * Profile `(dyn)variables` take precedence over profile's included `(dyn)variables`.
* external/imported `(dyn)variables` take precedence over * External/imported `(dyn)variables` take precedence over
`(dyn)variables` defined inside the main config file `(dyn)variables` defined inside the main config file.
* [user variables](config-details.md#entry-uservariables) are ignored if * [User variables](config-details.md#uservariables-entry) are ignored if
any other variable with the same key is defined any other variable with the same key is defined.
## Permissions ## 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). config dotfile entry [chmod](config-format.md#dotfiles-entry).
A [chmod](config-format.md#dotfiles-entry) entry on a directory A [chmod](config-format.md#dotfiles-entry) entry on a directory
is applied to the directory only, not recursively. is applied to the directory only, not recursively.
For example For example:
```yaml ```yaml
dotfiles: dotfiles:
f_file: f_file:
@@ -84,59 +84,59 @@ dotfiles:
chmod: 744 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 stored in a `chmod` entry
* if imported file permissions differ from umask then its permissions are automatically * If the imported file's permissions differ from the umask, then the permissions are automatically
stored in the `chmod` entry stored in the `chmod` entry.
* otherwise no `chmod` entry is added * 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 * 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. * 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 * If the global setting `force_chmod` is set to true, dotdrop will not ask
for confirmation to apply permission for confirmation to apply permissions.
On `update`: On `update`:
* if the permissions of the file in the filesystem differ from the dotfile in the `dotpath` * 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 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: which are controlled by the `link` config attribute of each dotfile:
* `link: nolink`: the dotfile (file or directory) is copied to its 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`: 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: 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 ## 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 Entry | Related doc
-------- | ------------- -------- | -------------
dotfile src | [dynamic dotfile paths](config-details.md#dynamic-dotfile-paths) dotfile src | [Dynamic dotfile paths](config-details.md#dynamic-dotfile-paths)
dotfile dst | [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) dotfile link | [Dynamic dotfile link value](config-details.md#dynamic-dotfile-link-value)
variables | [variables](config-details.md#entry-variables) variables | [variables](config-details.md#variables-entry)
dynvariables | [dynvariables](config-details.md#entry-dynvariables) dynvariables | [dynvariables](config-details.md#dynvariables-entry)
actions | [dynamic actions](config-details.md#dynamic-actions) actions | [dynamic actions](config-details.md#dynamic-actions)
profile include | [profile include](config-details.md#entry-profile-include) profile include | [Profile include](config-details.md#profile-include-entry)
profile import | [profile import](config-details.md#entry-profile-import) profile import | [Profile import](config-details.md#profile-import-entry)
import_variables | [import_variables](config-details.md#entry-import_variables) import_variables | [import_variables](config-details.md#import_variables-entry)
import_actions | [import_actions](config-details.md#entry-import_actions) import_actions | [import_actions](config-details.md#import_actions-entry)
import_configs | [import_configs](config-details.md#entry-import_configs) import_configs | [import_configs](config-details.md#import_configs-entry)
## All dotfiles for a profile ## 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`. the keyword `ALL`.
For example: For example:
@@ -161,27 +161,27 @@ profiles:
It is possible to ignore specific patterns when using dotdrop. It is possible to ignore specific patterns when using dotdrop.
* for [install](usage.md#install-dotfiles) * For [install](usage.md#install-dotfiles):
* using `instignore` in the config file * Using `instignore` in the config file
* for [import](usage.md#import-dotfiles) * For [import](usage.md#import-dotfiles):
* using `impignore` in the config file * Using `impignore` in the config file
* for [compare](usage.md#compare-dotfiles) * For [compare](usage.md#compare-dotfiles):
* using `cmpignore` in the config file * Using `cmpignore` in the config file
* using the command line switch `-i --ignore` * Using the command line switch `-i`/`--ignore`
* for [update](usage.md#update-dotfiles) * For [update](usage.md#update-dotfiles):
* using `upignore` in the config file * Using `upignore` in the config file
* using the command line switch `-i --ignore` * Using the command line switch `-i`/`--ignore`
The ignore pattern must follow Unix shell-style wildcards like for example `*/path/to/file`. 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. 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 (`!`). 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, 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 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 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 ```yaml
config: config:
@@ -212,7 +212,7 @@ dotfiles:
- "*" - "*"
``` ```
To ignore specific directory when updating To ignore a specific directory when updating:
```yaml ```yaml
dotfiles: dotfiles:
d_colorpicker: d_colorpicker:
@@ -222,7 +222,7 @@ dotfiles:
- '*sub_directory_to_ignore' - '*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 ```yaml
config: config:
impignore: impignore:

6
docs/howto/append.md
View File

@@ -2,7 +2,7 @@
Sometimes it might be useful to be able to append some text to a Sometimes it might be useful to be able to append some text to a
file. Dotdrop is able to do that with the help of file. Dotdrop is able to do that with the help of
[actions](../config-details.md#entry-actions) and a temporary file. [actions](../config-details.md#actions-entry) and a temporary file.
Below is a config example to append to a file: Below is a config example to append to a file:
```yaml ```yaml
@@ -23,9 +23,9 @@ actions:
post: post:
append: "cat {0} >> {1}; rm -f {0}" 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 # my pattern
this is the end this is the end

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

@@ -1,9 +1,9 @@
# Create files on install # 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. [actions](../config-details.md#actions-entry) 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`. from under `~/.original` to `~/symlinks`.
```bash ```bash
$ tree ~/.original $ tree ~/.original
@@ -13,19 +13,19 @@ $ tree ~/.original
└── dir3 └── 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 dir1
dir2 dir2
dir3 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 `dynvariables` that will read the above text file
* a few `variables` for the source and destination * A few `variables` for the source and destination
* an action that will create the destination directory and symlink those directories * 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 *fake* dotfile (with no `src` and no `dst` values) that will be always installed with the above action
```yaml ```yaml
dynvariables: dynvariables:
@@ -45,7 +45,7 @@ actions:
- symlink_them '{{@@ links_list @@}}' '{{@@ links_dst @@}}' - symlink_them '{{@@ links_list @@}}' '{{@@ links_dst @@}}'
``` ```
The result would be The result would be:
```bash ```bash
$ tree ~/.symlinks $ tree ~/.symlinks
/home/user/.symlinks /home/user/.symlinks
@@ -54,4 +54,4 @@ $ tree ~/.symlinks
└── dir3 -> /home/user/.original/dir3 └── 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 ## Append text to a dotfile on install
@@ -20,13 +20,13 @@
[Handle special chars](special-chars.md) [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 ## 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 # 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" 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: For example:
```yaml ```yaml

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

@@ -1,14 +1,14 @@
# Merge files on install # 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/top`: top part of the file
* `<dotpath>/vimrc.d/bottom`: bottom 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 ```yaml
... ...
dotfiles: dotfiles:
@@ -48,12 +48,12 @@ Dotdrop will then automagically include the files into your vimrc when handling
## Merge all files in a directory ## Merge all files in a directory
To include all files in a directory, a combination of To include all files in a directory, a combination of
[dynvariables](../config-details.md#entry-dynvariables) [dynvariables](../config-details.md#dynvariables-entry)
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. Let's say all files in `<dotpath>/toinclude` need to be included into a dotfile.
First define a [dynvariables](../config-details.md#entry-dynvariables) First define a [dynvariables](../config-details.md#dynvariables-entry)
in the config file which will look for files to include in the above directory: in the config file which will look for files to include in the above directory:
```yaml ```yaml
dynvariables: dynvariables:
@@ -61,9 +61,9 @@ dynvariables:
``` ```
Note that `_dotdrop_dotpath` is part of the built-in variables 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() @@%} {%@@ for f in allfiles.split() @@%}
{%@@ include f @@%} {%@@ include f @@%}

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

@@ -1,14 +1,14 @@
# Prompt user for variables # Prompt user for variables
With the use of [uservariables](../config-details.md#entry-uservariables), With the use of [uservariables](../config-details.md#uservariables-entry),
one can define specific variables that need to be initially filled in manually one can define specific variables that need to be initially filled in manually
by the user on first run. by the user on first run.
The provided values are then automatically saved by dotdrop to `uservariables.yaml`, The provided values are then automatically saved by dotdrop to `uservariables.yaml`,
which can be included in the main config as a file from which variables are imported 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). using [import_variables](../config-details.md#import_variables-entry).
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. on new hosts you deploy your dotfiles to.
You'd add the following elements to your config: You'd add the following elements to your config:

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

@@ -19,35 +19,35 @@ trans_read:
_gpg: gpg2 -q --for-your-eyes-only --no-tty -d {0} > {1} _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. 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 ```bash
$ dotdrop import ~/.secret $ dotdrop import ~/.secret
``` ```
* encrypt the original dotfile * Encrypt the original dotfile:
```bash ```bash
$ <some-gpg-command> ~/.secret $ <some-gpg-command> ~/.secret
``` ```
* overwrite the dotfile with the encrypted version * Overwrite the dotfile with the encrypted version:
```bash ```bash
$ cp <encrypted-version-of-secret> dotfiles/secret $ 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) (as shown in the example above)
* commit and push the changes * Commit and push the changes
See [transformations](../config-details.md#entry-transformations). See [transformations](../config-details.md#transformations-entry).
## Load passphrase from file ## Load passphrase from file
@@ -59,7 +59,7 @@ trans_read:
_gpg: "gpg2 --batch --yes --passphrase-file <({{@@ gpg_password @@}}) -q --for-your-eyes-only --no-tty -d {0} > {1}" _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 ```yaml
variables: variables:
gpg_password_file: "/tmp/the-password" gpg_password_file: "/tmp/the-password"
@@ -67,4 +67,4 @@ trans_read:
_gpg: "gpg2 --batch --yes --passphrase-file <(cat {{@@ gpg_password_file @@}}) -q --for-your-eyes-only --no-tty -d {0} > {1}" _gpg: "gpg2 --batch --yes --passphrase-file <(cat {{@@ gpg_password_file @@}}) -q --for-your-eyes-only --no-tty -d {0} > {1}"
``` ```
See [transformations](../config-details.md#entry-transformations). See [transformations](../config-details.md#transformations-entry).

43
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, 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 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 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 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 templating and merging them into the same dotfile in dotdrop's `dotpath`. Here
are a few suggestions about how to achieve this. are a few suggestions about how to achieve this:
* [Brute force templating](#brute-force-templating) * [Brute force templating](#brute-force-templating)
* [Profile variables](#profile-variables) * [Profile variables](#profile-variables)
@@ -13,7 +13,7 @@ are a few suggestions about how to achieve this.
## Brute force templating ## 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: In order to do this, we need to:
1. Create the merged dotfile with an arbitrary name somewhere in `dotpath`. 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 @@}}' export DB_PORT='{{@@ aws_db_port @@}}'
``` ```
Part of Dotdrop `config.yaml` file: Part of dotdrop `config.yaml` file:
```yaml ```yaml
# config.yaml # config.yaml
@@ -63,10 +63,10 @@ export DB_PORT='4521'
## Profile variables ## 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 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: [profile variables](../config-details.md#profile-variables-entry). This is achieved by:
1. Creating the merged dotfile with an arbitrary name somewhere in `dotpath`. 1. Creating the merged dotfile with an arbitrary name somewhere in `dotpath`.
2. Adding some variables in the merged dotfile via templating. 2. Adding some variables in the merged dotfile via templating.
@@ -79,7 +79,7 @@ solution consists in using
An example: An example:
The merged dotfile (`dotpath/projects/env`) The merged dotfile (`dotpath/projects/env`):
```bash ```bash
# .env # .env
@@ -87,7 +87,7 @@ export DB_HOST='{{@@ aws_db_host @@}}'
export DB_PORT='{{@@ aws_db_port @@}}' export DB_PORT='{{@@ aws_db_port @@}}'
``` ```
Part of Dotdrop `config.yaml` file: Part of dotdrop `config.yaml` file:
```yaml ```yaml
# config.yaml # config.yaml
@@ -128,26 +128,26 @@ export DB_PORT='9632'
Even though it has cleaner dotfiles, the profile-variable-based procedure can't 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 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 force templating approach can be used, but in the latter one it also makes the
dotfiles bloated with "bookkeeping" logic, thus hard to read. dotfiles bloated with "bookkeeping" logic, thus hard to read.
A solution for this relies in leveraging Jinja macros. This method is a 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 variation of the brute force templating one where the merged dotfile is
included from many different dotfiles in `dotpath` via jinja macros, rather included from many different dotfiles in `dotpath` via Jinja macros rather
than via many `dotfile` entries with the same `src` attribute. This way, the 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. because computations are in other files.
The steps to achieve this are: The steps to achieve this are:
1. Creating the merged dotfile with an arbitrary name somewhere in `dotpath`. 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. 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. **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 If it needs to not be deployed, the `ignoreempty` entry can be set to
`true` in `config.yaml`. `true` in `config.yaml`.
As usual, an example: As usual, an example:
@@ -162,7 +162,7 @@ export DB_PORT='{{@@ db_port @@}}'
{%@@ endmacro @@%} {%@@ endmacro @@%}
``` ```
Server0's environment file (`projects/server0/.env`) Server0's environment file (`projects/server0/.env`):
```jinja2 ```jinja2
{%@@ from projects/env import env @@%} {%@@ from projects/env import env @@%}
@@ -182,14 +182,14 @@ Server0's environment file (`projects/server0/.env`)
{{@@ env(db_host, db_port) @@}} {{@@ env(db_host, db_port) @@}}
``` ```
Server1's environment file (`projects/server1/.env`) Server1's environment file (`projects/server1/.env`):
```jinja2 ```jinja2
{%@@ from projects/env import env @@%} {%@@ from projects/env import env @@%}
{{@@ env('average-host.com', 9632) @@}} {{@@ env('average-host.com', 9632) @@}}
``` ```
Part of Dotdrop `config.yaml` file: Part of dotdrop `config.yaml` file:
```yaml ```yaml
# config.yaml # config.yaml
@@ -203,7 +203,6 @@ dotfiles:
server1-env: server1-env:
src: projects/server1/.env src: projects/server1/.env
dst: ~/projects/server1/.env dst: ~/projects/server1/.env
``` ```
With this configuration, installing the dotfile `server0-env-local-dbg` will 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 ## Detect encoding
Text file encoding can be identified using for example `file -b <file-path>` or in vim Text file encoding can be identified using, for example, `file -b <file-path>` or in vim
with `:set fileencoding` with `:set fileencoding`.
Here's an example of encoding that will fully work with dotdrop: Here's an example of encoding that will fully work with dotdrop:
```bash ```bash
@@ -27,19 +27,20 @@ ISO-8859 text, with escape sequences
### CRLF ### CRLF
The use of dotfiles with DOS/Windows line ending (CRLF, `\r\n`) will result in The use of dotfiles with DOS/Windows line endings (CRLF, `\r\n`) will result in
the comparison (`compare`) returning a difference while there is none. the comparison (`compare`) returning a difference where there is none.
This is due to Jinja2 stripping CRLF. 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>. 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>. See <https://github.com/deadc0de6/dotdrop/issues/42>.

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

@@ -1,6 +1,6 @@
# Handle compressed directories # 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. compressed directories and deploy them with dotdrop.
Config file: Config file:
@@ -25,12 +25,12 @@ profiles:
- d_somedir - 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} 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} . tar -cf {1} -C {0} .
``` ```

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

@@ -1,34 +1,34 @@
# Symlink dotfiles # Symlink dotfiles
Dotdrop offers two ways to symlink a dotfile through its 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` 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_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 where `src` is the file stored in your *dotpath* and
`dst` as the file located in your `$HOME`. `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* `~/.config/dotdrop` instead of directly into your *dotpath*
(see [Templating symlinked dotfiles](#templating-symlinked-dotfiles)) (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`, 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. will fail.
## Symlink a dotfile ## 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. 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 ```bash
$ ./dotdrop.sh import ~/.bashrc $ ./dotdrop.sh import ~/.bashrc
-> "/home/user/.bashrc" imported -> "/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 ```yaml
dotfiles: dotfiles:
f_bashrc: f_bashrc:
@@ -37,7 +37,7 @@ dotfiles:
link: link 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 ```bash
$ ./dotdrop.sh install $ ./dotdrop.sh install
Remove "/home/user/.bashrc" for link creation? [y/N] ? y 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. 1 dotfile(s) installed.
``` ```
The dotfile then points to the file in dotdrop The dotfile then points to the file in dotdrop:
```bash ```bash
$ readlink ~/.bashrc $ readlink ~/.bashrc
/home/user/dotdrop/dotfiles/bashrc /home/user/dotdrop/dotfiles/bashrc
@@ -55,16 +55,16 @@ $ readlink ~/.bashrc
## Link children ## Link children
The `link_children` option can be very useful for dotfiles when you don't want the entire 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). 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. 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 ```yaml
config: config:
dotpath: dotfiles dotpath: dotfiles
@@ -75,7 +75,7 @@ dotfiles:
link: link 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 ```bash
$ readlink ~/.vim $ readlink ~/.vim
~/.dotfiles/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 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` 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 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. files/directories, and then the `link` entry is set to `link_children` in the config file:
```yaml ```yaml
config: config:
dotpath: dotfiles dotpath: dotfiles
@@ -120,15 +120,15 @@ $ tree -L 1 ~/.vim
## Templating symlinked dotfiles ## 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)). to dotdrop's `dotpath` directory (see [Config](../config.md)).
When using templating directives however the dotfiles are first installed into When using templating directives, however, the dotfiles are first installed into
`workdir` (defaults to *~/.config/dotdrop*, see [Config](../config.md)) `workdir` (defaults to *~/.config/dotdrop*; see [Config format](../config-format.md))
and then symlinked there. and then symlinked there.
This applies to both dotfiles with `link: link` and `link: link_children`. This applies to both dotfiles with `link: link` and `link: link_children`.
For example For example:
```bash ```bash
# with template # with template
/home/user/.xyz -> /home/user/.config/dotdrop/.xyz /home/user/.xyz -> /home/user/.config/dotdrop/.xyz

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

@@ -1,18 +1,18 @@
# Manage system dotfiles # 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 handling these two uses cases:
For example: For example:
* one `config-user.yaml` for the local/user dotfiles (with its dedicated *dotpath*, for example `dotfiles-user`) * 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-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 ```bash
## user config file is config-user.yaml ## user config file is config-user.yaml
$ ./dotdrop.sh import --cfg config-user.yaml <some-dotfile> $ ./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 ```bash
## root config file is config-root.yaml ## root config file is config-root.yaml
$ sudo ./dotdrop.sh import --cfg=config-root.yaml <some-dotfile> $ 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. 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 (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. In that case, the virtualenv environment might need to be loaded before any attempt to use dotdrop.
## As a submodule ## 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: keep dotdrop as a submodule:
```bash ```bash
## create the repository ## create the repository
@@ -25,15 +25,15 @@ $ ./dotdrop/bootstrap.sh
$ ./dotdrop.sh --help $ ./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*). (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 using the generated script `dotdrop.sh` at the root
of your dotfiles repository. of your dotfiles repository.
To ease the use of dotdrop, it is recommended to add an alias to it in your 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>' alias dotdrop=<absolute-path-to-dotdrop.sh> --cfg=<path-to-your-config.yaml>'
``` ```
@@ -58,7 +58,7 @@ $ ./dotdrop/bootstrap.sh
$ ./dotdrop.sh --help $ ./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 ```bash
$ source env/bin/activate $ source env/bin/activate
$ ./dotdrop.sh --help $ ./dotdrop.sh --help
@@ -66,18 +66,18 @@ $ ./dotdrop.sh --help
Then follow the instructions under [As a submodule](#as-a-submodule). Then follow the instructions under [As a submodule](#as-a-submodule).
## Pypi package ## PyPI package
Install dotdrop Install dotdrop:
```bash ```bash
$ pip3 install dotdrop --user $ 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 ```bash
$ virtualenv -p python3 env $ virtualenv -p python3 env
$ source env/bin/activate $ source env/bin/activate
@@ -91,14 +91,14 @@ $ source env/bin/activate
$ dotdrop --help $ dotdrop --help
``` ```
Then follow the instructions under [Pypi package](#pypi-package). Then follow the instructions under [PyPI package](#pypi-package).
## Aur packages ## Aur packages
Dotdrop is available on aur: Dotdrop is available on aur:
* stable: <https://aur.archlinux.org/packages/dotdrop/> * Stable: <https://aur.archlinux.org/packages/dotdrop/>
* git version: <https://aur.archlinux.org/packages/dotdrop-git/> * 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. 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 ## 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 ```bash
snap install dotdrop snap install dotdrop
``` ```
Then follow the [doc to setup your repository](repository-setup.md). 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: try defining the following environment variable:
```bash ```bash
export MAGIC=$SNAP/usr/share/file/magic.mgc export MAGIC=$SNAP/usr/share/file/magic.mgc
@@ -123,7 +123,7 @@ export MAGIC=$SNAP/usr/share/file/magic.mgc
## From source ## From source
Clone the repository Clone the repository:
```bash ```bash
$ git clone https://github.com/deadc0de6/dotdrop.git $ git clone https://github.com/deadc0de6/dotdrop.git
``` ```
@@ -138,14 +138,14 @@ $ ./dotdrop.sh --cfg <my-config-file> files
## Dependencies ## Dependencies
Beside the python dependencies defined in [requirements.txt](https://github.com/deadc0de6/dotdrop/blob/master/requirements.txt), Beside the Python dependencies defined in [requirements.txt](https://github.com/deadc0de6/dotdrop/blob/master/requirements.txt),
dotdrop depends on following tools: dotdrop depends on the following tools:
* `diff` * `diff`
* `git` (only if using the entry point script [dotdrop.sh](https://github.com/deadc0de6/dotdrop/blob/master/dotdrop.sh)) * `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)) * `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) * [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) * [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`. script by defining the environment variable `DOTDROP_AUTOUPDATE=yes`.
If undefined, `DOTDROP_AUTOUPDATE` will take the value `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 ```bash
$ git submodule update --init --recursive $ git submodule update --init --recursive
$ git submodule update --remote dotdrop $ git submodule update --remote dotdrop
``` ```
You will then need to commit the changes with You will then need to commit the changes with:
```bash ```bash
$ git add dotdrop $ git add dotdrop
$ git commit -m 'update dotdrop' $ git commit -m 'update dotdrop'
@@ -180,7 +180,7 @@ $ git push
If you wish to get a specific version of dotdrop when using If you wish to get a specific version of dotdrop when using
it as a submodule, the following operations can be done. 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 ```bash
## enter the repository containing the dotdrop submodule ## enter the repository containing the dotdrop submodule
$ cd my-dotfiles $ cd my-dotfiles
@@ -197,11 +197,9 @@ automatically update dotdrop back to the latest commit.
## Shell completion ## 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). see [the related doc](https://github.com/deadc0de6/dotdrop/blob/master/completion/README.md).
## Highlighters ## Highlighters
Highlighters for dotdrop templates are available [here](https://github.com/deadc0de6/dotdrop/tree/master/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 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. 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 ```bash
$ cd <dotfiles-directory> $ cd <dotfiles-directory>
@@ -30,40 +30,40 @@ $ git commit -m 'update dotdrop.sh'
$ git push $ 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 ```bash
$ cd <dotfiles-repository> $ cd <dotfiles-repository>
``` ```
* remove the entire `submodule "dotdrop"` section in `.gitmodules` * Remove the entire `submodule "dotdrop"` section in `.gitmodules`
* stage the changes * Stage the changes
```bash ```bash
$ git add .gitmodules $ git add .gitmodules
``` ```
* remove the entire `submodule "dotdrop"` section in `.git/config` * Remove the entire `submodule "dotdrop"` section in `.git/config`
* remove the submodule * Remove the submodule
```bash ```bash
$ git rm --cached dotdrop $ git rm --cached dotdrop
``` ```
* remove the submodule from .git * Remove the submodule from .git
```bash ```bash
$ rm -rf .git/modules/dotdrop $ rm -rf .git/modules/dotdrop
``` ```
* commit the changes * Commit the changes
```bash ```bash
$ git commit -m 'removing dotdrop submodule' $ git commit -m 'removing dotdrop submodule'
``` ```
* remove any remaining files from the dotdrop submodule * Remove any remaining files from the dotdrop submodule
```bash ```bash
$ rm -rf dotdrop $ rm -rf dotdrop
``` ```
* remove `dotdrop.sh` * Remove `dotdrop.sh`
```bash ```bash
$ git rm dotdrop.sh $ git rm dotdrop.sh
$ git commit -m 'remove dotdrop.sh script' $ git commit -m 'remove dotdrop.sh script'
``` ```
* push upstream * Push upstream
```bash ```bash
$ git push $ 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/open-dynaMIX/dotfiles](https://github.com/open-dynaMIX/dotfiles)
* [https://github.com/moyiz/dotfiles](https://github.com/moyiz/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/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) * [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 # 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`) This repository will contain two main elements, dotdrop's config file (`config.yaml`)
and a directory containing all your dotfiles managed by dotdrop. and a directory containing all your dotfiles managed by dotdrop.
```bash ```bash
@@ -15,12 +15,12 @@ $ mkdir dotfiles
Then add a config file. You can get a Then add a config file. You can get a
[minimal config file](https://github.com/deadc0de6/dotdrop/blob/master/config.yaml) [minimal config file](https://github.com/deadc0de6/dotdrop/blob/master/config.yaml)
from dotdrop's repository with from dotdrop's repository with:
```bash ```bash
$ wget https://raw.githubusercontent.com/deadc0de6/dotdrop/master/config.yaml $ wget https://raw.githubusercontent.com/deadc0de6/dotdrop/master/config.yaml
``` ```
It is recommended to store your config file directly within your repository 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. see [config location](config.md#location) for more.
```bash ```bash

92
docs/templating.md
View File

@@ -1,49 +1,49 @@
# Templating # Templating
Dotdrop leverage the power of [jinja2](https://palletsprojects.com/p/jinja/) to handle the Dotdrop leverages 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/) 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. or the below sections for more information on how to template your dotfiles.
## Templating or not templating ## Templating or not templating
The dotfile config entry [template](config-format.md#dotfiles-entry) The dotfile config entry [template](config-format.md#dotfiles-entry)
and the global config entry [template_dotfile_default](config-format.md#config-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 is not, disabling templating will speed up its installation (since it won't have to be
processed by the engine). processed by the engine).
For dotfiles being symlinked (`link` or `link_children`), see 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 ## Delimiters
Dotdrop uses different delimiters than 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 start = `{%@@`
* block/statement end = `@@%}` * Block/statement end = `@@%}`
* variable/expression start = `{{@@` * Variable/expression start = `{{@@`
* variable/expression end = `@@}}` * Variable/expression end = `@@}}`
* comment start = `{#@@` * Comment start = `{#@@`
* comment end = `@@#}` * 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 ## Template variables
Following variables are available in templates: The following variables are available in templates:
* `{{@@ profile @@}}` contains the profile provided to dotdrop. * `{{@@ profile @@}}` contains the profile provided to dotdrop.
* `{{@@ env['MY_VAR'] @@}}` contains environment variables (see [Environment variables](#environment-variables)). * `{{@@ 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_dotpath @@}}` contains the [dotpath](config-format.md) absolute path.
* `{{@@ _dotdrop_cfgpath @@}}` contains the absolute path to the [config file](config.md). * `{{@@ _dotdrop_cfgpath @@}}` contains the absolute path to the [config file](config.md).
* `{{@@ _dotdrop_workdir @@}}` contains the [workdir](config-format.md) absolute path. * `{{@@ _dotdrop_workdir @@}}` contains the [workdir](config-format.md) absolute path.
* dotfile specific variables (see [Dotfile variables](#dotfile-variables)) * Dotfile specific variables (see [Dotfile variables](#dotfile-variables))
* all defined config variables (see [Variables](config.md#variables)). * All defined config variables (see [Variables](config.md#variables))
* all defined config interpreted variables (see [Interpreted variables](config-details.md#entry-dynvariables)). * All defined config interpreted variables (see [Interpreted variables](config-details.md#dynvariables-entry))
## Dotfile variables ## 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_key @@}}` contains the processed dotfile key.
* `{{@@ _dotfile_link @@}}` contains the processed dotfile `link` string value. * `{{@@ _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_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. * `{{@@ _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_abs_dst` would be `/home/user/.ssh`
* `_dotfile_sub_abs_dst` would be `/home/user/.ssh/config` * `_dotfile_sub_abs_dst` would be `/home/user/.ssh/config`
## Environment variables ## 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'] @@}} {{@@ 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. 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)) It is recommended to use `variables` (see [config variables](config.md#variables))
instead of environment variables unless these contain sensitive information that 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 ## Some secrets
pass="verysecurepassword" 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`. put it in your `.gitignore`.
You can then invoke dotdrop with the help of an alias 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 ## Template methods
Beside [jinja2 global functions](https://jinja.palletsprojects.com/en/2.11.x/templates/#list-of-global-functions) Besides [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: 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') @@%} {%@@ if exists('/dev/null') @@%}
it does exist it does exist
{%@@ endif @@%} {%@@ 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') @@%} {%@@ if exists_in_path('exa') @@%}
alias ls='exa --git --color=always' alias ls='exa --git --color=always'
{%@@ endif @@%} {%@@ 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 ) @@%} {%@@ set dotfile_filename = basename( _dotfile_abs_dst ) @@%}
dotfile dst filename: {{@@ dotfile_filename @@}} 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 ) @@%} {%@@ set dotfile_dirname = dirname( _dotfile_abs_dst ) @@%}
dotfile dst dirname: {{@@ dotfile_dirname @@}} dotfile dst dirname: {{@@ dotfile_dirname @@}}
@@ -133,20 +133,20 @@ config entry `func_file`.
Example: Example:
the config file The config file:
```yaml ```yaml
config: config:
func_file: func_file:
- /tmp/myfuncs_file.py - /tmp/myfuncs_file.py
``` ```
the python function under `/tmp/myfuncs_file.py` The python function under `/tmp/myfuncs_file.py`:
```python ```python
def myfunc(arg): def myfunc(arg):
return not arg return not arg
``` ```
the dotfile content The dotfile content:
``` ```
{%@@ if myfunc(False) @@%} {%@@ if myfunc(False) @@%}
this should exist this should exist
@@ -155,44 +155,44 @@ this should exist
## Template filters ## 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`: custom user-defined filter functions can be loaded using the config entry `filter_file`:
Example: Example:
the config file The config file:
```yaml ```yaml
config: config:
filter_file: filter_file:
- /tmp/myfilter_file.py - /tmp/myfilter_file.py
``` ```
the python filter under `/tmp/myfilter_file.py` The python filter under `/tmp/myfilter_file.py`:
```python ```python
def myfilter(arg1): def myfilter(arg1):
return str(int(arg1) - 10) return str(int(arg1) - 10)
``` ```
the dotfile content The dotfile content:
``` ```
{{@@ "13" | myfilter() @@}} {{@@ "13" | myfilter() @@}}
``` ```
For more information on how to create filters, 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: Macros must be imported `with context` in order to have access to the variables:
``` ```
{%@@ from 'macro_file' import macro with context @@%} {%@@ 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 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. to remind anyone opening the file for editing that this file is managed by dotdrop.
Here's what it looks like: Here's what it looks like:
@@ -205,13 +205,13 @@ The header can be automatically added with:
{{@@ header() @@}} {{@@ header() @@}}
``` ```
Properly commenting the header in templates is the responsibility of the user 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. 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 Either prepend the directive with the commenting char(s) used in the dotfile
(for example `# {{@@ header() @@}}`) or provide it as an argument `{{@@ header('# ') @@}}`. (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 To debug the result of a template, one can install the dotfiles to a temporary
directory with the `install` command and the `-t` switch: 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 ## 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>` * 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` * 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: For more advanced uses:
* `dotdrop --help` for the cli usage. * `dotdrop --help` for the CLI usage.
* [the example](https://github.com/deadc0de6/dotdrop#getting-started) * [The example](https://github.com/deadc0de6/dotdrop#getting-started)
* [the howto](howto/howto.md) * [The howto](howto/howto.md)
## Profile ## Profile
@@ -23,17 +23,17 @@ The default profile used by dotdrop is the *hostname* of the host you are runnin
It can be changed: It can be changed:
* using the command line switch `-p --profile=<profile>` * Using the command line switch `-p`/`--profile=<profile>`
* by defining it in the env variable `DOTDROP_PROFILE` * By defining it in the env variable `DOTDROP_PROFILE`
## Import dotfiles ## Import dotfiles
The `import` command imports dotfiles to be managed by dotdrop. 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. 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 ```bash
$ dotdrop import ~/.xinitrc $ dotdrop import ~/.xinitrc
-> "/home/user/.xinitrc" imported -> "/home/user/.xinitrc" imported
@@ -42,35 +42,35 @@ $ dotdrop import ~/.xinitrc
``` ```
You can control how the dotfile key is generated in the config file 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: Two formats are available:
* *short format* (default): take the shortest unique path * *short format* (default): take the shortest unique path
* *long format*: take the full 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_rc.lua` in the short format
* `f_config_awesome_rc.lua` in the long 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_colors` and `d_vim_colors` in the short format
* `d_mutt_colors` and `d_vim_colors` in the long 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 command line switch `--as` (effectively selecting the `src` part
of the dotfile in the config). It is however recommended of the dotfile in the config). It is however recommended
to use [templating](templating.md) to avoid duplicates and optimize to use [templating](templating.md) to avoid duplicates and optimize
dotfiles management. dotfile management.
```bash ```bash
$ dotdrop import ~/.zshrc --as=~/.zshrc.test $ 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 ## Install dotfiles
@@ -79,49 +79,45 @@ The `install` command installs/deploys dotfiles managed by dotdrop from the `dot
$ dotdrop install $ 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). * `-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 that mode. Note that actions are not executed in this mode.
* `-a --force-actions`: force the execution of actions even if the dotfiles are not installed * `-a`/`--force-actions`: Force the execution of actions even if the dotfiles are not installed
* `-f --force`: do not ask any confirmation * `-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 ## 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 ```bash
$ dotdrop compare $ 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`. 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). 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.
For more options, see the usage with `dotdrop --help`. For more options, see the usage with `dotdrop --help`.
## List profiles ## List profiles
The `profiles` command lists defined profiles in the config file The `profiles` command lists the profiles defined in the config file.
```bash ```bash
$ dotdrop profiles $ 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 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 The default profile can also be changed by defining the
`DOTDROP_PROFILE` environment variable. `DOTDROP_PROFILE` environment variable.
@@ -137,10 +133,10 @@ f_xinitrc
-> link: nolink -> 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. 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: by invoking the `detail` command, for example:
```bash ```bash
$ dotdrop detail $ 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 This is especially useful when the dotfile entry is a directory
and one wants to have information on the different files it contains 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 ## 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. 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 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. 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. When using the `-k`/`--key` switch and no key is provided, all dotfiles for that profile are updated.
```bash ```bash
## update by path ## update by path
$ dotdrop update ~/.vimrc $ 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. 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: There are two cases when updating a dotfile:
### The dotfile doesn't use [templating](templating.md) ### The dotfile doesn't use [templating](templating.md)
The new version of the dotfile is copied to the *dotpath* directory and overwrites 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. `diff` can be used to view the changes.
```bash ```bash
@@ -193,18 +189,18 @@ $ git diff
### The dotfile uses [templating](templating.md) ### 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: changes to apply to the template:
* Use the `compare` command * Use the `compare` command:
```bash ```bash
## use compare to identify change(s) ## use compare to identify change(s)
$ dotdrop compare --file=~/.vimrc $ dotdrop compare --file=~/.vimrc
``` ```
* Call `update` with the `-P --show-patch` switch that will provide with an ad-hoc solution * 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 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) (This isn't a bullet-proof solution and might need manual checking.)
```bash ```bash
## get an ad-hoc solution to manually patch the template ## get an ad-hoc solution to manually patch the template
$ dotdrop update --show-patch ~/.vimrc $ 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 * 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 ```bash
## use install to identify change(s) ## use install to identify change(s)
$ dotdrop install -t -t f_vimrc $ dotdrop install -t -t f_vimrc
@@ -223,17 +219,17 @@ $ diff ~/.vimrc /tmp/dotdrop-6ajz7565/home/user/.vimrc
## Remove dotfiles ## 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: 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` * 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 ## 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 multiple concurrent workers to execute an operation. It can be applied to the following
commands: commands:
@@ -244,37 +240,37 @@ commands:
It should be set to a maximum of the number of cores available (usually returned It should be set to a maximum of the number of cores available (usually returned
on linux by the command `nproc`). on linux by the command `nproc`).
It may speed up the operation but cannot be used interractively (it needs `-f --force` to be set 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 except for `compare`) and cannot be used with `-d`/`--dry`. Also, information printed to stdout/stderr
will probably be messed up. will probably be messed up.
**WARNING** this feature hasn't been extensively tested and is to be used at your own risk. **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). 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 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). `-w`/`--workers`, do please also report it [in an issue](https://github.com/deadc0de6/dotdrop/issues).
## Environment variables ## 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`) Note that CLI switches take precedence over environment variables (except for `DOTDROP_FORCE_NODEBUG`)
* `DOTDROP_PROFILE`: `-p --profile` * `DOTDROP_PROFILE`: `-p`/`--profile`
```bash ```bash
export DOTDROP_PROFILE="my-fancy-profile" export DOTDROP_PROFILE="my-fancy-profile"
``` ```
* `DOTDROP_CONFIG`: `-c --cfg` * `DOTDROP_CONFIG`: `-c`/`--cfg`
```bash ```bash
export DOTDROP_CONFIG="/home/user/dotdrop/config.yaml" export DOTDROP_CONFIG="/home/user/dotdrop/config.yaml"
``` ```
* `DOTDROP_NOBANNER`: `-b --no-banner` * `DOTDROP_NOBANNER`: `-b`/`--no-banner`
```bash ```bash
export DOTDROP_NOBANNER= export DOTDROP_NOBANNER=
``` ```
* `DOTDROP_DEBUG`: `-V --verbose` * `DOTDROP_DEBUG`: `-V`/`--verbose`
```bash ```bash
export DOTDROP_DEBUG= 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 ```bash
export DOTDROP_FORCE_NODEBUG= export DOTDROP_FORCE_NODEBUG=
``` ```
@@ -286,7 +282,7 @@ export DOTDROP_TMPDIR="/tmp/dotdrop-tmp"
```bash ```bash
export DOTDROP_WORKDIR="/tmp/dotdrop-workdir" export DOTDROP_WORKDIR="/tmp/dotdrop-workdir"
``` ```
* `DOTDROP_WORKERS`: overwrite the `-w --workers` cli argument * `DOTDROP_WORKERS`: overwrite the `-w`/`--workers` cli argument
```bash ```bash
export DOTDROP_WORKERS="10" 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 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. 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, 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). 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 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 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. with your test.
Helper functions are available in `helpers`. Helper functions are available in `helpers`.