Add default options

This feature was implemented with feedback from Aleks Kamko
<aykamko@gmail.com> and Casey Rodarmor <casey@rodarmor.com>.

1 files changed, 35 insertions, 0 deletions

diff --git a/README.md b/README.md
index 3ed74f5..1b42f75 100644
--- a/README.md
+++ b/README.md
@@ -78,6 +78,10 @@ Here's an example of a complete configuration.
 The conventional name for the configuration file is `install.conf.yaml`.
 
 ```yaml
+- defaults:
+    link:
+      relink: true
+
 - clean: ['~']
 
 - link:
@@ -98,6 +102,13 @@ The conventional name for this file is `install.conf.json`.
 ```json
 [
     {
+        "defaults": {
+            "link": {
+                "relink": true
+            }
+        }
+    },
+    {
         "clean": ["~"]
     },
     {
@@ -225,6 +236,30 @@ Clean commands are specified as an array of directories to be cleaned.
 - clean: ['~']
 ```
 
+### Defaults
+
+Default options for plugins can be specified so that options don't have to be
+repeated many times. This can be very useful to use with the link command, for
+example.
+
+Defaults apply to all commands that follow setting the defaults. Defaults can
+be set multiple times; each change replaces the defaults with a new set of
+options.
+
+#### Format
+
+Defaults are specified as a dictionary mapping action names to settings, which
+are dictionaries from option names to values.
+
+#### Example
+
+```yaml
+- defaults:
+    link:
+      create: true
+      relink: true
+```
+
 ### Plugins
 
 Dotbot also supports custom directives implemented by plugins. Plugins are