Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/wecodemore/grunt-githooks
A Grunt plugin to help bind Grunt tasks to Git hooks
https://github.com/wecodemore/grunt-githooks
Last synced: about 3 hours ago
JSON representation
A Grunt plugin to help bind Grunt tasks to Git hooks
- Host: GitHub
- URL: https://github.com/wecodemore/grunt-githooks
- Owner: wecodemore
- License: mit
- Created: 2013-09-01T23:15:35.000Z (over 11 years ago)
- Default Branch: master
- Last Pushed: 2022-08-03T19:29:21.000Z (over 2 years ago)
- Last Synced: 2025-01-04T18:07:20.939Z (7 days ago)
- Language: JavaScript
- Homepage: https://npmjs.org/package/grunt-githooks
- Size: 89.8 KB
- Stars: 317
- Watchers: 11
- Forks: 24
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE-MIT
Awesome Lists containing this project
- awesome-git-hooks - Grunt GitHooks - Setup, manage and update your hooks with Grunt. Can be used with all languages, supports templates. (Tools)
README
# grunt-githooks v0.6.0
[](https://travis-ci.org/wecodemore/grunt-githooks)
[](https://codeclimate.com/github/wecodemore/grunt-githooks)
[](https://www.npmjs.org/package/grunt-githooks)
> A Grunt plugin to help bind Grunt tasks to Git hooks
## Getting Started
This plugin requires at least Grunt `~0.4.1`
If you haven't used [Grunt](http://gruntjs.com/) before, be sure to check out the
[Getting Started](http://gruntjs.com/getting-started) guide, as it explains how to
create a [Gruntfile](http://gruntjs.com/sample-gruntfile) as well as install and
use Grunt plugins. Once you're familiar with that process, you may install this
plugin with this command:
```shell
npm install grunt-githooks --save-dev
```
Once the plugin has been installed, it may be enabled inside your
Gruntfile with this line of JavaScript:
```js
grunt.loadNpmTasks('grunt-githooks');
```
## The "githooks" task
### Overview
In your project's Gruntfile, add a section named `githooks` to the data
object passed into `grunt.initConfig()`.
```js
grunt.initConfig({
githooks: {
options: {
// Task-specific options go here.
},
all: {
options: {
// Target-specific options go here
},
// Hook definitions go there
}
},
})
```
#### Defining a few hooks
Hooks are listed as keys of your target configuration. **Any key other than
`options`** is considered the name of a hook you want to create. The simplest way
to define a hook is to provide a **space-separated list of the tasks you want
the hook to run as the value**.
For example:
```js
grunt.initConfig({
githooks: {
all: {
// Will create `./git/hooks/pre-commit` file which will be used at every commit,
// so that to run the `jshint` and `test:unit` tasks before commit really happen.
'pre-commit': 'jshint test:unit',
}
}
});
```
The plugin warns you if the name matches one of the
[hooks announced in the Git documentation](https://www.kernel.org/pub/software/scm/git/docs/githooks.html).
It will still create the hook, though, in case Git introduces new hooks
in the future.
#### Hook specific options
If you need to override a few options for a given hook only, you can *use an
Object instead of a String*.
The `taskNames` property will then correspond to the tasks you want to run.
Any other key will be merged into the options.
```js
grunt.initConfig({
githooks: {
all: {
options: {
template: 'path/to/a/template'
},
// Will bind the jshint and test:unit tasks
// with the template specified above
'pre-commit': 'jshint test:unit',
// Will bind the bower:install task
// with a specific template
'post-merge': {
taskNames: 'bower:install',
template: 'path/to/another/template'
}
}
}
})
```
#### Working with existing hooks
If you happen to have existing hooks in your hook folder, the plugin *appends
the code launching Grunt* at the end of your hooks. You can also insert marker
comments in your hooks to specify exactly where you want them inserted. Your
existing hook would look something like this:
```js
// Some code run before Grunt starts
// GRUNT-GITHOOKS START // GRUNT-GITHOOKS END
// Some code run after Grunt starts
```
The markers get automatically inserted when the plugin appends code, so hooks
get updated cleanly the next time you run `grunt githooks`.
#### Customising hook output
By default, the plugin generate NodeJS scripts for the hooks. Reasoning behind
this is that creating Shell scripts won't work well for people using Windows.
Plus, NodeJS is already installed as Grunt kinda needs it. However, you're not
tied to it and you can customise the generated script entirely. In case of
a Shell script:
```js
grunt.initConfig({
githooks: {
all: {
options: {
// Customize the hashbang to say 'Shell script'
hashbang: '#!/bin/sh',
// Plugin comes in with a sheel script template already. Handy, innit?
template: './node_modules/grunt-githooks/templates/shell.hb',
// Customize the markers so comments start with #
startMarker: '## LET THE FUN BEGIN',
endMarker: '## PARTY IS OVER'
}
}
}
});
```
In the template, you've got access to the following variables:
- *hook*: `String` with the name of the current hook
- *command*: `String` with the name of the command to run
- *task*: `String` with the name of the tasks to be run
- *args*: `String` with the list of arguments to provide to the task
- *gruntfileDirectory*: Absolute path to the directory containing the Gruntfile
- *preventExit*: Flag telling if the hook should avoid exiting after the grunt task
- *options*: The options provided to the grunt-githooks task to create this hook
#### Extending the plugin
Pretty annoying when you're using a library that's missing the exact extension
point you need to tweak its functionalities? `grunt-githooks` is based on a lot
of small functions and most of them are exposed so you can override them. If you
need feel, free to tinker with the internals (at your own risk though ;)).
Could be something along:
```js
var gruntGithooks = require('grunt-githooks/tasks/githooks');
var originalFunction = gruntGithooks.internals.Hook.prototype.getHookContent;
gruntGithooks.internals.Hook.prototype.getHookContent = function () {
console.log('Loading content of an existing hook');
originalFunction.apply(this, arguments);
};
```
### Options
#### command
Type: `String`
Defaults: `grunt`
The command that will be run by the hook. This has initially been introduced to
allow specifying the full path to Grunt in some specific cases. It can also allow
you to run another command than Grunt if you need.
#### taskNames
Type: `String`
A space separated list of tasks that will be run by the hook.
#### args
Type: `String`
Additional CLI arguments to be passed to the command run by the hook.
#### hashbang
Type: `String`
Defaults: `'#!/usr/bin/env node'`
The hashbang that will be used at the top of the hook script file. If a hook
already exist, the hashbang will be used to check if its ok to append/insert
code in it (to avoid inserting Node code in a Python hook for example).
#### template
Type: `String`
Path to the Handlebars template used to generate the code that will run Grunt
in the hook. Default template is the `node.js.hb` file located in the `templates`
folder of the plugin. It also contains a `shell.hb` file with the template for a
shell script hook.
> **Note**: Handlebars escapes HTML special characters if you use only two curly braces to insert
> a variable in your template. Make sure you use three `{{{my_var}}}` if you need to insert variable
> that contains quotes, chevrons or anything that would be HTML escaped
#### startMarker
Type: `String`
Default: `'// GRUNT-GITHOOKS START'`
#### endMarker
Type: `String`
Default: `'// GRUNT-GITHOOKS END'`
`startMarker` and `endMarker` are markers the plugin use to know where to insert
code if a hook already exist. If the existing hook doesn't have these markers,
the code will simply be appended.
#### preventExit
Type: `Boolean`
Default `false`
By default, the inserted code will exit the process after Grunt has run, using
a -1 exit code if the task(s) failed. If you're inserting the code running Grunt
in the middle of an existing hook, you might want to disable this so any code
after what was inserted by the plugin runs.
#### dest
Type: `String`
Default value: `'.git/hooks'`
This option allows you to choose in which directory the hooks should be generated.
Comes in handy if your Gruntfile is not at the root of your Git project.
## Contributing
In lieu of a formal style-guide, take care to maintain the existing coding style.
Please file a Pull Request along your issues.
* Add unit tests for any new or changed functionality.
* Lint and test your code using [Grunt](http://gruntjs.com/).
* Keep the line length at 80-100 characters per line.
### File a Pull Request
The process actually is quite simple:
1. Please check out your changes on a separate branch named `issue-{$integer}` and commit against that one.
1. When your tests pass and are green, merge to `dev` using `--no-ff` so we have a separate commit for that merge.
1. After the review on `dev`, we can merge to `master`, again using `--no-ff`.
1. The merge to `master` will get tagged. We use the [SemVer standard](http://semver.org), so _no_ leading `v`.
If your PR is successful, you will get added as contributor to the repo. We
trust you after your first PR made it into the repo and you then have access
for further changes, handling issues, etc. So the *important* thing is to add
your name to the `package.json` array of `contributors` when changing or adding
some code for a PR. Please do that in a separate commit.
## Release History
See [Changelog](./CHANGELOG.md) for details or [the Release list](../../releases) - (see [latest](../../releases/latest) for recent updates).