From c402396c58114640745dbba132856cfd8cd7f422 Mon Sep 17 00:00:00 2001 From: Anish Athalye Date: Sat, 6 Feb 2016 13:54:19 -0500 Subject: [PATCH] Add documentation and tests for plugins --- README.md | 17 ++++++++++++++++- test/tests/plugin-dir.bash | 29 +++++++++++++++++++++++++++++ test/tests/plugin.bash | 28 ++++++++++++++++++++++++++++ 3 files changed, 73 insertions(+), 1 deletion(-) create mode 100644 test/tests/plugin-dir.bash create mode 100644 test/tests/plugin.bash 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 ------------ diff --git a/test/tests/plugin-dir.bash b/test/tests/plugin-dir.bash new file mode 100644 index 0000000..299f144 --- /dev/null +++ b/test/tests/plugin-dir.bash @@ -0,0 +1,29 @@ +test_description='directory-based plugin loading works' +. '../test-lib.bash' + +test_expect_success 'setup' ' +mkdir ${DOTFILES}/plugins +cat > ${DOTFILES}/plugins/test.py < ${DOTFILES}/test.py <