diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 936537ef5..16c7e5901 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -1,96 +1,134 @@ -import { defineConfig } from 'vitepress' +import { defineConfig } from "vitepress"; // https://vitepress.dev/reference/site-config export default defineConfig({ title: "Husky", description: "Git hooks made easy", head: [ - ['link', { rel: 'icon', href: 'data:image/svg+xml,🐶' }], + [ + "link", + { + rel: "icon", + href: 'data:image/svg+xml,🐶', + }, + ], ], - base: '/husky/', + base: "/husky/", themeConfig: { // outline: [2, 3], socialLinks: [ - { icon: 'github', link: 'https://github.com/typicode/husky' }, - { icon: 'twitter', link: 'https://x.com/typicode' } + { icon: "github", link: "https://github.com/typicode/husky" }, + { icon: "twitter", link: "https://x.com/typicode" }, ], // carbonAds: { // code: 'CWYDP53L', // placement: 'typicodegithubio', // }, sidebar: [ - { text: 'Introduction', link: '/' }, - { text: 'Get Started', link: '/get-started' }, - { text: 'How To', link: '/how-to' }, - { text: 'Troubleshoot', link: '/troubleshoot' }, - { text: 'Migrate from v4', link: '/migrate-from-v4' }, - ], - nav: [ - { text: 'Sponsor', link: 'https://github.com/sponsors/typicode' } - ] + { text: "Introduction", link: "/" }, + { text: "Get Started", link: "/get-started" }, + { text: "How To", link: "/how-to" }, + { text: "Troubleshoot", link: "/troubleshoot" }, + { text: "Migrate from v4", link: "/migrate-from-v4" }, + ], + nav: [{ text: "Sponsor", link: "https://github.com/sponsors/typicode" }], }, locales: { root: { - label: 'English', - lang: 'en-US' + label: "English", + lang: "en-US", }, zh: { - label: '简体中文', - lang: 'zh-hans', - description: '使 Git hooks 变得简单', - link: '/zh/', + label: "简体中文", + lang: "zh-hans", + description: "使 Git hooks 变得简单", + link: "/zh/", themeConfig: { sidebar: [ - { text: '简介', link: '/zh/' }, - { text: '快速开始', link: '/zh/get-started' }, - { text: '如何使用', link: '/zh/how-to' }, - { text: '故障排查', link: '/zh/troubleshoot' }, - { text: '从 v4 迁移', link: '/zh/migrate-from-v4' }, + { text: "简介", link: "/zh/" }, + { text: "快速开始", link: "/zh/get-started" }, + { text: "如何使用", link: "/zh/how-to" }, + { text: "故障排查", link: "/zh/troubleshoot" }, + { text: "从 v4 迁移", link: "/zh/migrate-from-v4" }, ], docFooter: { - prev: '上一页', - next: '下一页' + prev: "上一页", + next: "下一页", }, outline: { - label: '页面导航' + label: "页面导航", }, nav: [ { - text: 'v9.0.1', + text: "v9.0.1", items: [ { - text: '更新日志', - link: 'https://github.com/typicode/husky/releases/tag/v9.0.1' - } - ] - } - ] - } + text: "更新日志", + link: "https://github.com/typicode/husky/releases/tag/v9.0.1", + }, + ], + }, + ], + }, }, ru: { - label: 'Русский', - lang: 'ru-RU', - description: 'Git hooks made easy', - link: '/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' }, + { 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: 'Следующая страница' + prev: "Предыдущая страница", + next: "Следующая страница", }, outline: { - label: 'Содержание страницы' + label: "Содержание страницы", }, nav: [ - { text: 'Sponsor', link: 'https://github.com/sponsors/typicode' } - ] - } - } - } -}) + { text: "Sponsor", link: "https://github.com/sponsors/typicode" }, + ], + }, + }, + sp: { + label: "Español", + lang: "es-EC", + description: "Git hooks se vuelven fáciles", + link: "/es/", + themeConfig: { + sidebar: [ + { text: "Introducción", link: "/es/" }, + { text: "Comenzar", link: "/es/get-started" }, + { text: "Cómo hacerlo", link: "/es/how-to" }, + { text: "Solucionar problemas", link: "/es/troubleshoot" }, + { text: "Migrar desde v4", link: "/es/migrate-from-v4" }, + ], + docFooter: { + prev: "Pagina anterior", + next: "Página siguiente", + }, + outline: { + label: "Contenido de la página", + }, + nav: [ + { text: "Sponsor", link: "https://github.com/sponsors/typicode" }, + { + text: "v9.1.5", + items: [ + { + text: "Registro de cambios", + link: "https://github.com/typicode/husky/releases/tag/v9.1.5", + }, + ], + }, + ], + }, + }, + }, +}); diff --git a/docs/es/get-started.md b/docs/es/get-started.md new file mode 100644 index 000000000..31ef85e22 --- /dev/null +++ b/docs/es/get-started.md @@ -0,0 +1,79 @@ +# Comenzar + +## Instalar + +::: code-group + +```shell [npm] +npm install --save-dev husky +``` + +```shell [pnpm] +pnpm add --save-dev husky +``` + +```shell [yarn] +yarn add --dev husky +# Agregue pinst SÓLO si su paquete no es privado +yarn add --dev pinst +``` + +```shell [bun] +bun add --dev husky +``` + +::: + +## `husky init` (recomendado) + +El comando `init` simplifica la configuración de husky en un proyecto. Crea un script `pre-commit` en `.husky/` y actualiza el script `prepare` en `package.json`. Se pueden realizar modificaciones más tarde para que se adapten a su flujo de trabajo. + +::: code-group + +```shell [npm] +npx husky init +``` + +```shell [pnpm] +pnpm exec husky init +``` + +```shell [yarn] +# Debido a advertencias específicas y diferencias con otros administradores de paquetes, +# consulte la sección Cómo hacerlo. +``` + +```shell [bun] +bunx husky init +``` + +::: + +## Pruébalo + +¡Felicitaciones! Has configurado exitosamente tu primer gancho de Git (Git hook) con solo un comando 🎉. Probémoslo: + +```shell +git commit -m "Keep calm and commit" +# El script de prueba se ejecutará cada vez que realices un commit +``` + +## Algunas palabras... + +### Scripting + +Si bien la mayoría de las veces, solo ejecutarás algunos comandos `npm run` o `npx` en tus ganchos (hooks), también puedes crear scripts con el shell POSIX para flujos de trabajo personalizados (custom workflows). + +Por ejemplo, aquí se muestra cómo puedes analizar (lint) tus archivos preparados (staged files) en cada commit con solo dos líneas de código de shell y sin dependencia externa: + +```shell +# .husky/pre-commit +prettier $(git diff --cached --name-only --diff-filter=ACMR | sed 's| |\\ |g') --write --ignore-unknown +git update-index --again +``` + +_Este es un ejemplo básico pero funcional, verifique [lint-staged](https://github.com/lint-staged/lint-staged) si necesitas más._ + +### Deshabilitar ganchos + +Husky no fuerza los ganchos de Git (Git hooks). Se pueden deshabilitar globalmente (`HUSKY=0`) o se pueden habilitar si se desea. Consulta la sección [Cómo hacerlo](cómo hacerlo) para obtener más información y realizar una configuración manual. diff --git a/docs/es/how-to.md b/docs/es/how-to.md new file mode 100644 index 000000000..fa2b1ecf7 --- /dev/null +++ b/docs/es/how-to.md @@ -0,0 +1,335 @@ +# Cómo hacerlo + +## Agregar un nuevo gancho (Hook) + +Agregar un gancho (hook) es tan simple como crear un archivo. Esto se puede lograr usando su editor favorito, un script o un comando echo básico. Por ejemplo, en Linux/macOS: + +```shell +echo "npm test" > .husky/pre-commit +``` + +## Archivos de inicio + +Husky le permite ejecutar comandos locales antes de ejecutar ganchos (hooks). Lee comandos de estos archivos: + +- `$XDG_CONFIG_HOME/husky/init.sh` +- `~/.config/husky/init.sh` +- `~/.huskyrc` (obsoleto (deprecated)) + +En Windows: `C:\Users\yourusername\.config\husky\init.sh` + +## Omitir ganchos de Git (Git Hooks) + +### Para un solo comando + +La mayoría de los comandos de Git incluyen una opción `-n/--no-verify` para omitir ganchos (hooks): + +```sh +git commit -m "..." -n # Skips Git hooks +``` + +Para los comandos sin esta bandera, deshabilite los ganchos (hooks) temporalmente con HUSKY=0: + +```shell +HUSKY=0 git ... # Desactiva temporalmente todos los ganchos de Git (Git hooks) +git ... # Los ganchos (Hooks) se ejecutarán nuevamente +``` + +### Para varios comandos + +Para deshabilitar los ganchos (hooks) durante un período prolongado (por ejemplo, durante la rebase/fusión (merge)): + +```shell +export HUSKY=0 # Deshabilita todos los ganchos (hooks) de Git +git ... +git ... +unset HUSKY # Vuelve a habilitar los ganchos (hooks) +``` + +### Para una GUI o globalmente + +Para deshabilitar los ganchos (hooks) de Git en un cliente GUI o globalmente, modifica la configuración de husky: + +```sh +# ~/.config/husky/init.sh +export HUSKY=0 # Husky no instalará ni ejecutará ganchos (hooks) en tu máquina +``` + +## Servidor CI y Docker + +Para evitar instalar ganchos de Git (Git Hooks) en servidores de CI o en Docker, use `HUSKY=0`. Por ejemplo, en GitHub Actions: + +```yml +# https://docs.github.com/en/actions/learn-github-actions/variables +env: + HUSKY: 0 +``` + +Si instala solo `dependencies` (no `devDependencies`), el script `"prepare": "husky"` puede fallar porque Husky no se instalará. + +Tiene varias soluciones. + +Modifique el script `prepare` para que nunca falle: + +```json +// package.json +"prepare": "husky || true" +``` + +Aún recibirá un mensaje de error `command not found` en su salida que puede ser confuso. Para que sea silencioso, cree `.husky/install.mjs`: + + + +```js +// Omitir la instalación de Husky en producción y CI +if (process.env.NODE_ENV === "production" || process.env.CI === "true") { + process.exit(0); +} +const husky = (await import("husky")).default; +console.log(husky()); +``` + +Luego, úsalo en `prepare`: + +```json +"prepare": "node .husky/install.mjs" +``` + +## Probar Ganchos (Hooks) sin comitear (Committing) + +Para probar un gancho (hook), agregue `exit 1` al script del gancho (hook) para cancelar el comando Git: + +```shell +# .husky/pre-commit + +# Your WIP script +# ... + +exit 1 +``` + +```shell +git commit -m "testing pre-commit code" +# No se creará una confirmación (commit) +``` + +## El proyecto no está en el directorio raíz de Git + +Por razones de seguridad, Husky no se instala en los directorios padres (`../`). Sin embargo, puedes cambiar el directorio en el script `prepare`. + +Considera esta estructura de proyecto: + +``` +. +├── .git/ +├── backend/ # No package.json +└── frontend/ # Package.json con husky +``` + +Configure su script de preparación de la siguiente manera: + +```json +"prepare": "cd .. && husky frontend/.husky" +``` + +En el script de gancho (hook script), cambie el directorio nuevamente al subdirectorio correspondiente: + +```shell +# frontend/.husky/pre-commit +cd frontend +npm test +``` + +## Ganchos (Hooks) que no son de shell + +Para ejecutar scripts que requieren el uso de un lenguaje de script, use el siguiente patrón para cada gancho (hook) en el que aplique: + +(Ejemplo usando el gancho `pre-commit` y NodeJS) + +1. Cree un punto de entrada para el gancho (hook): + +```shell +.husky/pre-commit +``` + +2. En el archivo agregue lo siguiente + +```shell +node .husky/pre-commit.js +``` + +3. en `.husky/pre-commit.js` + +```javascript +// Su código NodeJS +// ... +``` + +## Bash + +Los scripts de hook deben ser compatibles con POSIX para garantizar la mejor compatibilidad, ya que no todos tienen "bash" (por ejemplo, los usuarios de Windows). + +Dicho esto, si su equipo no usa Windows, puede usar Bash de esta manera: + +```shell +# .husky/pre-commit + +bash << EOF +# Put your bash script inside +# ... +EOF +``` + +## Administradores de versiones de Node y GUI + +Si usas ganchos de Git (Git hooks) en GUI con Node instalado a través de un administrador de versiones (como `nvm`, `n`, `fnm`, `asdf`, `volta`, etc.), es posible que te aparezca un error de `comando no encontrado` debido a problemas con la variable de entorno `PATH`. + +### Entender `PATH` y los administradores de versiones + +`PATH` es una variable de entorno que contiene una lista de directorios. Su shell busca comandos en estos directorios. Si no encuentra un comando, recibirá un mensaje de `comando no encontrado`. + +Ejecute `echo $PATH` en un shell para ver su contenido. + +Los administradores de versiones funcionan de la siguiente manera: + +1. Agregar el código de inicialización al archivo de inicio de su shell (`.zshrc`, `.bashrc`, etc.), que se ejecuta cada vez que abre una terminal. +2. Descargar versiones de Node a un directorio en su carpeta de inicio. + +Por ejemplo, si tiene dos versiones de Node: + +```shell +~/version-manager/Node-X/node +~/version-manager/Node-Y/node +``` + +Al abrir una terminal se inicializa el administrador de versiones, que selecciona una versión (por ejemplo, `Node-Y`) y antepone su ruta a `PATH`: + +```shell +echo $PATH +# Salida +~/version-manager/Node-Y/:... +``` + +Ahora, el nodo hace referencia a `Nodo-Y`. Al cambiar a `Nodo-X`, `PATH` cambia en consecuencia: + +```shell +echo $PATH +# Salida +~/version-manager/Node-X/:... +``` + +El problema surge porque las GUI, lanzadas fuera de una terminal, no inicializan el administrador de versiones, lo que deja a `PATH` sin la ruta de instalación de Node. Por lo tanto, los ganchos de Git (Git hooks) desde las GUI suelen fallar. + +### Solución + +Husky obtiene `~/.config/husky/init.sh` antes de cada gancho de Git (Git hooks). Copie aquí el código de inicialización del administrador de versiones para asegurarse de que se ejecute en las GUI. + +Ejemplo con `nvm`: + +```shell +# ~/.config/husky/init.sh +export NVM_DIR="$HOME/.nvm" +[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm +``` + +Como alternativa, si su archivo de inicio de shell es rápido y liviano, consígalo directamente: + +```shell +# ~/.config/husky/init.sh +. ~/.zshrc +``` + +## Configuración manual + +Git necesita ser configurado y husky debe configurar los archivos en `.husky/`. + +Ejecute el comando `husky` una vez en su repositorio. Lo ideal es incluirlo en el script `prepare` en `package.json` para su ejecución automática después de cada instalación (recomendado). + +::: code-group + +```json [npm] +{ + "scripts": { + "prepare": "husky" // [!code hl] + } +} +``` + +```json [pnpm] +{ + "scripts": { + "prepare": "husky" // [!code hl] + } +} +``` + +```json [yarn] +{ + "scripts": { + // Yarn doesn't support prepare script + "postinstall": "husky", + // Include this if publishing to npmjs.com + "prepack": "pinst --disable", + "postpack": "pinst --enable" + } +} +``` + +```json [bun] +{ + "scripts": { + "prepare": "husky" // [!code hl] + } +} +``` + +::: + +Ejecute `prepare` una vez + +::: code-group + +```sh [npm] +npm run prepare +``` + +```sh [pnpm] +pnpm run prepare +``` + +```sh [yarn] +# Yarn doesn't support `prepare` +yarn run postinstall +``` + +```sh [bun] +bun run prepare +``` + +::: + +Cree un archivo `pre-commit` en el directorio `.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 +bun test +``` + +::: diff --git a/docs/es/index.md b/docs/es/index.md new file mode 100644 index 000000000..1552b8e6f --- /dev/null +++ b/docs/es/index.md @@ -0,0 +1,81 @@ +![npm](https://img.shields.io/npm/dm/husky) + +> Hooks nativos de Git ultrarrápidos y modernos + +Husky mejora tus commits y más 🐶 _¡guau!_ + +Automáticamente hace un **lint de tus mensages de commit** **código** y **ejecuta pruebas (test)** al confirmar (commit) o enviar (push). + +Comienza [aquí](/get-started.md). + +## Características + +- Solo `2 kB` (📦 _gzipped_) sin dependencias +- Extremadamente rápido (se ejecuta en `~1ms`) +- Utiliza la nueva característica de Git (`core.hooksPath`) +- Soporta: + - macOS, Linux, Windows + - GUI de Git (Git GUIs), administradores de versiones de Node, directorio de custom hooks, proyectos anidados, monorepositorios (monorepos) + - [Los 13 ganchos de Git (Git hooks) del lado del cliente](https://git-scm.com/docs/githooks) + +Y más: + +- Ganchos específicos de la rama +- Uso de shell POSIX para crear scripts de casos avanzados +- Se adhiere a la organización de ganchos nativa de Git (Git's native hook organization) +- Se alinea con las mejores prácticas de [npm](https://docs.npmjs.com/cli/v10/using-npm/scripts#best-practices) usando el script `prepare` +- Opciones de inclusión/exclusión (Opt-in/opt-out) +- Se puede deshabilitar globalmente +- Mensajes de error amigables con el usuario + +## Patrocinadores (Sponsors) + +Apoya este proyecto convirtiéndote en patrocinador (sponsor) [here](https://github.com/sponsors/typicode) 💖 + +### Patrocinador especial (Special Sponsor) + +

+ +
+ Obtenga recompensas por sus contribuciones de código abierto + +

+ +### GitHub + +

+ + + +

+ +### Colectivo Abierto (Open Collective) + + + + + + + + +## Usado por + +Husky se utiliza en [**más de 1,5 millones de proyectos**](https://github.com/typicode/husky/network/dependents?package_id=UGFja2FnZS0xODQzNTgwNg%3D%3D) en GitHub, incluidos: + +- [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) +- ... + +## Artículos + +- [Por qué Husky ha abandonado la configuración JS convencional](https://blog.typicode.com/posts/husky-git-hooks-javascript-config/) +- [Por qué Husky ya no se instala automáticamente](https://blog.typicode.com/posts/husky-git-hooks-autoinstall/) diff --git a/docs/es/migrate-from-v4.md b/docs/es/migrate-from-v4.md new file mode 100644 index 000000000..6d7f087fe --- /dev/null +++ b/docs/es/migrate-from-v4.md @@ -0,0 +1,65 @@ +# Migrar desde v4 + +Si estabas llamando a los scripts `package.json` usando `npm` o `yarn`, **puedes simplemente copiar tus comandos** desde tu archivo de configuración al gancho (hook) correspondiente: + +Husky v4 + +```json +// package.json +{ + "hooks": { + "pre-commit": "npm test && npm run foo" // [!code hl] + } +} +``` + +Husky v9 + +```shell +# .husky/pre-commit +# Tenga en cuenta que ahora puede tener comandos en varias líneas. +npm test // [!code hl] +npm run foo // [!code hl] +``` + +Si estaba llamando a binarios instalados localmente, **ahora necesita ejecutarlos a través de su administrador de paquetes**: + +::: code-group + +```js [.huskyrc.json (v4)] +{ + "hooks": { + "pre-commit": "jest" + } +} +``` + +```shell [.husky/pre-commit (v9)] +jest +``` + +::: + +La variable de entorno `HUSKY_GIT_PARAMS` ahora se reemplaza por los parámetros nativos `$1`, `$2`, etc. + +::: code-group + +```js [.huskyrc.json (v4)] +{ + "hooks": { + "commit-msg": "commitlint -E HUSKY_GIT_PARAMS" + } +} +``` + +```shell [.husky/commit-msg (v9)] +commitlint --edit $1 +``` + +::: + +Otros cambios en las variables del entorno: + +- `HUSKY_SKIP_HOOKS` se reemplaza por `HUSKY`. +- `HUSKY_SKIP_INSTALL` se reemplaza por `HUSKY`. +- `HUSKY_GIT_PARAMS` se elimina. En su lugar, los parámetros de Git deben usarse directamente en los scripts (por ejemplo, `$1`). diff --git a/docs/es/troubleshoot.md b/docs/es/troubleshoot.md new file mode 100644 index 000000000..1628bfd81 --- /dev/null +++ b/docs/es/troubleshoot.md @@ -0,0 +1,41 @@ +# Solución de problemas + +## Comando no encontrado + +Consulta [Cómo hacerlo](how-to) para obtener soluciones. + +## Los ganchos no se están ejecutando + +1. Verifica que el nombre del archivo sea correcto. Por ejemplo, `precommit` o `pre-commit.sh` son nombres inválidos. Consulta la [documentación](https://git-scm.com/docs/githooks) de los Ganchos de Git (Git hooks ) para conocer los nombres válidos. +2. Ejecuta `git config core.hooksPath` y asegúrate de que apunte a `.husky/_` (o a tu directorio de ganchos (hooks) personalizado). +3. Confirma que tu versión de Git sea superior a `2.9`. + +## `.git/hooks/` no funciona después de la desinstalación + +Si los ganchos (hooks) en `.git/hooks/` no funcionan después de desinstalar `husky`, ejecuta `git config --unset core.hooksPath`. + +## Yarn en Windows + +Los ganchos de Git (Git hooks) pueden fallar con Yarn en Windows usando Git Bash (`stdin no es un tty`). Para los usuarios de Windows, implemente esta solución alternativa (workaround): + +1. Crear `.husky/common.sh`: + +```shell +command_exists () { + command -v "$1" >/dev/null 2>&1 +} + +# Solución alternativa (Workaround) para Windows 10, Git Bash, and Yarn +if command_exists winpty && test -t 1; then + exec < /dev/tty +fi +``` + +2. Obtenga la fuente donde se ejecutan los comandos Yarn: + +```shell +# .husky/pre-commit +. .husky/common.sh + +yarn ... +```