docs: support Russian documentation (#1495)

This commit is contained in:
Oleg Kipchatov
2024-08-24 18:45:25 +02:00
committed by GitHub
parent 32059e73c7
commit f83129fbfa
6 changed files with 617 additions and 0 deletions
+25
View File
@@ -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' }
]
}
}
}
})
+79
View File
@@ -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) для ручной настройки и дополнительной информации.
+326
View File
@@ -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`:
<!-- Поскольку husky может быть не установлен, его необходимо импортировать динамически после проверки prod/CI -->
```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
тест булочки
```
:::
+80
View File
@@ -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) 💖
### Специальный спонсор
<p align="center">
<a href="https://app.tea.xyz/sign-up?r=8L2HWfJB6hs">
<img src="https://github.com/typicode/husky/assets/5502029/1b95c571-0157-48bc-a147-0d8d2fbc1d8a" /><br/>
Получите награды за свой вклад в открытый исходный код
</a>
</p>
### GitHub
<p align="center">
<a href="../sponsorkit/sponsors.svg">
<img src='../sponsorkit/sponsors.svg'/>
</a>
</p>
### Открытый коллектив
<a href="https://opencollective.com/husky/tiers/company/0/website"><img src="https://opencollective.com/husky/tiers/company/0/avatar.svg?avatarHeight=120"></a>
<a href="https://opencollective.com/husky/tiers/company/1/website"><img src="https://opencollective.com/husky/tiers/company/1/avatar.svg?avatarHeight=120"></a>
<a href="https://opencollective.com/husky/tiers/company/2/website"><img src="https://opencollective.com/husky/tiers/company/2/avatar.svg?avatarHeight=120"></a>
<a href="https://opencollective.com/husky/tiers/company/3/website"><img src="https://opencollective.com/husky/tiers/company/3/avatar.svg?avatarHeight=120"></a>
<a href="https://opencollective.com/husky/tiers/company/4/website"><img src="https://opencollective.com/husky/tiers/company/4/avatar.svg?avatarHeight=120"></a>
<a href="https://opencollective.com/husky/tiers/company/5/website"><img src="https://opencollective.com/husky/tiers/company/5/avatar.svg?avatarHeight=120"></a>
## Используется
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/)
+66
View File
@@ -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`).
+41
View File
@@ -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 ...
```