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 allow developers to add features by running code before or after snapshots are taken. Installed plugin gems are automatically loaded before the capturing process starts.
This gem showcases an example plugin. It prints short messages to the screen before and after every lolcommit. After configuring the plugin to be enabled, you'll see something like this for a capture:
✨ Say cheese 😁 ! *** Preserving this moment in history. 📸 Snap wow! 9e6303c at /path/to/lolcommit.jpg is your best looking commit yet! (it was an image!)
Use this repo to jump-start development on your own plugin. It has tests, docs and hooks with useful tools; Travis, CodeClimate, Rdoc etc.
Developing your own plugin
First, there are some things your gem must do to be loaded and executed:
- The gem name must have a
gemspecfile as a development dependency.
- 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.
Your Plugin Class
You plugin class must have a namespace and path that matches your gem
name and be in the gem's
# for a gem named lolcommits-zapier you should have a plugin class: 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 # at lib/lolcommits/plugin/super_awesome.rb # required in a file at lib/lolcommits/super_awesome.rb
The following methods can be overridden to execute code during the capture process:
run_pre_capture- executes before the capture starts, at this point you could alter the commit message/sha text.
run_post_capture- executes immediately after the camera captures, use this hook to manipulate the image (e.g. resize, apply filters, annotate).
run_capture_ready- executes after all
run_post_capturehooks have ran, at this point we consider the capture to be ready for exporting or sharing.
Available options can be defined in an Array (
@options instance var)
and/or a Hash (by overriding the
By default (on initialize),
@options will be set to
option is mandatory since
configuration[:enabled] == true before any capture hooks can run.
Using a Hash to define default options allows you to:
- fall back to default values (or nil) if the user enters nothing when prompted
- define nested options (the user is prompted for each nested option key)
configure_option_hash will iterate over all options prompting the user
for input while building the configuration Hash.
Lolcommits will save this Hash to a YAML file. During the capture
process the configuration is loaded, parsed and available in the plugin
configuration. Or if you want to fall back to default values,
you should use the
config_option method to dig into the Hash.
Alternatively you can override these methods to fully customise the configuration process.
def configure_options!- by default this prompts the user for option values (based on option names in the
default_options) and returns a Hash that will be persisted.
def enabled?- by default checks if
configuration[:enabled] == trueto determine if the plugin should run.
def valid_configuration?- checks the persisted config Hash is valid.
By default a plugin will only run it's capture hooks if:
parse_user_input method is available to help parse strings from
STDIN to Ruby objects (e.g. boolean, integer or nil).
During plugin configuration, your plugin class will be initialized with
config argument (and no runner). This allows you to read
the existing saved options during configuration. E.g. to show existing
options back to the user, allowing you to ask if they want to keep or
change an option if reconfiguring.
NOTE: If your plugin does not require configuration and should be
enabled by default (on gem install) you could override the
method to always return
true. Simply uninstalling the gem will disable
The Lolcommits 'runner'
The only required argument for your plugin class initializer is a
instance. By default, the base plugin initializer will set this in the
instance var for use in your plugin's code.
runner.message- the commit message
runner.sha- the sha for the current commit
runner.vcs_info- a reference to the Lolcommits::VCSInfo instance
runner.config- a reference to the Lolcommits::Configuration instance
runner.overlay- blank transparent PNG (
runner.lolcommits_path- the processed lolcommit file path (jpg, mp4 or gif)
runner.lolcommits_gif_path- the processed lolcommit animated gif path (may be
truewhen a video capture was generated
truewhen an animated gif capture was generated
truewhen an image (jpg) was captured, false for gifs/videos
After the capturing process completes, (i.e. in
run_capture_ready hooks) use
runner.lolcommit_path to access the
lolcommit file (jpg, mp4 or gif).
NOTE: it is possible for both an animated gif AND video to be
generated, in this case
lolcommits_path points to the
mp4 video and
runner.lolcommits_gif_path points to the animated
Take a look at Lolcommits::Runner for more details.
After capturing (and resizing), the runner provides a blank (transparent) PNG for plugins to manipulate. It matches the width and height of the lolcommit capture.
To make use of this
runner.overlay, reference it in any
hook. You can use any
utility method. For
plugin annotates text, a border and overlay colour
post_capture hooks finish, this overlay PNG is composited on
top of the snapshot and the final lolcommit file is available at
capture_ready hooks to use.
Testing your plugin
To make test setup easier, the lolcommits gem includes these helpers to work with command line IO and Git.
# 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 commit_repo_with_message # perform a git commit in the test repo last_commit # commit info for the last test repo commit teardown_repo # destroy the test repo in_repo(&block) # run lolcommits within the test repo
For STDIN and capturing IO use the
# capture the output of the `configure_options` method, sending the # string input 'true' (followed by a carriage return) to STDIN: output = fake_io_capture(inputs: %w(true)) do configured_plugin_options = plugin.configure_options! end
For more examples take a look at the tests in this repo.
- Use this gem as a starting point, renaming files, classes etc.
- For more examples, take a look at other published lolcommit plugins.
- If you feel something is missing (or out of date) in this guide. Post an issue.
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` and configure other options as you like
That's it! Every lolcommit now comes with it's own emoji themed commentary!
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 report.
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.