# hookshot

> ![](http://i.cloudup.com/i_vGKjtQcY2.png)

Latest version **0.1.0** (published 2014-09-16) · 0 weekly downloads

## Install

```sh
npm install hookshot
pnpm add hookshot
yarn add hookshot
bun add hookshot
```

Provides the command `hookshot`.

## Health

**Score 10/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; low quality score; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.1.0 |
| Published | 2014-09-16 |
| First published | 2013-04-22 |
| Weekly downloads | 0 |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 4 |
| Known vulnerabilities | 0 (+4 in 2 direct dependencies) |
| Install scripts | no |
| Author | Marco Aurelio |
| Maintainers | coreh |

## Links

- npm: https://www.npmjs.com/package/hookshot
- npm.io page: https://npm.io/package/hookshot

## Dependencies (4)

- [express](https://npm.io/package/express.md) ~4.9.0
- [lockfile](https://npm.io/package/lockfile.md) ~1.0.0
- [commander](https://npm.io/package/commander.md) ~2.3.0
- [body-parser](https://npm.io/package/body-parser.md) ~1.8.2

## Recent versions

- 0.1.0 (latest) — 2014-09-16
- 0.0.2 — 2013-05-16
- 0.0.1 — 2013-04-22

## README

# hookshot

![](http://i.cloudup.com/i_vGKjtQcY2.png)

"You found the *hookshot*! It's a spring-loaded chain that you can cast out to hook things."

## Intro

**hookshot** is a tiny library and companion CLI tool for handling [GitHub post-receive hooks](https://help.github.com/articles/post-receive-hooks).

## Examples

### Library

```javascript
var hookshot = require('hookshot');
hookshot('refs/heads/master', 'git pull && make').listen(3000)
```

### CLI Tool

```bash
hookshot -r refs/heads/master 'git pull && make'
```

## Usage

The library exposes a single function, `hookshot()`. When called, this functions returns an express instance configured to handle post-receive hooks from GitHub. You can react to pushes to specific branches by listening to specific events on the returned instance, or by providing optional arguments to the `hookshot()` function.

```javascript
hookshot()
.on('refs/heads/master', 'git pull && make')
.listen(3000)
```

```javascript
hookshot('refs/heads/master', 'git pull && make').listen(3000)
```

### Actions

Actions can either be shell commands or JavaScript functions.

```javascript
hookshot('refs/heads/master', 'git pull && make').listen(3000)
```

```javascript
hookshot('refs/heads/master', function(info) {
  // do something with push info ...
}).listen(3000)
```

### Mounting to existing express servers

**hookshot** can be mounted to a custom route on your existing express server:

```javascript
// ...
app.use('/my-github-hook', hookshot('refs/heads/master', 'git pull && make'));
// ...
```

### Special Events

Special events are fired when branches/tags are created, deleted:

```javascript
hookshot()
.on('create', function(info) {
  console.log('ref ' + info.ref + ' was created.')
})
.on('delete', function(info) {
  console.log('ref ' + info.ref + ' was deleted.')
})
```

The `push` event is fired when a push is made to any ref:

```javascript
hookshot()
.on('push', function(info) {
  console.log('ref ' + info.ref + ' was pushed.')
})
```

Finally, the `hook` event is fired for every post-receive hook that is send by GitHub.

```javascript
hookshot()
.on('push', function(info) {
  console.log('ref ' + info.ref + ' was pushed.')
})
```

### CLI Tool

A companion CLI tool is provided for convenience. To use it, install **hookshot** via npm using the `-g` flag:

```bash
npm install -g hookshot
```

The CLI tool takes as argument a command to execute upon GitHub post-receive hook:

```bash
hookshot 'echo "PUSHED!"'
```

You can optionally specify an HTTP port via the `-p` flag (defaults to 3000) and a ref via the `-r` flag (defaults to all refs):

```bash
hookshot -r refs/heads/master -p 9001 'echo "pushed to master!"'
```

---
_Source: https://npm.io/package/hookshot · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._