From b40ebc12dd45cd4e7a93620a6d15595c91c1ff99 Mon Sep 17 00:00:00 2001 From: typicode Date: Wed, 27 Sep 2023 15:01:21 +0200 Subject: [PATCH] docs: update --- docs/getting-started.md | 129 +++++++++++++--------------------------- docs/guide.md | 42 ++----------- src/index.ts | 1 - 3 files changed, 46 insertions(+), 126 deletions(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index 02294f521..4f50fa792 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -2,6 +2,8 @@ Install husky and configure Git hooks +## Setup + ::: code-group ```shell [npm] @@ -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 ``` ::: @@ -25,7 +28,7 @@ To automatically have Git hooks enabled after install, edit `package.json` ::: code-group -```json [package.json] +```json [npm] { "scripts": { "prepare": "husky" // [!code hl] @@ -33,73 +36,19 @@ To automatically have Git hooks enabled after install, edit `package.json` } ``` -::: - -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" } @@ -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 ``` ::: diff --git a/docs/guide.md b/docs/guide.md index 5600256b5..ff38919ba 100644 --- a/docs/guide.md +++ b/docs/guide.md @@ -2,15 +2,13 @@ ## 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" @@ -18,15 +16,11 @@ 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: -::: code-group - -```js [package.json] +```json { "scripts": { "prepare": "cd .. && husky -d front/.husky" @@ -34,20 +28,15 @@ 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: -::: 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: @@ -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 -``` diff --git a/src/index.ts b/src/index.ts index 664fefb09..9c72eb006 100644 --- a/src/index.ts +++ b/src/index.ts @@ -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}`)