Skip to content

Commit

Permalink
docs: update
Browse files Browse the repository at this point in the history
  • Loading branch information
typicode committed Sep 27, 2023
1 parent d707bb1 commit b40ebc1
Show file tree
Hide file tree
Showing 3 changed files with 46 additions and 126 deletions.
129 changes: 41 additions & 88 deletions docs/getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

Install husky and configure Git hooks

## Setup

::: code-group

```shell [npm]
Expand All @@ -15,8 +17,9 @@ pnpm exec husky
```

```shell [yarn]
yarn add --dev husky
yarn exec husky
yarn add husky --dev
yarn add pinst --dev # ONLY if your package is not private
yarn run husky
```

:::
Expand All @@ -25,81 +28,27 @@ To automatically have Git hooks enabled after install, edit `package.json`

::: code-group

```json [package.json]
```json [npm]
{
"scripts": {
"prepare": "husky" // [!code hl]
}
}
```

:::

Create a `pre-commit` file in `husky/` directory

::: code-group

```shell [.husky/pre-commit]
npm test
```

:::

Make a commit

```shell
git commit -m "Keep calm and commit"
# `npm test` will run every time you commit
```

::: info
Yarn 2+ doesn't support `prepare` lifecycle script, so husky needs to be installed differently. See [Yarn 2+ install](#yarn-2).
:::

::: warning
**Using Yarn to run commands? There's an issue on Windows with Git Bash, see [Yarn on Windows](#yarn-on-windows).**
:::

Uninstall

```shell
npm uninstall husky && git config --unset core.hooksPath
```

## Yarn 2

### Install

1. Install `husky`

```shell
yarn add husky --dev
yarn add pinst --dev # ONLY if your package is not private
```

2. Enable Git hooks

```shell
yarn husky
```

3. To automatically have Git hooks enabled after install, edit `package.json`

::: code-group

```js [package.json private=true]
```json [pnpm]
{
"private": true,
"scripts": {
"postinstall": "husky"
"prepare": "husky" // [!code hl]
}
}
```

```js [package.json private=false]
```json [yarn]
{
"scripts": {
"postinstall": "husky",
// Add this if you're publishing to npmjs.com
"prepack": "pinst --disable",
"postpack": "pinst --enable"
}
Expand All @@ -108,50 +57,54 @@ yarn husky

:::

::: tip
if your package is not private and you're publishing it on a registry like [npmjs.com](https://npmjs.com), you need to disable `postinstall` script using [pinst](https://github.com/typicode/pinst)\*\*. Otherwise, `postinstall` will run when someone installs your package and result in an error.
:::

### Uninstall

Remove `"postinstall": "husky"` from `package.json` and run:

```shell
yarn remove husky && git config --unset core.hooksPath
```

## Automatic (recommended)

`husky-init` is a one-time command to quickly initialize a project with husky.
Create a `pre-commit` file in `husky/` directory

::: code-group

```shell [npm]
npx husky-init
# .husky/pre-commit
npm test
```

```shell [pnpm]
pnpm dlx husky-init
# .husky/pre-commit
pnpm test
```

```shell [yarn]
yarn dlx husky-init --yarn2
# .husky/pre-commit
yarn test
```

:::

`husky-init` will:
Kudos, you've succesfully setup your first Git hook 🎉

1. Add `prepare` script to `package.json`
1. Create a sample `pre-commit` hook that you can edit (by default, `npm test` will run when you commit)
1. Set Git `core.hooksPath` repository option
## Try it

To add another hook, simply create a new file in `.husky/`. For example to add `commit-msg` hook:
Make a commit

:::code-group
```shell
git commit -m "Keep calm and commit"
# test script will run every time you commit
```

```shell [.husky/commit-msg]
npx --no -- commitlint --edit "$1"
## Uninstall

::: code-group

```shell [npm]
npm uninstall husky
git config --unset core.hooksPath
```

```shell [pnpm]
pnpm uninstall husky
git config --unset core.hooksPath
```

```shell [yarn]
yarn remove husky
git config --unset core.hooksPath
```

:::
42 changes: 5 additions & 37 deletions docs/guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,52 +2,41 @@

## Monorepo

It's recommended to add husky in root `package.json`. You can use tools like [lerna](https://github.com/lerna/lerna) and filters to only run scripts in packages that have been changed.
It's recommended to add husky in the root `package.json`.

## Custom directory

If you want to install husky in another directory, for example `.config`, you can pass it to `install` command. For example:

::: code-group

```js [package.json]
```json
{
"scripts": {
"prepare": "husky -d .config/husky"
}
}
```

:::

Another case you may be in is if your `package.json` file and `.git` directory are not at the same level. For example, `project/.git` and `project/front/package.json`.

By design, `husky install` must be run in the same directory as `.git`, but you can change directory during `prepare` script and pass a subdirectory:

::: code-group

```js [package.json]
```json
{
"scripts": {
"prepare": "cd .. && husky -d front/.husky"
}
}
```

:::

In your hooks, you'll also need to change directory:

::: code-group

```shell [.husky/pre-commit]
```shell
# .husky/pre-commit
# ...
cd front
npm test
```

:::

## Bypass hooks

You can bypass `pre-commit` and `commit-msg` hooks using Git `-n/--no-verify` option:
Expand Down Expand Up @@ -153,24 +142,3 @@ exit 1 # Commit will be aborted
```

:::

## Git-flow

If you're using [git-flow](https://github.com/petervanderdoes/gitflow-avh/) you need to ensure your git-flow hooks directory is set to use Husky's (`.husky/_` by default).

```shell
git config gitflow.path.hooks .husky/_
```

::: info

- If you are configuring git-flow _after_ you have installed husky, the git-flow setup process will correctly suggest the .husky directory.
- If you have set a [custom directory](#custom-directory) for husky you need to specify that (ex. `git config gitflow.path.hooks .config/husky/_`)

:::

To **revert** the git-flow hooks directory back to its default you need to reset the config to point to the default Git hooks directory.

```shell
git config gitflow.path.hooks .git/hooks
```
1 change: 0 additions & 1 deletion src/index.ts
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
import cp = require('child_process')
import fs = require('fs')
import p = require('path')
import os = require('os')

// Logger
const l = (msg: string): void => console.log(`husky - ${msg}`)
Expand Down

0 comments on commit b40ebc1

Please sign in to comment.