plugins.md

Plugins

Plugins are a powerful way to encapsulate and share complex functionalities in an easily importable package.

Definition

Plugins can be used to define commands, learn more about commands and the configuration.

There are multiple ways to write plugins:

String

These are plain shell commands, they won't look pretty though:

'rm -rf node_modules'

Function

They will be called with:

• config: autogit's configuration object.
• repoPath: the absolute path of the target repository.
• ctx: Listr's ctx object.
• task: Listr's task object.

function myPlugin ( config, repoPath, ctx, task ) {
  // Plugin logic...
}

You can additionally define a title property, which will be used instead of the name of the function if available:

myPlugin.title = 'My Plugin';

Function => Listr

You can also return an instance of Listr from your plugin function, this will allow you to define subtasks.

const Listr = require ( 'listr' );

function myPlugin ( config, repoPath, ctx, task ) {

  return new Listr ([
    {
      title: 'Noop',
      task: () => true
    },
    {
      title: 'Lottery',
      enabled: () => Math.random () > 0.5,
      task: () => true
    }
  ]);

}

Function Factory

If you want your plugin to be able to accept options you should wrap it in a function that can accept options:

function factory ( options = {} ) {

  return function myPlugin ( config, repoPath, ctx, task ) {
    // Some code...
  };

  /* --- OR --- */

  return function myPlugin ( config, repoPath, ctx, task ) {
    return new Listr ([
      // Some tasks...
    ]);
  };

}

Notes

• Respect --dry: Unless you're writing your plugin as a string, where this is handled for you, you should always make sure you're respecting the --dry flag and only simulate doing the work when its setted. You can retrieve this value with config.dry.

Community Plugins

You can find most of the plugins made by the community in the awesome-autogit repository.

Plugins should follow the UNIX philosophy and be minimalistic and easily composable into commands.