Merge branch 'master' into clear-on-install

docs/config/config-config.md

@@ -4,7 +4,7 @@ The **config** entry (mandatory) contains global settings.
 
 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 existing destination; see [backup entry](config-config.md#backup-entry)) | true
 `banner` | Display the banner  | true
 `check_version` | Check if a new version of dotdrop is available on github | false
 `chmod_on_import` | Always add a chmod entry on newly imported dotfiles (see `--preserve-mode`) | false
@@ -212,4 +212,16 @@ profiles:
   hostname:
     dotfiles:
     - f_vimrc
-```
+```
+
+## backup entry
+
+When set to `true`, existing files that would be replaced
+by a dotdrop `install`, are backed up with the
+extension `.dotdropbak` if their content differ.
+
+Note:
+* directories will **not** be backed up, only files
+* when using a different `link` value than `nolink` with directories,
+  the files under the directory will **not** be backed up
+  (See [Symlinking dotfiles](config-file.md#symlinking-dotfiles)),

docs/config/config-dotfiles.md

@@ -14,11 +14,13 @@ Entry    | Description
 `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-file.md#ignore-patterns))
 `template` | If false, disable templating for this dotfile (defaults to the value of `template_dotfile_default`)
-`trans_read` | Transformation key to apply when installing this dotfile (must be defined in the **trans_read** entry below; see [transformations](config-transformations.md))
-`trans_write` | Transformation key to apply when updating this dotfile (must be defined in the **trans_write** entry below; see [transformations](config-transformations.md))
+`trans_install` | Transformation key to apply when installing this dotfile (must be defined in the **trans_install** entry below; see [transformations](config-transformations.md))
+`trans_update` | Transformation key to apply when updating this dotfile (must be defined in the **trans_update** entry below; see [transformations](config-transformations.md))
 `upignore` | List of patterns to ignore when updating (enclose in quotes when using wildcards; see [ignore patterns](config-file.md#ignore-patterns))
 <s>link_children</s> | Replaced by `link: link_children`
-<s>trans</s> | Replaced by `trans_read`
+<s>trans</s> | Replaced by `trans_install`
+<s>trans_read</s> | Replaced by `trans_install`
+<s>trans_write</s> | Replaced by `trans_update`
 
 ```yaml
 <dotfile-key-name>:
@@ -37,8 +39,8 @@ Entry    | Description
     - <action-key>
   template: (true|false)
   chmod: '<file-permissions>'
-  trans_read: <transformation-key>
-  trans_write: <transformation-key>
+  trans_install: <transformation-key>
+  trans_update: <transformation-key>
 ```
 
 ## Dotfile actions

docs/config/config-file.md

@@ -91,17 +91,17 @@ dotfiles:
     dst: ~/dir
     chmod: 744
   f_preserve:
-    src: preserve
-    dst: ~/preserve
+    src: pfile
+    dst: ~/pfile
     chmod: preserve
 ```
 
-The `chmod` value defines the file permissions in octal notation to apply on dotfiles. If undefined
+The `chmod` value defines the file permissions in octal notation to apply to the dotfile. If undefined
 new files will get the system default permissions (see `umask`, `777-<umask>` for directories and
 `666-<umask>` for files).
 
 The special keyword `preserve` allows to ensure that if the dotfiles already exists
-on the filesystem, it is not altered during `install` and the `chmod` value won't
+on the filesystem, its permission is not altered during `install` and the `chmod` config value won't
 be changed during `update`.
 
 On `import`, the following rules are applied:

docs/config/config-transformations.md

@@ -14,14 +14,14 @@ For examples of transformation uses, see:
 
 There are two types of transformations available:
 
-* **Read transformations**: used to transform dotfiles before they are installed ([config](config-config.md) key `trans_read`)
+* **Install transformations**: used to transform dotfiles before they are installed ([config](config-config.md) key `trans_install`)
     * Used for commands `install` and `compare`
     * They have two mandatory arguments:
         * **{0}** will be replaced with the dotfile to process
         * **{1}** will be replaced with a temporary file to store the result of the transformation
     * This Happens **before** the dotfile is templated (see [templating](../template/templating.md))
 
-* **Write transformations**: used to transform files before updating a dotfile ([config](config-config.md) key `trans_write`)
+* **Update/Import transformations**: used to transform files before updating/importing a dotfile ([config](config-config.md) key `trans_update`)
     * Used for command `update` and `import`
     * They have two mandatory arguments:
         * **{0}** will be replaced with the file path to update the dotfile with
@@ -36,13 +36,13 @@ Transformations also support additional positional arguments that must start fro
 
 For example:
 ```yaml
-trans_read:
+trans_install:
   targ: echo "$(basename {0}); {{@@ _dotfile_key @@}}; {2}; {3}" > {1}
 dotfiles:
   f_abc:
     dst: /tmp/abc
     src: abc
-    trans_read: targ "{{@@ profile @@}}" lastarg
+    trans_install: targ "{{@@ profile @@}}" lastarg
 profiles:
   p1:
     dotfiles:
@@ -51,21 +51,21 @@ profiles:
 
 will result in `abc; f_abc; p1; lastarg`.
 
-## trans_read entry
+## trans_install entry
 
-The **trans_read** entry (optional) contains a transformations mapping (See [transformations](config-transformations.md)).
+The **trans_install** entry (optional) contains a transformations mapping (See [transformations](config-transformations.md)).
 
 ```yaml
-trans_read:
+trans_install:
    <trans-key>: <command-to-execute>
 ```
 
-## trans_write entry
+## trans_update entry
 
-The **trans_write** entry (optional) contains a write transformations mapping (See [transformations](config-transformations.md)).
+The **trans_update** entry (optional) contains a write transformations mapping (See [transformations](config-transformations.md)).
 
 ```yaml
-trans_write:
+trans_update:
    <trans-key>: <command-to-execute>
 ```
 
@@ -77,10 +77,10 @@ and [template variables](../template/template-variables.md#template-variables)).
 
 A very dumb example:
 ```yaml
-trans_read:
+trans_install:
   r_echo_abs_src: echo "{0}: {{@@ _dotfile_abs_src @@}}" > {1}
   r_echo_var: echo "{0}: {{@@ r_var @@}}" > {1}
-trans_write:
+trans_update:
   w_echo_key: echo "{0}: {{@@ _dotfile_key @@}}" > {1}
   w_echo_var: echo "{0}: {{@@ w_var @@}}" > {1}
 variables:
@@ -90,11 +90,11 @@ dotfiles:
   f_abc:
     dst: ${tmpd}/abc
     src: abc
-    trans_read: r_echo_abs_src
-    trans_write: w_echo_key
+    trans_install: r_echo_abs_src
+    trans_update: w_echo_key
   f_def:
     dst: ${tmpd}/def
     src: def
-    trans_read: r_echo_var
-    trans_write: w_echo_var
+    trans_install: r_echo_var
+    trans_update: w_echo_var
 ```

docs/howto/sensitive-dotfiles.md

@@ -37,9 +37,9 @@ First you need to define the encryption/decryption methods, for example
 ```yaml
 variables:
   keyid: "11223344"
-trans_read:
+trans_install:
   _decrypt: "gpg -q --for-your-eyes-only--no-tty -d {0} > {1}"
-trans_write:
+trans_update:
   _encrypt: "gpg -q -r {{@@ keyid @@}} --armor --no-tty -o {1} -e {0}"
 ```
 
@@ -60,17 +60,17 @@ Using GPG keys:
 ```yaml
 variables:
   keyid: "11223344"
-trans_read:
+trans_install:
   _decrypt: "gpg -q --for-your-eyes-only--no-tty -d {0} > {1}"
-trans_write:
+trans_update:
   _encrypt: "gpg -q -r {{@@ keyid @@}} --armor --no-tty -o {1} -e {0}"
 ```
 
 Passphrase is stored in an environment variable:
 ```yaml
-trans_read:
+trans_install:
   _decrypt: "echo {{@@ env['THE_KEY'] @@}} | gpg -q --batch --yes --for-your-eyes-only --passphrase-fd 0 --no-tty -d {0} > {1}"
-trans_write:
+trans_update:
   _encrypt: "echo {{@@ env['THE_KEY'] @@}} | gpg -q --batch --yes --passphrase-fd 0 --no-tty -o {1} -c {0}"
 ```
 
@@ -78,9 +78,9 @@ Passphrase is stored as a variable:
 ```yaml
 variables:
   gpg_password: "some password"
-trans_read:
+trans_install:
   _decrypt: "echo {{@@ gpg_password @@}} | gpg -q --batch --yes --for-your-eyes-only --passphrase-fd 0 --no-tty -d {0} > {1}"
-trans_write:
+trans_update:
   _encrypt: "echo {{@@ gpg_password @@}} | gpg -q --batch --yes --passphrase-fd 0 --no-tty -o {1} -c {0}"
 ```
 
@@ -88,9 +88,9 @@ Passphrase is retrieved using a script:
 ```yaml
 dynvariables:
   gpg_password: "./get-password.sh"
-trans_read:
+trans_install:
   _decrypt: "echo {{@@ gpg_password @@}} | gpg -q --batch --yes --for-your-eyes-only --passphrase-fd 0 --no-tty -d {0} > {1}"
-trans_write:
+trans_update:
   _encrypt: "echo {{@@ gpg_password @@}} | gpg -q --batch --yes --passphrase-fd 0 --no-tty -o {1} -c {0}"
 ```
 
@@ -100,9 +100,9 @@ variables:
   gpg_password_file: "/tmp/the-password"
 dynvariables:
   gpg_password: "cat {{@@ gpg_password_file @@}}"
-trans_read:
+trans_install:
   _decrypt: "echo {{@@ gpg_password @@}} | gpg -q --batch --yes --for-your-eyes-only --passphrase-fd 0 --no-tty -d {0} > {1}"
-trans_write:
+trans_update:
   _encrypt: "echo {{@@ gpg_password @@}} | gpg -q --batch --yes --passphrase-fd 0 --no-tty -o {1} -c {0}"
 ```
 

docs/howto/store-compressed-directories.md

@@ -1,13 +1,13 @@
 # Handle compressed directories
 
-This is an example of how to use transformations (`trans_read` and `trans_write`) to store
+This is an example of how to use transformations (`trans_install` and `trans_update`) to store
 compressed directories and deploy them with dotdrop.
 
 Start by defining the transformations:
 ```yaml
-trans_read:
+trans_install:
   uncompress: "mkdir -p {1} && tar -xf {0} -C {1}"
-trans_write:
+trans_update:
   compress: "tar -cf {1} -C {0} ."
 ```
 

docs/usage.md

@@ -235,6 +235,21 @@ dotdrop. It will:
 
 For more options, see the usage with `dotdrop --help`.
 
+## Uninstall dotfiles
+
+The `uninstall` command removes dotfiles installed by dotdrop
+```bash
+$ dotdrop uninstall
+```
+
+It will remove the installed dotfiles related to the provided key
+(or all dotfiles if not provided) of the selected profile.
+
+If a backup exists ([backup entry](config/config-config.md#backup-entry)),
+the file will be restored.
+
+For more options, see the usage with `dotdrop --help`.
+
 ## Concurrency
 
 The command line switch `-w`/`--workers`, if set to a value greater than one, enables the use