root
/
husky
mirror of https://github.com/typicode/husky.git
1
0
Fork 0
Code Issues Actions Packages Projects Releases Wiki Activity

chore: vitepress (#1264)

This commit is contained in:
typicode 2023-05-15 23:47:26 +02:00 committed by GitHub
parent 1e52695a93
commit 58da6f6bc0
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 2044 additions and 169 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

33
.github/workflows/deploy.yml vendored Normal file
View File

@ -0,0 +1,33 @@
name: Deploy
on:
workflow_dispatch: {}
push:
branches:
- main
jobs:
deploy:
runs-on: ubuntu-latest
permissions:
pages: write
id-token: write
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- uses: actions/checkout@v3
with:
fetch-depth: 0
- uses: actions/setup-node@v3
with:
node-version: 16
cache: npm
- run: npm ci
- name: Build
run: npm run docs:build
- uses: actions/configure-pages@v2
- uses: actions/upload-pages-artifact@v1
with:
path: docs/.vitepress/dist
- name: Deploy
id: deployment
uses: actions/deploy-pages@v1

2
.gitignore vendored
View File

@ -3,3 +3,5 @@ node_modules
husky-*.tgz
tsconfig.tsbuildinfo
*.log
docs/.vitepress/cache
docs/.vitepress/dist

0
docs/.nojekyll
View File

17
docs/.vitepress/config.ts Normal file
View File

@ -0,0 +1,17 @@
import { defineConfig } from 'vitepress'
// https://vitepress.dev/reference/site-config
export default defineConfig({
title: '🐶 husky',
description: 'Git hooks made easy',
base: '/husky/',
themeConfig: {
socialLinks: [
{ icon: 'github', link: 'https://github.com/typicode/husky' },
],
carbonAds: {
code: 'CWYDP53L',
placement: 'typicodegithubio',
},
},
})

43
docs/index.html
View File

@ -1,43 +0,0 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<title>Husky - Git hooks</title>
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
<meta name="description" content="Modern native Git hooks made easy" />
<meta
name="viewport"
content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0"
/>
<link
rel="stylesheet"
href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css"
/>
<link
rel="icon"
href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><text y='.9em' font-size='90'>🐶</text></svg>"
/>
<style>
.markdown-section {
max-width: 840px;
}
.markdown-section h1 {
margin: 4rem 0 0;
}
.markdown-section h1 + h2 {
margin: 2rem 0 0;
}
</style>
</head>
<body>
<div id="app"></div>
<script>
window.$docsify = {
name: 'husky',
repo: 'https://github.com/typicode/husky',
}
</script>
<script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-bash.min.js"></script>
</body>
</html>

263
docs/README.md → docs/index.md
View File

@ -1,4 +1,12 @@
[![Financial Contributors on Open Collective](https://opencollective.com/husky/all/badge.svg?label=financial+contributors)](https://opencollective.com/husky) [![](https://img.shields.io/npm/dm/husky.svg?style=flat)](https://www.npmjs.org/package/husky) [![Node.js CI](https://github.com/typicode/husky/workflows/Node.js%20CI/badge.svg)](https://github.com/typicode/husky/actions)
---
outline: deep
---
[![Financial Contributors on Open Collective](https://opencollective.com/husky/all/badge.svg?label=financial+contributors)](https://opencollective.com/husky)
[![](https://img.shields.io/npm/dm/husky.svg?style=flat)](https://www.npmjs.org/package/husky)
[![Node.js CI](https://github.com/typicode/husky/workflows/Node.js%20CI/badge.svg)](https://github.com/typicode/husky/actions)
> Modern native git hooks made easy
@ -6,20 +14,20 @@ Husky improves your commits and more 🐶 _woof!_
You can use it to **lint your commit messages**, **run tests**, **lint code**, etc... when you commit or push. Husky supports [all Git hooks](https://git-scm.com/docs/githooks).
# Features
## Features
- Zero dependencies and lightweight (`6 kB`)
- Lightweight with zero dependencies (`6 kB`)
- Powered by modern new Git feature (`core.hooksPath`)
- Follows [npm](https://docs.npmjs.com/cli/v8/using-npm/scripts#best-practices) and [Yarn](https://yarnpkg.com/advanced/lifecycle-scripts#a-note-about-postinstall) best practices regarding autoinstall
- Follows [npm](https://docs.npmjs.com/cli/v8/using-npm/scripts#best-practices) and [Yarn](https://yarnpkg.com/advanced/lifecycle-scripts#a-note-about-postinstall) best practices regarding `autoinstall`
- User-friendly messages
- Optional install
- __Like husky 4, supports__
- **Supports**
- macOS, Linux and Windows
- Git GUIs
- Custom directories
- Monorepos
# Used by
## Widely used
Husky is used by these awesome projects:
@ -45,43 +53,56 @@ Husky is used by these awesome projects:
- [zenorocha/clipboard.js](https://github.com/zenorocha/clipboard.js)
- [NodeBB/NodeBB](https://github.com/NodeBB/NodeBB)
- [ant-design/ant-design](https://github.com/ant-design/ant-design)
- And [__more__](https://github.com/typicode/husky/network/dependents?package_id=UGFja2FnZS0xODQzNTgwNg%3D%3D)
- And [**more than 1.1M projects**](https://github.com/typicode/husky/network/dependents?package_id=UGFja2FnZS0xODQzNTgwNg%3D%3D)
## Articles
### Articles
- [Why husky has dropped conventional JS config](https://blog.typicode.com/husky-git-hooks-javascript-config/)
- [Why husky doesn't autoinstall anymore](https://blog.typicode.com/husky-git-hooks-autoinstall/)
# Usage
## Usage
Already using husky? See [Migrate from 4 to 8](/?id=migrate-from-v4-to-v8).
Already using husky? See [Migrate from 4 to 8](#migrate-from-v4-to-v8).
## Automatic (recommended)
### Automatic (recommended)
`husky-init` is a one-time command to quickly initialize a project with husky.
```shell
npx husky-init && npm install # npm
npx husky-init && yarn # Yarn 1
yarn dlx husky-init --yarn2 && yarn # Yarn 2+
pnpm dlx husky-init && pnpm install # pnpm
::: code-group
```shell [npm]
npx husky-init && npm install
```
It will setup husky, modify `package.json` and create a sample `pre-commit` hook that you can edit. By default, it will run `npm test` when you commit.
```shell [pnpm]
pnpm dlx husky-init && pnpm install
```
To add another hook use `husky add`.
```shell [yarn]
yarn dlx husky-init --yarn2 && yarn
```
For example:
:::
It will:
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. Configure Git hooks path
To add another hook use `husky add`. For example:
```shell
npx husky add .husky/commit-msg 'npx --no -- commitlint --edit "$1"'
```
_For Windows users, if you see the help message when running `npx husky add ...`, try `node node_modules/husky/lib/bin add ...` instead. This isn't an issue with husky code._
::: info
For Windows users, if you see the help message when running `npx husky add ...`, try `node node_modules/husky/lib/bin add ...` instead. This isn't an issue with husky code.
:::
## Manual
### Manual
### Install
#### Install
1. Install `husky`
@ -103,18 +124,23 @@ npm pkg set scripts.prepare="husky install"
You should have:
```js
// package.json
::: code-group
```json [package.json]
{
"scripts": {
"prepare": "husky install"
"prepare": "husky install" // [!code hl]
}
}
```
!> **Yarn 2+ doesn't support `prepare` lifecycle script, so husky needs to be installed differently (this doesn't apply to Yarn 1 though). See [Yarn 2+ install](/?id=yarn-2).**
:::
### Create a hook
::: info
Yarn 2+ doesn't support `prepare` lifecycle script, so husky needs to be installed differently (this doesn't apply to Yarn 1 though). See [Yarn 2+ install](#yarn-2).
:::
#### Create a hook
To add a command to a hook or create a new one, use `husky add <file> [cmd]` (don't forget to run `husky install` before).
@ -131,7 +157,9 @@ git commit -m "Keep calm and commit"
If `npm test` command fails, your commit will be automatically aborted.
!> **Using Yarn to run commands? There's an issue on Windows with Git Bash, see [Yarn on Windows](/?id=yarn-on-windows).**
::: warning
**Using Yarn to run commands? There's an issue on Windows with Git Bash, see [Yarn on Windows](#yarn-on-windows).**
:::
_For Windows users, if you see the help message when running `npx husky add ...`, try `node node_modules/.bin/husky add ...` instead. This isn't an issue with husky code and is fixed in recent versions of npm 8._
@ -141,9 +169,9 @@ _For Windows users, if you see the help message when running `npx husky add ...`
npm uninstall husky && git config --unset core.hooksPath
```
## Yarn 2
### Yarn 2
### Install
#### Install
1. Install `husky`
@ -160,8 +188,9 @@ yarn husky install
3. To automatically have Git hooks enabled after install, edit `package.json`
```js
// package.json
::: code-group
```js [package.json]
{
"private": true, // ← your package is private, you only need postinstall
"scripts": {
@ -170,10 +199,15 @@ yarn husky install
}
```
!> **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.
:::
```js
// package.json
::: 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.
:::
::: code-group
```js [package.json]
{
"private": false, // ← your package is public
"scripts": {
@ -184,7 +218,9 @@ yarn husky install
}
```
### Uninstall
:::
#### Uninstall
Remove `"postinstall": "husky install"` from `package.json` and run:
@ -192,18 +228,19 @@ Remove `"postinstall": "husky install"` from `package.json` and run:
yarn remove husky && git config --unset core.hooksPath
```
# Recipes
## Recipes
## Monorepo
### 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.
## Custom directory
### Custom directory
If you want to install husky in another directory, for example `.config`, you can pass it to `install` command. For example:
```js
// package.json
::: code-group
```js [package.json]
{
"scripts": {
"prepare": "husky install .config/husky"
@ -211,12 +248,15 @@ If you want to install husky in another directory, for example `.config`, you ca
}
```
:::
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:
```js
// package.json
::: code-group
```js [package.json]
{
"scripts": {
"prepare": "cd .. && husky install front/.husky"
@ -224,16 +264,21 @@ By design, `husky install` must be run in the same directory as `.git`, but you
}
```
:::
In your hooks, you'll also need to change directory:
```shell
# .husky/pre-commit
::: code-group
```shell [.husky/pre-commit]
# ...
cd front
npm test
```
## Bypass hooks
:::
### Bypass hooks
You can bypass `pre-commit` and `commit-msg` hooks using Git `-n/--no-verify` option:
@ -247,11 +292,11 @@ For Git commands that don't have a `--no-verify` option, you can use `HUSKY` env
HUSKY=0 git push # yolo!
```
## Disable husky in CI/Docker/Prod
### Disable husky in CI/Docker/Prod
There's no right or wrong way to disable husky in CI/Docker/Prod context and is highly __dependent on your use-case__.
There's no right or wrong way to disable husky in CI/Docker/Prod context and is highly **dependent on your use-case**.
### With npm
#### With npm
If you want to prevent husky from installing completely
@ -266,41 +311,47 @@ npm pkg delete scripts.prepare
npm ci --omit=dev
```
### With a custom script
#### With a custom script
You can create a custom JS script and conditionally require husky and install hooks.
```json
::: code-group
```json [package.json]
"prepare": "node ./prepare.js"
```
```js
// prepare.js
```js [prepare.js]
const isCi = process.env.CI !== undefined
if (!isCi) {
require('husky').install()
}
```
:::
Or make `prepare` script fail silently if husky is not installed:
```json
```json [package.json]
"prepare": "node -e \"try { require('husky').install() } catch (e) {if (e.code !== 'MODULE_NOT_FOUND') throw e}\""
```
### With env variables
#### With env variables
You can set `HUSKY` environment variable to `0` in your CI config file, to disable hooks installation.
Alternatively, most Continuous Integration Servers set a `CI` environment variable. You can use it in your hooks to detect if it's running in a CI.
```shell
# .husky/pre-commit
::: code-group
```shell [.husky/pre-commit]
# ...
[ -n "$CI" ] && exit 0
```
### With is-ci
:::
#### With is-ci
You can also use [is-ci](https://github.com/watson/is-ci) in your `prepare` script to conditionally install husky
@ -308,8 +359,9 @@ You can also use [is-ci](https://github.com/watson/is-ci) in your `prepare` scri
npm install is-ci --save-dev
```
```js
// package.json
::: code-group
```js [package.json]
{
"scripts": {
"prepare": "is-ci || husky install"
@ -317,17 +369,22 @@ npm install is-ci --save-dev
}
```
## Test hooks
:::
### Test hooks
If you want to test a hook, you can add `exit 1` at the end of the script to abort git command.
```shell
# .husky/pre-commit
::: code-group
```shell [.husky/pre-commit]
# ...
exit 1 # Commit will be aborted
```
## Git-flow
:::
### Git-flow
If 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).
@ -338,7 +395,7 @@ git config gitflow.path.hooks .husky
**Note:**
- 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](/?id=custom-directory) for husky you need to specify that (ex. `git config gitflow.path.hooks .config/husky`)
- 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.
@ -346,15 +403,15 @@ To **revert** the git-flow hooks directory back to its default you need to reset
git config gitflow.path.hooks .git/hooks
```
# FAQ
## FAQ
## Does it work on Windows?
### Does it work on Windows?
Yes. When you install Git on Windows, it comes with the necessary software to run shell scripts.
# Troubleshoot
## Troubleshoot
## Command not found
### Command not found
If you're running Git from an app and the command can be found in your terminal, this means that the `PATH` in your app is different from your terminal.
@ -366,8 +423,9 @@ Finally, if you're using a script for managing versions like `nvm`, `n`, `rbenv`
For example, for `nvm` that would be:
```shell
# ~/.huskyrc
::: code-group
```shell [~/.huskyrc]
# This loads nvm.sh, sets the correct PATH before running hook, and ensures the project version of Node
export NVM_DIR="$HOME/.nvm"
@ -377,25 +435,28 @@ export NVM_DIR="$HOME/.nvm"
if [[ -f ".nvmrc" ]]; then
nvm use
fi
```
!> **For some apps (e.g., VS Code), you can resolve this simply by restarting the app. Try this before following any of these steps above!**
:::
## Hooks not running
::: info
For some apps (e.g., VS Code), you can resolve this simply by restarting the app. Try this before following any of these steps above!\*\*
:::
### Hooks not running
1. Ensure that you don't have a typo in your filename. For example, `precommit` or `pre-commit.sh` are invalid names. See Git hooks [documentation](https://git-scm.com/docs/githooks) for valid names.
1. Check that `git config core.hooksPath` returns `.husky` (or your custom hooks directory).
1. Verify that hook files are executable. This is automatically set when using `husky add` command but you can run `chmod +x .husky/<hookname>` to fix that.
1. Check that your version of Git is greater than `2.9`.
## .git/hooks/ not working after uninstall
### .git/hooks/ not working after uninstall
If after uninstalling `husky`, hooks in `.git/hooks/` aren't working. Run `git config --unset core.hooksPath`.
Note: this was done automatically by `npm <7` when uninstalling husky, however `preuninstall` is now unsupported.
## Yarn on Windows
### Yarn on Windows
Git hooks may fail when using Yarn on Windows with Git Bash (`stdin is not a tty`). If you have users on Windows, it's highly recommended to add the following workaround.
@ -422,7 +483,7 @@ fi
yarn ...
```
# Breaking changes
## Breaking changes
Environment variables:
@ -431,18 +492,19 @@ Environment variables:
- `HUSKY_GIT_PARAMS` is removed. Instead Git parameters should be used directly in scripts (e.g. `$1`).
- `PATH` for locally installed tools is not automatically set anymore. You'll need to use your package manager to run them.
# Migrate from v4 to v8
## Migrate from v4 to v8
## husky-4-to-8 CLI
### husky-4-to-8 CLI
See [husky-4-to-8](https://github.com/typicode/husky-4-to-8) CLI to quickly migrate from v4 to v8.
## Package scripts
### Package scripts
If you were calling `package.json` scripts using `npm` or `yarn`, **you can simply copy your commands**:
```js
// .huskyrc.json (v4)
::: code-group
```js [.huskyrc.json (v4)]
{
"hooks": {
"pre-commit": "npm test && npm run foo"
@ -450,19 +512,21 @@ If you were calling `package.json` scripts using `npm` or `yarn`, **you can simp
}
```
```shell
# .husky/pre-commit (v8)
```shell [.husky/commit-msg (v8)]
# ...
npm test
npm run foo
```
## Locally installed binaries
:::
### Locally installed binaries
If you were calling directly locally installed binaries, **you need to run them via your package manager**:
```js
// .huskyrc.json (v4)
::: code-group
```js [.huskyrc.json (v4)]
{
"hooks": {
"pre-commit": "jest"
@ -470,20 +534,22 @@ If you were calling directly locally installed binaries, **you need to run them
}
```
```shell
# .husky/pre-commit (v8)
```shell [.husky/commit-msg (v8)]
# ...
npx --no jest
# or
yarn jest
```
## HUSKY_GIT_PARAMS (i.e. commitlint, ...)
:::
### HUSKY_GIT_PARAMS (i.e. commitlint, ...)
Previous `HUSKY_GIT_PARAMS` environment variable is replaced by native params `$1`, `$2`, etc.
```js
// .huskyrc.json (v4)
::: code-group
```js [.huskyrc.json (v4)]
{
"hooks": {
"commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
@ -491,17 +557,18 @@ Previous `HUSKY_GIT_PARAMS` environment variable is replaced by native params `$
}
```
```shell
# .husky/commit-msg (v8)
```shell [.husky/commit-msg (v8)]
# ...
npx --no -- commitlint --edit $1
# or
yarn commitlint --edit $1
```
# Sponsors
:::
## Companies
## Sponsors
### Companies
Does your company use husky? Ask your manager or marketing team if your company would be interested in supporting this project.
@ -516,7 +583,7 @@ Does your company use husky? Ask your manager or marketing team if your company
<a href="https://opencollective.com/husky/tiers/company/8/website"><img src="https://opencollective.com/husky/tiers/company/8/avatar.svg?avatarHeight=120"></a>
<a href="https://opencollective.com/husky/tiers/company/9/website"><img src="https://opencollective.com/husky/tiers/company/9/avatar.svg?avatarHeight=120"></a>
## Individuals
### Individuals
Find husky helpful? Become a backer and show your appreciation with a monthly donation on [Open Collective](https://opencollective.com/husky). You can also tip with a one-time donation.
@ -524,6 +591,6 @@ Find husky helpful? Become a backer and show your appreciation with a monthly do
GitHub sponsors can be viewed on my [profile](https://github.com/typicode). All past and current Open Collective sponsors can be viewed on [here](https://opencollective.com/husky).
# License
## License
MIT

1845
package-lock.json generated
View File

File diff suppressed because it is too large Load Diff

10
package.json
View File

@ -23,7 +23,10 @@
"test": "sh test/all.sh",
"lint": "eslint src --ext .ts",
"serve": "docsify serve docs",
"prepare": "npm run build && node lib/bin install"
"prepare": "npm run build && node lib/bin install",
"docs:dev": "vitepress dev docs",
"docs:build": "vitepress build docs",
"docs:preview": "vitepress preview docs"
},
"devDependencies": {
"@commitlint/cli": "^17.6.3",
@ -32,9 +35,10 @@
"@types/node": "^20.1.4",
"@typicode/eslint-config": "^1.1.0",
"docsify-cli": "^4.4.4",
"typescript": "^5.0.4"
"typescript": "^5.0.4",
"vitepress": "^1.0.0-alpha.75"
},
"engines": {
"node": ">=16"
}
}
}