From 04357fdba11b1dd48f0a6f7439b9019b3be0b5f8 Mon Sep 17 00:00:00 2001 From: Oleg Kipchatov <35765711+OlegKipchatov@users.noreply.github.com> Date: Sat, 17 Aug 2024 20:57:31 +0300 Subject: [PATCH 1/2] docs: support ru locale --- docs/ru/get-started.md | 79 +++++++++ docs/ru/how-to.md | 326 +++++++++++++++++++++++++++++++++++++ docs/ru/index.md | 80 +++++++++ docs/ru/migrate-from-v4.md | 66 ++++++++ docs/ru/troubleshoot.md | 41 +++++ 5 files changed, 592 insertions(+) create mode 100644 docs/ru/get-started.md create mode 100644 docs/ru/how-to.md create mode 100644 docs/ru/index.md create mode 100644 docs/ru/migrate-from-v4.md create mode 100644 docs/ru/troubleshoot.md diff --git a/docs/ru/get-started.md b/docs/ru/get-started.md new file mode 100644 index 000000000..658983e3d --- /dev/null +++ b/docs/ru/get-started.md @@ -0,0 +1,79 @@ +# Начало работы + +## Установить + +::: code-group + +```shell [npm] +npm install --save-dev husky +``` + +```shell [pnpm] +pnpm add --save-dev husky +``` + +```shell [yarn] +yarn add --dev husky +# Добавить pinst ТОЛЬКО если ваш пакет не является закрытым +yarn add --dev pinst +``` + +```shell [bun] +bun add --dev husky +``` + +::: + +## `husky init` (рекомендуется) + +Команда `init` упрощает настройку husky в проекте. Она создает скрипт `pre-commit` в `.husky/` и обновляет скрипт `prepare` в `package.json`. Изменения можно внести позже в соответствии с вашим рабочим процессом. + +::: code-group + +```shell [npm] +npx husky init +``` + +```shell [pnpm] +pnpm exec husky init +``` + +```shell [yarn] +# Из-за особых оговорок и различий с другими менеджерами пакетов, +# обратитесь к разделу «Как использовать». +``` + +```shell [bun] +bunx husky init +``` + +::: + +## Попробуйте + +Поздравляем! Вы успешно настроили свой первый Git hook всего одной командой 🎉. Давайте проверим: + +```shell +git commit -m "Keep calm and commit" +# тестовый скрипт будет запускаться каждый раз при коммите +``` + +## Несколько слов... + +### Скриптинг + +Хотя большую часть времени вы просто запускаете несколько команд `npm run` или `npx` в своих хуках, вы также можете записать их с помощью оболочки POSIX для пользовательских рабочих процессов. + +Например, вот как можно линтинговать подготовленные файлы на каждом коммите, используя всего две строки кода оболочки и без внешней зависимости: + +```shell +# .husky/pre-commit +prettier $(git diff --cached --name-only --diff-filter=ACMR | sed 's| |\\ |g') --write --ignore-unknown +git update-index --again +``` + +_Это простой, но рабочий пример, проверьте [lint-staged](https://github.com/lint-staged/lint-staged), если вам нужно больше._ + +### Отключение хуков + +Husky не принудительно использует хуки Git. Его можно отключить глобально (`HUSKY=0`) или включить, если нужно. См. раздел [Как сделать](how-to) для ручной настройки и дополнительной информации. \ No newline at end of file diff --git a/docs/ru/how-to.md b/docs/ru/how-to.md new file mode 100644 index 000000000..1fc807ac3 --- /dev/null +++ b/docs/ru/how-to.md @@ -0,0 +1,326 @@ +# Как использовать + +## Добавление нового хука + +Добавление хука так же просто, как создание файла. Это можно сделать с помощью вашего любимого редактора, скрипта или базовой команды echo. Например, в Linux/macOS: +```shell +echo "npm test" > .husky/pre-commit +``` + +## Файлы запуска + +Husky позволяет выполнять локальные команды перед запуском хуков. Он считывает команды из следующих файлов: + +- `$XDG_CONFIG_HOME/husky/init.sh` +- `~/.config/husky/init.sh` +- `~/.huskyrc` (устарело) + +В Windows: `C:\Users\yourusername\.config\husky\init.sh` + +## Пропуск хуков Git + +### Для одной команды + +Большинство команд Git включают опцию `-n/--no-verify` для пропуска хуков: + +```sh +git commit -m "..." -n # Пропускает хуки Git +``` + +Для команд без этого флага временно отключите хуки с помощью HUSKY=0: + +```shell +HUSKY=0 git ... # Временно отключает все хуки Git +git ... # Хуки снова запустятся +``` + +### Для нескольких команд + +Чтобы отключить хуки для длительный период (например, во время rebase/merge): + +```shell +export HUSKY=0 # Отключает все хуки Git +git ... +git ... +unset HUSKY # Повторно включает хуки +``` + +### Для GUI или глобально + +Чтобы отключить хуки Git в клиенте GUI или глобально, измените конфигурацию husky: + +```sh +# ~/.config/husky/init.sh +export HUSKY=0 # Husky не установит и не запустит хуки на вашей машине +``` + +## CI-сервер и Docker + +Чтобы избежать установки хуков Git на CI-серверах или в Docker, используйте `HUSKY=0`. Например, в GitHub Actions: + +```yml +# https://docs.github.com/en/actions/learn-github-actions/variables +env: +HUSKY: 0 +``` + +Если устанавливается только `dependencies` (не `devDependencies`), скрипт `"prepare": "husky"` может завершиться ошибкой, поскольку Husky не будет установлен. + +У вас есть несколько решений. + +Измените скрипт `prepare`, чтобы он никогда не завершался ошибкой: + +```json +// package.json +"prepare": "husky || true" +``` + +Вы все равно получите сообщение об ошибке `command not found` в выводе, что может сбивать с толку. Чтобы сделать его тихим, создайте `.husky/install.mjs`: + + +```js +// Пропустить установку Husky в production и CI +if (process.env.NODE_ENV === 'production' || process.env.CI === 'true') { + process.exit(0) +} +const husky = (await import('husky')).default +console.log(husky()) +``` + +Затем используйте его в `prepare`: + +```json +"prepare": "node .husky/install.mjs" +``` + +## Тестирование хуков без коммита + +Чтобы протестировать хук, добавьте `exit 1` в скрипт хука, чтобы прервать Git команду: + +```shell +# .husky/pre-commit + +# Ваш скрипт WIP +# ... + +exit 1 +``` + +```shell +git commit -m "testing pre-commit code" +# Коммит не будет создан +``` + +## Проект не в корневом каталоге Git + +Husky не устанавливается в родительские каталоги (`../`) по соображениям безопасности. Однако вы можете изменить каталог в скрипте `prepare`. + +Рассмотрим следующую структуру проекта: + +``` +. +├── .git/ +├── backend/ # Нет package.json +└── frontend/ # Package.json с husky +``` + +Настройте скрипт подготовки следующим образом: + +```json +"prepare": "cd .. && husky frontend/.husky" +``` + +В скрипте хука измените каталог обратно на соответствующий подкаталог: + +```shell +# frontend/.husky/pre-commit +cd frontend +npm test +``` + +## Хуки, не относящиеся к оболочке + +Чтобы запустить скрипты, требующие использования языка сценариев, используйте следующий шаблон для каждого применимого хука: + +(Пример использования хука `pre-commit` и NodeJS) +1. Создайте точку входа для хука: + ```shell + .husky/pre-commit + ``` +2. В файл добавьте следующее + ```shell + node .husky/pre-commit.js + ``` +3. в `.husky/pre-commit.js` + ```javascript + // Ваш код NodeJS + // ... + ``` + +## Bash + +Скрипты хуков должны быть совместимы с POSIX, чтобы обеспечить лучшую совместимость, так как не у всех есть `bash` (например, у пользователей Windows). + +При этом, если ваша команда не использует Windows, вы можете использовать Bash следующим образом: + +```shell +# .husky/pre-commit + +bash << EOF +# Поместите свой скрипт bash внутрь +# ... +EOF +``` + +## Менеджеры версий Node и графические интерфейсы + +Если вы используете хуки Git в графических интерфейсах с Node, установленным через менеджер версий (например, `nvm`, `n`, `fnm`, `asdf`, `volta` и т. д.), вы можете столкнуться с ошибкой `command not found` из-за проблем с переменной среды `PATH`. + +### Понимание `PATH` и менеджеров версий + +`PATH` — это переменная среды, содержащая список каталогов. Ваша оболочка ищет команды в этих каталогах. Если она не находит команду, вы получаете сообщение `command not found`. + +Запустите `echo $PATH` в оболочке, чтобы просмотреть ее содержимое. + +Менеджеры версий работают следующим образом: +1. Добавляют код инициализации в файл запуска оболочки (`.zshrc`, `.bashrc` и т. д.), который запускается каждый раз при открытии терминала. +2. Загружают версии Node в каталог в вашей домашней папке. + +Например, если у вас две версии Node: + +```shell +~/version-manager/Node-X/node +~/version-manager/Node-Y/node +``` + +Открытие терминала инициализирует менеджер версий, который выбирает версию (например, `Node-Y`) и добавляет ее путь к `PATH`: + +```shell +echo $PATH +# Вывод +~/version-manager/Node-Y/:... +``` + +Теперь node ссылается на `Node-Y`. Переключение на `Node-X` соответственно изменяет `PATH`: + +```shell +echo $PATH +# Вывод +/version-manager/Node-X/:... +``` + +Проблема возникает из-за того, что GUI, запущенные вне терминала, не инициализируют менеджер версий, оставляя `PATH` без пути установки Node. Таким образом, хуки Git из GUI часто терпят неудачу. + +### Решение + +Husky создает `~/.config/husky/init.sh` перед каждым хуком Git. Скопируйте сюда код инициализации вашего менеджера версий, чтобы он работал в GUI. + +Пример с `nvm`: + +```shell +# ~/.config/husky/init.sh +export NVM_DIR="$HOME/.nvm" +[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # Это загружает nvm +``` + +В качестве альтернативы, если ваш файл запуска оболочки быстрый и легкий, используйте его напрямую: + +```shell +# ~/.config/husky/init.sh +. ~/.zshrc +``` + +## Ручная настройка + +Git необходимо настроить, а husky необходимо настроить файлы в `.husky/`. + +Запустите команду `husky` один раз в вашем репозитории. В идеале включите ее в скрипт `prepare` в `package.json` для автоматического выполнения после каждой установки (рекомендуется). + +::: code-group + +```json [npm] +{ + "scripts": { + "prepare": "husky" // [!code hl] + } +} +``` + +```json [pnpm] +{ + "scripts": { + "prepare": "husky" // [!code hl] + } +} +``` + +```json [yarn] +{ + "scripts": { + // Yarn не поддерживает скрипт подготовки + "postinstall": "husky", + // Включить это при публикации на npmjs.com + "prepack": "pinst --disable", + "postpack": "pinst --enable" +} +} +``` + +```json [bun] +{ + "scripts": { + "prepare": "husky" // [!code hl] +} +} +``` + +::: + +Запустить `prepare` once: + +::: code-group + +```sh [npm] +npm run prepare +``` + +```sh [pnpm] +pnpm run preparation +``` + +```sh [yarn] +# Yarn не поддерживает `prepare` +yarn run postinstall +``` + +```sh [bun] +bun run preparation +``` + +::: + +Создайте файл `pre-commit` в каталоге `.husky/`: + +::: code-group + +```shell [npm] +# .husky/pre-commit +npm test +``` + +```shell [pnpm] +# .husky/pre-commit +pnpm test +``` + +```shell [yarn] +# .husky/pre-commit +yarn test +``` + +```sh [bun] +# .husky/pre-commit +тест булочки +``` + +::: \ No newline at end of file diff --git a/docs/ru/index.md b/docs/ru/index.md new file mode 100644 index 000000000..25c081b14 --- /dev/null +++ b/docs/ru/index.md @@ -0,0 +1,80 @@ +![npm](https://img.shields.io/npm/dm/husky) + +> Сверхбыстрые современные собственные хуки git + +Husky улучшает ваши коммиты и многое другое 🐶 _woof!_ + +Автоматически **линтует ваши сообщения коммитов**, **код** и **запускает тесты** при коммите или отправке. + +Начните [здесь](/get-started.md). + +## Возможности + +- Всего `2 КБ` (📦 _gzipped_) без зависимостей +- Очень быстрый (запускается за `~1 мс`) +- Использует новую функцию Git (`core.hooksPath`) +- Поддерживает: + - macOS, Linux, Windows + - Git GUI, менеджеры версий Node, каталог пользовательских хуков, вложенные проекты, монорепозитории + - [Все 13 клиентских хуков Git](https://git-scm.com/docs/githooks) + +И многое другое: +- Хуки, специфичные для веток +- Используйте оболочку POSIX для скриптов сложных случаев +- Соответствует собственной организации хуков Git +- Соответствует лучшим практикам [npm](https://docs.npmjs.com/cli/v10/using-npm/scripts#best-practices) с использованием скрипта `prepare` +- Параметры согласия/отказа +- Может быть глобально отключено +- Удобные сообщения об ошибках + +## Спонсоры + +Поддержите этот проект, став спонсором [здесь](https://github.com/sponsors/typicode) 💖 + +### Специальный спонсор + +

+ +
+ Получите награды за свой вклад в открытый исходный код + +

+ +### GitHub + +

+ + + +

+ +### Открытый коллектив + + + + + + + + +## Используется + +Husky используется в [**более 1,5 млн проектов**](https://github.com/typicode/husky/network/dependents?package_id=UGFja2FnZS0xODQzNTgwNg%3D%3D) на GitHub, включая: + +- [vercel/next.js](https://github.com/vercel/next.js) +- [vercel/hyper](https://github.com/vercel/hyper) +- [webpack/webpack](https://github.com/webpack/webpack) +- [angular/angular](https://github.com/angular/angular) +- [facebook/docusaurus](https://github.com/facebook/docusaurus) +- [microsoft/vscode](https://github.com/microsoft/vscode) +- [11ty/eleventy](https://github.com/11ty/eleventy) +- [stylelint/stylelint](https://github.com/stylelint/stylelint) +- [colinhacks/zod](https://github.com/colinhacks/zod) +- [rollup/rollup](https://github.com/rollup/rollup) +- [tinyhttp/tinyhttp](https://github.com/tinyhttp/tinyhttp) +- ... + +## Статьи + +- [Почему husky отказался от обычного JS config](https://blog.typicode.com/posts/husky-git-hooks-javascript-config/) +- [Почему husky больше не устанавливается автоматически](https://blog.typicode.com/posts/husky-git-hooks-autoinstall/) \ No newline at end of file diff --git a/docs/ru/migrate-from-v4.md b/docs/ru/migrate-from-v4.md new file mode 100644 index 000000000..b240269b1 --- /dev/null +++ b/docs/ru/migrate-from-v4.md @@ -0,0 +1,66 @@ +# Переход с v4 + +Если вы вызывали скрипты `package.json` с помощью `npm` или `yarn`, **вы можете просто скопировать свои команды** из файла конфигурации в соответствующий хук: + +Husky v4 + +```json +// package.json +{ + "hooks": { + "pre-commit": "npm test && npm run foo" // [!code hl] + } +} +``` + +Husky v9 + +```shell +# .husky/pre-commit +# Обратите внимание, что теперь вы можете иметь команды в нескольких строках +npm test // [!code hl] +npm run foo // [!code hl] +``` + +Если вы вызывали локально установленные двоичные файлы, **теперь вам нужно запустить их через менеджер пакетов**: + +::: code-group + +```js [.huskyrc.json (v4)] +{ + "hooks": { + "pre-commit": "jest" + } +} +``` + +```shell [.husky/pre-commit (v9)] +jest +``` + +::: + +Переменная окружения `HUSKY_GIT_PARAMS` теперь заменена на собственные параметры `$1`, `$2` и т. д. + +::: code-group + +```js [.huskyrc.json (v4)] +{ + "hooks": { + "commit-msg": "commitlint -E HUSKY_GIT_PARAMS" + } +} +``` + +```shell [.husky/commit-msg (v9)] +commitlint --edit $1 +``` + +::: + +Другие изменения переменных окружения: + +- `HUSKY_SKIP_HOOKS` заменен на `HUSKY`. + +- `HUSKY_SKIP_INSTALL` заменен на `HUSKY`. +- `HUSKY_GIT_PARAMS` удален. Вместо этого параметры Git следует использовать непосредственно в скриптах (например, `$1`). \ No newline at end of file diff --git a/docs/ru/troubleshoot.md b/docs/ru/troubleshoot.md new file mode 100644 index 000000000..84847607b --- /dev/null +++ b/docs/ru/troubleshoot.md @@ -0,0 +1,41 @@ +# Устранение неполадок + +## Команда не найдена （Command not found） + +См. [Как сделать](how-to) для решений. + +## Хуки не работают + +1. Проверьте правильность имени файла. Например, `precommit` или `pre-commit.sh` — недопустимые имена. Обратитесь к [документации] Git hooks (https://git-scm.com/docs/githooks) для допустимых имен. +2. Запустите `git config core.hooksPath` и убедитесь, что он указывает на `.husky/_` (или на ваш пользовательский каталог hooks). +1. Убедитесь, что версия Git выше `2.9`. + +## `.git/hooks/` не работает после удаления + +Если хуки в `.git/hooks/` не работают после удаления `husky`, выполните `git config --unset core.hooksPath`. + +## Yarn в Windows + +Git-хуки могут не работать с Yarn в Windows с использованием Git Bash (`stdin не является tty`). Для пользователей Windows реализуйте этот обходной путь: + +1. Создайте `.husky/common.sh`: + +```shell +command_exists () { + command -v "$1" >/dev/null 2>&1 +} + +# Обходной путь для Windows 10, Git Bash и Yarn +if command_exists winpty && test -t 1; then + exec < /dev/tty +fi +``` + +2. Укажите его там, где выполняются команды Yarn: + +```shell +# .husky/pre-commit +. .husky/common.sh + +yarn ... +``` \ No newline at end of file From 54d32120601ab5e55edacb8e652e8038da702012 Mon Sep 17 00:00:00 2001 From: Oleg Kipchatov <35765711+OlegKipchatov@users.noreply.github.com> Date: Sat, 17 Aug 2024 20:59:58 +0300 Subject: [PATCH 2/2] docs: add ru locale to docs config --- docs/.vitepress/config.mts | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 734ae5870..936537ef5 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -66,6 +66,31 @@ export default defineConfig({ } ] } + }, + ru: { + label: 'Русский', + lang: 'ru-RU', + description: 'Git hooks made easy', + link: '/ru/', + themeConfig: { + sidebar: [ + { text: 'Введение', link: '/ru/' }, + { text: 'Начало работы', link: '/ru/get-started' }, + { text: 'Как использовать', link: '/ru/how-to' }, + { text: 'Устранение неполадок', link: '/ru/troubleshoot' }, + { text: 'Миграция с v4', link: '/ru/migrate-from-v4' }, + ], + docFooter: { + prev: 'Предыдущая страница', + next: 'Следующая страница' + }, + outline: { + label: 'Содержание страницы' + }, + nav: [ + { text: 'Sponsor', link: 'https://github.com/sponsors/typicode' } + ] + } } } })