Merge pull request #292 from deadc0de6/chmod

Chmod

.github/workflows/testing.yml

@@ -20,15 +20,24 @@ jobs:
       run: |
         python -m pip install --upgrade pip
         pip install -r tests-requirements.txt
+        pip install --user --upgrade coverage
         pip install -r requirements.txt
         npm install -g remark-cli remark-validate-links
         npm install -g markdown-link-check
-    - name: Run tests
+    - name: Run sequential tests
       run: |
         ./tests.sh
       env:
         DOTDROP_FORCE_NODEBUG: yes
         DOTDROP_NOBANNER: yes
+        DOTDROP_WORKERS: 1
+    - name: Run parallel tests
+      run: |
+        ./tests.sh
+      env:
+        DOTDROP_FORCE_NODEBUG: yes
+        DOTDROP_NOBANNER: yes
+        DOTDROP_WORKERS: 4
     - name: Coveralls
       run: |
         coveralls

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))

docs/config.md

@@ -59,6 +59,31 @@ 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
+
+Dotdrop allows to control the permission applied to a dotfile using the
+config dotfile entry [chmod](config-format.md#dotfiles-entry).
+A [chmod](config-format.md#dotfiles-entry) entry on a directory is applied to the
+directory only, not recursively.
+
+On `import` the following rules are applied:
+
+* if the `-m --preserve-mode` switch is provided the imported file permissions are
+  stored in a `chmod` entry
+* if imported file permissions differ from umask then its permissions are automatically
+  stored in the `chmod` entry
+* otherwise no `chmod` entry is added
+
+On `install` the following rules are applied:
+
+* if `chmod` is specified in the dotfile, it will be applied to the installed dotfile
+* otherwise the permissions of the dotfile in the `dotpath` are applied.
+
+On `update`:
+
+* if the permissions of the file in the filesystem differ from the dotfile in the `dotpath`
+  then the dotfile entry `chmod` is added/updated accordingly
+
 ## Symlink dotfiles
 
 Dotdrop is able to install dotfiles in three different ways

docs/howto/howto.md

@@ -28,7 +28,7 @@
 
 ## Manage system dotfiles
 
-[Manage system dotfiles](global-config-files.md)
+[Manage system dotfiles](system-config-files.md)
 
 ## Merge files on install
 

docs/howto/system-config-files.md

@@ -0,0 +1,29 @@
+# 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.
+
+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.
+
+It is therefore recommended to have two different config files (and thus two different *dotpath*)
+for handling these two uses cases:
+
+For example:
+
+* one `config-user.yaml` for the local/user dotfiles (with its dedicated *dotpath*, for example `dotfiles-user`)
+* one `config-root.yaml` for the system/root dotfiles (with its dedicated *dotpath*, for example `dotfiles-root`)
+
+`config-user.yaml` is used when managing the user's dotfiles
+```bash
+## user config file is config-user.yaml
+$ ./dotdrop.sh import --cfg config-user.yaml <some-dotfile>
+$ ./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
+```bash
+## root config file is config-root.yaml
+$ sudo ./dotdrop.sh import --cfg=config-root.yaml <some-dotfile>
+$ sudo ./dotdrop.sh install --cfg=config-root.yaml
+...
+```

docs/usage.md

@@ -226,6 +226,28 @@ dotdrop. It will:
 
 For more options, see the usage with `dotdrop --help`
 
+## Concurrency
+
+The command line switch `-w --workers` if set to a value greater than one allows to use
+multiple concurrent workers to execute an operation. It can be applied to the following
+commands:
+
+* `install`
+* `compare`
+* `update`
+
+It should be set to a maximum of the number of cores available (usually returned
+on linux by the command `nproc`).
+
+It may speed up the operation but cannot be used interractively (it needs `-f --force` to be set
+except for `compare`) and cannot be used with `-d --dry`. Also information printed to stdout/stderr
+will probably be messed up.
+
+**WARNING** this feature hasn't been extensively tested and is to be used at your own risk.
+If you try it out and find any issue, please [report it](https://github.com/deadc0de6/dotdrop/issues).
+Also if you find it useful and have been able to successfully speed up your operation when using
+`-w --workers`, do please also report it [in an issue](https://github.com/deadc0de6/dotdrop/issues).
+
 ## Environment variables
 
 Following environment variables can be used to specify different CLI options.
@@ -255,3 +277,11 @@ export DOTDROP_FORCE_NODEBUG=
 ```bash
 export DOTDROP_TMPDIR="/tmp/dotdrop-tmp"
 ```
+* `DOTDROP_WORKDIR`: overwrite the `workdir` defined in the config
+```bash
+export DOTDROP_WORKDIR="/tmp/dotdrop-workdir"
+```
+* `DOTDROP_WORKERS`: overwrite the `-w --workers` cli argument
+```bash
+export DOTDROP_WORKERS="10"
+```