# CaptainHoog
[](https://travis-ci.org/GateprotectGmbH/captain_hoog)
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 --plugins_dir --project_dir
```
**Please note:** `````` and `````` 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:_ To have more than one plugin directory used, just add as many plugin directories as you want do the ```plugins_dir``` section in the Hoogfile. 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
```
command.
where `````` 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 notification 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.
```rb
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.
```rb
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.
```rb
git.describe 'name of Git head' do |pre|
pre.run do
system "git show --name-only HEAD"
end
end
```
**Plugin specific configurations**
Sometimes a plugin needs specific configurations that not match the use of a helper method. You can add plugin configurations to your Hoogfile by adding a section that is named after the plugin. Let's say there is a plugin called 'clear logs' that needs a 'truncate_line_numbers' configuration. The Hoogfile section would look like:
```yaml
clear logs:
truncate_line_numbers: 100
```
You are able to access this configuration within your plugin by using the ```config``` method:
```rb
git.describe 'clear logs' do |pre|
pre.run do
system "sed -i '#{config.truncate_line_numbers},$ d' development.log"
end
end
```
## Last stuff
Init and written by Daniel Schmidt (daniel.schmidt@gateprotect.com)
Image "Captain Hook" © 2012 Brian Patterson