From b5d8745fea1d996059dcb6108a10d324422e79ff Mon Sep 17 00:00:00 2001
From: deadc0de6 <info@deadc0de.ch>
Date: Mon, 9 Nov 2020 21:08:27 +0100
Subject: [PATCH] adding chmod doc

---
 docs/config-format.md |  1 +
 docs/config.md        | 36 ++++++++++++++++++++++++++++++++++++
 2 files changed, 37 insertions(+)

diff --git a/docs/config-format.md b/docs/config-format.md
index 666e5a3..3cc1649 100644
--- a/docs/config-format.md
+++ b/docs/config-format.md
@@ -46,6 +46,7 @@ Entry    | Description
 `src` | dotfile path within the `dotpath` (dotfile with empty `src` are ignored and considered installed, can use `variables` and `dynvariables`, make sure to quote)
 `link` | define how this dotfile is installed. Possible values: *nolink*, *link*, *link_children* (see [Symlinking dotfiles](config.md#symlink-dotfiles)) (defaults to value of `link_dotfile_default`)
 `actions` | list of action keys that need to be defined in the **actions** entry below (see [actions](config-details.md#entry-actions))
+`chmod` | defines the file permission 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))
 `ignoreempty` | if true empty template will not be deployed (defaults to value of `ignoreempty`)
 `instignore` | list of patterns to ignore when installing (enclose in quotes when using wildcards, see [ignore patterns](config.md#ignore-patterns))
diff --git a/docs/config.md b/docs/config.md
index 46b7a0f..7cd2366 100644
--- a/docs/config.md
+++ b/docs/config.md
@@ -59,6 +59,42 @@ Here are some rules on the use of variables in configs:
 * external/imported `(dyn)variables` take precedence over
   `(dyn)variables` defined inside the main config file
 
+## Permissions
+
+Dotfile allows to control the permission applied to a dotfile using the
+config dotfile entry `chmod`.
+A `chmod` entry on a directory is applied to the directory only, not recursively.
+
+On `import` the following rules are applied:
+
+* if the `-m --preserve-mode` switch is provided the imported file permissions are
+  stored in the `chmod` entry
+* if imported file permissions differ from umask its permissions are automatically
+  stored in the `chmod` entry
+
+On `install` the following rules are applied:
+
+* if `chmod` is specified, it will be applied to the installed dotfile
+* if file exists and its permissions differ from `umask` and no `chmod` is specified user needs
+  to confirm installation (unless `-f --force` is used) **TODO unless permissions match existing file**
+
+On `update`:
+
+* **TODO**
+
+One `compare`:
+
+* **TODO**
+
+Make sure to quote the `chmod` value in the config file:
+```yaml
+dotfiles:
+  f_xinitrc:
+    dst: ~/.xinitrc
+    src: xinitrc
+    chmod: '777'
+```
+
 ## Symlink dotfiles
 
 Dotdrop is able to install dotfiles in three different ways