From c402396c58114640745dbba132856cfd8cd7f422 Mon Sep 17 00:00:00 2001 From: Anish Athalye Date: Sat, 6 Feb 2016 13:54:19 -0500 Subject: Add documentation and tests for plugins --- README.md | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) (limited to 'README.md') diff --git a/README.md b/README.md index 83b16c5..00c654d 100644 --- a/README.md +++ b/README.md @@ -122,7 +122,7 @@ Configuration Dotbot uses YAML or JSON formatted configuration files to let you specify how to set up your dotfiles. Currently, Dotbot knows how to [link](#link) files and folders, execute [shell](#shell) commands, and [clean](#clean) directories of -broken symbolic links. +broken symbolic links. Dotbot also supports user plugins for custom commands. **Ideally, bootstrap configurations should be idempotent. That is, the installer should be able to be run multiple times without causing any @@ -224,6 +224,21 @@ Clean commands are specified as an array of directories to be cleaned. - clean: ['~'] ``` +### Plugins + +Dotbot also supports custom directives implemented by plugins. Plugins are +implemented as subclasses of `dotbot.Plugin`, so they must implement +`can_handle()` and `handle()`. The `can_handle()` method should return `True` +if the plugin can handle an action with the given name. The `handle()` method +should do something and return whether or not it completed successfully. + +All built-in Dotbot directives are written as plugins that are loaded by +default, so those can be used as a reference when writing custom plugins. + +Plugins are loaded using the `--plugin` and `--plugin-dir` options, using +either absolute paths or paths relative to the base directory. It is +recommended that these options are added directly to the `install` script. + Contributing ------------ -- cgit v1.2.3