Lolcommits Sample Plugin
lolcommits takes a snapshot with your webcam every time you git commit code, and archives a lolcat style image with it. Git blame has never been so much fun!
Lolcommit plugins are automatically loaded before the capturing process starts. The flexible class design allows developers to add features by running code before or after snapshots are taken.
This gem showcases an example plugin. It prints short messages to the screen before and after every lolcommit. Something like this;
Use this repo to jump-start development on your own plugin. It has good tests, docs and working hooks to useful tools (Travis, CodeClimate, Rdoc etc.) See below for more information on how to get started.
Developing your own plugin
First, there are some things your gem must do to be loaded and executed correctly. At the very least:
- Name your gem with the
- Include a class that inherits from
Lolcommits::Plugin::Base(this will be the entry point to your plugin from the lolcommits gem).
- This main plugin class must meet the requirements explained below.
lolcommitsin your gem spec as a development dependency.
Your Plugin Class
You plugin class must have a namespace and path that matches your gem name and
be in the
LOAD_PATH (required) with the gem for example:
# a gem named: lolcommits-zapier # should have a plugin class inheriting from Base like so: class Lolcommits::Plugin::Zapier < Lolcommits::Plugin::Base ... end # at lib/lolcommits/plugin/zapier.rb # required in a file at lib/lolcommits/zapier.rb # or a gem named: lolcommits-super_awesome # should have a plugin class class Lolcommits::Plugin::SuperAwesome < Lolcommits::Plugin::Base ... end # required in a file at lib/lolcommits/super_awesome.rb
You should override the following methods in this class:
def self.name- identifies the plugin to lolcommits and users, keep things simple and choose a name that matches your gem name.
def self.runner_order- return the hooks this plugin should run at during the capture process (
def run_capture_ready- override with your plugin's behaviour.
Three hooks points are available during the lolcommits capture process.
:pre_capture- called before the camera starts capturing, at this point you could alter the commit message/sha text.
:post_capture- called immediately after the camera snaps the raw image (or video for gif captures) use this hook to alter the image, other plugins may hook here to modify the image too.
:capture_ready- called after all
:post_captureplugins have ran, at this point the capture should be ready for exporting or sharing.
Base class initializer defines an
@options instance var, with an array
of setting names that the user can configure. By default, the only option is
enabled and plugins must be configured as
enabled = true to run.
A plugin can be configured by the lolcommits gem with;
lolcommits --config # or lolcommits --config -p plugin-name
configuration method in your plugin class to read these options.
Plugin methods you may want to override with custom configuration code include:
def enabled?- usually checks
configuration['enabled']to determine if the plugin should run.
def configure_options!- prompts the user for configuration (based on the
@options) returns a hash that will be persisted.
def configured?- checks the persisted config hash is present.
def valid_configuration?- checks the persisted config hash has valid data.
If your plugin requires no configuration, you could override the
method to always return
true. Users could disable your plugin by uninstalling
By default a plugin will only run it's capture hooks if:
The Lolcommits 'runner'
The only required argument for your plugin class initializer is a
Lolcommits::Runner instance. By default, the base plugin initializer will set
this in the
runner instance var.
Use these runner methods to access the commit, repo and configuration:
runner.message- the git commit message.
runner.sha- the git sha for the current commit.
runner.vcs_info- a reference to the Lolcommits::VCSInfo instance.
runner.config- a reference to the Lolcommits::Configuration instance.
After the capturing process has completed, (i.e. in the
run_capture_ready hooks) these methods will reveal the captured snapshot file.
runner.snapshot_loc- the raw image file.
runner.main_image- the processed image file, resized, with text overlay applied (or any other effects from other plugins).
During plugin configuration, your plugin class will be initialized with the
config argument (and no runner). This allows you to read the existing
saved options during configuration. E.g. to show the existing options back to
Take a look at the Lolcommits::Runner for more details.
Testing your plugin
It's a good idea to include tests with your gem. To make this easier for you, the main lolcommits gem provides helpers to work with IO and Git repos in test.
# add one or both of these to your plugin's test_helper file require 'lolcommits/test_helpers/git_repo' require 'lolcommits/test_helpers/fake_io' # and include either (or both) modules in your test include Lolcommits::TestHelpers::GitRepo include Lolcommits::TestHelpers::FakeIO
Use the following methods to manage a test repo:
setup_repo # create the test repo # perform a git commit in the test repo last_commit # git commit info for the last commit in the test repo teardown_repo # destroy the test repo in_repo(&block) # run lolcommits within the test repo
For submitting and capturing IO use the
fake_io_capture method. E.g. to
capture the output of the
configure_options method, while sending the string
input 'true' (followed by a carriage return) when prompted on STDIN:
output = fake_io_capture(inputs: %w(true)) do = plugin. end
For more examples take a look at the tests in this repo (MiniTest).
Use this gem as a starting point, renaming files, classes and references. Or build a new plugin gem from scratch with:
bundle gem lolcommits-my-plugin
For more examples, take a look at other published lolcommit plugins.
If you feel something is missing (or out of date) in this short guide. Please create a new issue.
Until recently, all plugins lived inside the main lolcommits gem. We are in the process of extracting them to individual gems, loaded with the new plugin manager. Ruby gem versioning will take care of managing dependencies and compatibility with the main gem.
Follow the install guide for lolcommits first. Then run the following:
$ gem install lolcommits-sample_plugin
Next configure and enable this plugin with:
$ lolcommits --config -p sample_plugin # set enabled to `true`
That's it! Every lolcommit now comes with it's own short (emoji themed) message!
Check out this repo and run
bin/setup, this will install dependencies and
generate docs. Run
bundle exec rake to run all tests and generate a coverage
You can also run
bin/console for an interactive prompt that will allow you to
experiment with the gem code.
MiniTest is used for testing. Run the test suite with:
$ rake test
Generate docs for this gem with:
$ rake rdoc
If you think something is broken or missing, please raise a new issue. Take a moment to check it hasn't been raised in the past (and possibly closed).
The gem is available as open source under the terms of LGPL-3.