CaptainHoog

Okay. That's not such a funny gem name. But it's a reference to Git and the subject of the gem: the Git Hooks.

Installation

Add this line to your application's Gemfile:

gem 'captain_hoog'

And then execute:

$ bundle

Or install it yourself as:

$ gem install captain_hoog

Usage

Install the hook

githoog install --type <GIT_HOOK_TYPE> --plugins_dir <PATH_TO_PLUGINS> --project_dir <PATH_TO_PROJECT>

Please note: <PATH_TO_PLUGINS> and <PATH_TO_PROJECT> must be given as absolute paths. Also make sure to run this from your git repository's root folder.

GIT_HOOK_TYPE may be something like this

pre-commit (default)
pre-push
pre-rebase
pre-applypatch

If the directory where pre-git test should be done, differs from the working directory adjust:

--project_dir

to your needs. You can omit this.

--plugins_dir

is not required anymore. If it's omited it will point to the actual directory you run the install script from. It should point to the directory you store the CaptainHoog plugins.

A note about plugin directories: All plugins must be placed in one directory. You can select which plugin is called from which Git hook later by defining it in the Hoogfile.

Removing the hook

Remove a hook by using the

githoog remove --type <GIT_HOOK_TYPE>

command.

where <GIT_HOOK_TYPE> is pre-commit by default.

The Hoogfile

All plugin executable and ignoring power is configurable in the Hoogfile. The Hoogfile's name is hoogfile.yml and it will be installed in your Git root directory. If you install several hooks, the installer will ask you if you want to override the config file.

The Hoogfile has several sections:

hook plugins per type
project dir
plugins dir

Some options are predefined from your information you provided during installation:

project dir
plugins dir

If this did not matches your need anymore, just pass the new paths in there.

Captain Hoog is doing nothing by default. You have explicitly define which plugins it should run or which not. You do this per hook type. E.g. for pre-commit:

pre-commit:
  - cucumber
  - rspec

So the plugins named cucumber and rspec are running before your commit applies to the index.

Migrating from pre 1.0 versions

There is no migration path from previous versions. Just re-install and adjust the Hoogfile to your previous configuration.

Writing plugins

A CaptainHoog plugin is written with a very simple DSL that used with the following expressions:

test
message
helper
run

Within test any stuff is done that either forces the commit to exit or to pass. Whatever you want to do like syntax checking, code style checking - implement it and make sure you return a boolean value.

message is used to define a notifiaction that is shown to the user if the test fails. This obviously must return a String.

You have to add a description (or name) to your plugin, this description (or name) will be used to check if the plugin should be executed or not by adding the plugins name to the section of your Hoogfile.

git.describe 'sample' do |pre|

  pre.test do
    # do any test like code style guide, syntax checking...
    # Must return a boolean value.
  end

  pre.message do
    # Define a message string here that is shown if the test fails.
  end

end

With helper you can extract some logic into a helper method that is useable anywhere in the plugin.

git.describe 'logger' do |pre|

  pre.helper :collect_logger_outputs do
    # do something
  end

  pre.test do
    collect_logger_outputs.empty?
  end

  pre.message do
   %q{ You have some logger outputs in your code! }
  end
end

If you don't want to test anything before commiting or pushing thus just running a command or something similiar, use the run method.

git.describe 'name of Git head' do |pre|

  pre.run do
    system "git show --name-only HEAD"
  end

end

Last stuff

Init and written by Daniel Schmidt ([email protected])