Git

Git - Reglas y Convenciones

---

1. Filosofía

1. Commits atómicos — Un commit = un cambio lógico. Commits pequeños, descriptivos y revisables.
2. Historia limpia — Preferir rebase sobre merge en ramas locales. Sin commits de WIP, merge bubbles innecesarias ni mensajes vacíos.
3. Ramas efímeras — Las ramas de feature/bugfix viven lo justo para completar el trabajo y se eliminan al mergear.
4. Conventional Commits — Estándar obligatorio para mensajes. Permite generar changelogs, versionado semántico y releases automatizados.
5. Progressive exposure — El código se expone al equipo vía PR con code review. Nunca se pushea directamente a main o develop.

---

2. Versión Mínima

Tecnología	Versión Mínima
Git	2.30+

---

3. Instalación y Configuración Inicial

Config global

git config --global user.name "Tu Nombre"
git config --global user.email "[email protected]"
git config --global init.defaultBranch main
git config --global core.autocrlf input      # macOS/Linux
git config --global core.autocrlf true       # Windows
git config --global pull.rebase true
git config --global fetch.prune true

Alias útiles

git config --global alias.lg "log --oneline --graph --decorate --all"
git config --global alias.ci "commit"
git config --global alias.co "checkout"
git config --global alias.br "branch"
git config --global alias.st "status"
git config --global alias.undo "reset HEAD~1 --soft"
git config --global alias.amend "commit --amend --no-edit"
git config --global alias.unstage "restore --staged"
git config --global alias.discard "restore"
git config --global alias.last "log -1 HEAD"

.gitconfig completo recomendado

[user]
  name = Tu Nombre
  email = [email protected]
[init]
  defaultBranch = main
[core]
  autocrlf = input
  editor = code --wait
[pull]
  rebase = true
[fetch]
  prune = true
[merge]
  tool = vscode
[diff]
  tool = vscode
[alias]
  lg = log --oneline --graph --decorate --all
  ci = commit
  co = checkout
  br = branch
  st = status
  undo = reset HEAD~1 --soft
  amend = commit --amend --no-edit
  unstage = restore --staged
  discard = restore
  last = log -1 HEAD

---

4. Branching Strategy

Ramas Principales

Rama	Propósito
main	Producción, siempre estable
develop	Integración, features se mergean aquí

Ramas de Soporte

Rama	Base	Merge hacia	Propósito
feature/<name>	develop	develop	Nueva funcionalidad
bugfix/<name>	develop	develop	Corrección en desarrollo
hotfix/<name>	main	main+develop	Corrección urgente en producción
release/<name>	develop	main+develop	Preparación de release

Convención de Nombres

feature/<issue-id>-<breve-descripcion>
bugfix/<issue-id>-<breve-descripcion>
hotfix/<issue-id>-<breve-descripcion>
release/v<version>

Ejemplos

feature/42-add-user-auth
bugfix/53-fix-login-redirect
hotfix/58-patch-security-vuln
release/v1.2.0

---

5. Commits

Formato (Conventional Commits)

<tipo>(<scope opcional>): <descripción>

<cuerpo opcional>

<footer opcional>

Tipos

Tipo	Uso
feat	Nueva funcionalidad
fix	Corrección de bug
docs	Documentación
style	Formato, linting, whitespace (no cambia lógica)
refactor	Refactor sin cambiar funcionalidad
perf	Mejora de rendimiento
test	Tests nuevos o actualizados
chore	Build, CI, tooling
revert	Revertir un cambio

Breaking Changes

feat(api)!: change user endpoint response format

BREAKING CHANGE: The /api/users endpoint now returns { data: [...] }
instead of the previous flat array format.

Ejemplos Commits

feat(auth): add login form validation

fix(api): handle 404 when user not found

docs(readme): update installation instructions

refactor: extract date formatting to utils

chore: update eslint config to v9

Reglas

• Inglés obligatorio para nombres y mensajes
• Descripción: presente imperativo, sin punto final
• Cuerpo: explicar el qué y por qué, no el cómo
• Footer: referenciar issues (Closes #42, Fixes #53)
• Commits atómicos: un cambio lógico por commit

# ❌ Malo
fix stuff
update
WIP
asdf

# ✅ Bueno
feat(api): add pagination to user list
Closes #42

Firmado de Commits (GPG)

# Generar clave GPG
gpg --full-generate-key

# Configurar Git
git config --global user.signingkey <KEY_ID>
git config --global commit.gpgsign true

# Firmar commit
git commit -S -m "feat: add secure endpoint"

# Verificar firma
git log --show-signature -1

---

6. Pull Requests

Título

Mismo formato que commits:

feat(auth): add login form validation

Descripción

## Descripción

<!-- Qué hace este PR, por qué es necesario -->

## Cambios

- [ ] Feature
- [ ] Bugfix
- [ ] Refactor
- [ ] Tests
- [ ] Documentación

## Cómo probar

1. Ir a /login
2. Ingresar credenciales inválidas
3. Ver error en pantalla

## Screenshots

<!-- Si aplica -->

## Closes

Closes #42

Checklist antes del PR

• Código sigue convenciones del proyecto
• Tests pasan localmente (pnpm test o npm test)
• Linter pasa (pnpm lint o npm run lint)
• Sin console.log / debugger
• Sin código comentado
• Documentación actualizada si aplica
• Sin merge conflicts con rama destino

Code Review

✅ Aprobar cuando:
- Código funciona correctamente
- Sigue convenciones del proyecto
- Tests cubren el cambio
- No hay problemas de seguridad/performance

❌ Solicitar cambios cuando:
- Hay bugs o edge cases no cubiertos
- No sigue convenciones del proyecto
- Falta documentación
- El enfoque es incorrecto

---

7. Merge vs Rebase vs Squash

Estrategia	Cuándo usarla
Merge	Rama compartida, preservar historial completo
Rebase	Rama local/feature, historial lineal
Squash	PR pequeño, commits de WIP que no aportan valor solos

Merge (rama compartida)

git checkout develop
git merge --no-ff feature/42-add-user-auth
# --no-ff fuerza un commit de merge aunque sea fast-forward

Rebase (rama local)

git checkout feature/42-add-user-auth
git rebase develop
# Re-escribe commits sobre la punta de develop

Rebase interactivo

git rebase -i HEAD~4
# Comandos disponibles:
# pick    = usar commit tal cual
# reword  = cambiar mensaje
# edit    = detener para enmendar contenido
# squash  = fusionar con commit anterior
# fixup   = fusionar sin conservar mensaje
# drop    = eliminar commit

Squash (PR final)

# Opción 1: squash merge en GitHub/GitLab
# Opción 2: local antes de mergear
git rebase -i HEAD~3
# Marcar todos como 'squash' excepto el primero

---

8. Flujo de Trabajo

Feature

git checkout develop
git pull origin develop
git checkout -b feature/42-add-user-auth
# ... trabajar en pequeños commits ...
git add .
git commit -m "feat(auth): add login form"
git add .
git commit -m "feat(auth): add validation"
git push origin feature/42-add-user-auth
# Crear PR en GitHub

Hotfix

git checkout main
git pull origin main
git checkout -b hotfix/58-patch-security-vuln
# ... corregir ...
git commit -m "fix: patch XSS vulnerability in search input"
git push origin hotfix/58-patch-security-vuln
# PR directo a main
# Luego mergear main a develop

Release

git checkout develop
git checkout -b release/v1.2.0
# ... ajustes finales, bump version ...
git commit -m "chore: bump version to 1.2.0"
git checkout main
git merge --no-ff release/v1.2.0
git tag -a v1.2.0 -m "Release v1.2.0"
git push origin main --tags
git checkout develop
git merge --no-ff release/v1.2.0
git branch -d release/v1.2.0

Sincronizar feature con develop

# Opción: rebase
git checkout feature/42-add-user-auth
git fetch origin
git rebase origin/develop

# Opción: merge (equipos grandes)
git merge origin/develop

---

9. .gitignore

Patrones Esenciales

# Dependencias
node_modules/
.pnp
.pnp.js

# Build
dist/
build/
.next/
out/
.cache/

# IDE
.vscode/
.idea/
*.swp
*.swo
*~

# OS
.DS_Store
Thumbs.db

# Env
.env
.env.local
.env.*.local

# Logs
*.log
npm-debug.log*

# Testing
coverage/
.vitest/
__snapshots__/

# Temp
*.tmp
*.temp
*.tsbuildinfo

# Docker
.docker/

---

10. Tags y Versionado Semántico

SemVer

MAJOR.MINOR.PATCH

MAJOR: cambios incompatibles (breaking changes)
MINOR: nuevas funcionalidades (backward compatible)
PATCH: bug fixes (backward compatible)

Crear tags

# Ligero (solo puntero)
git tag v1.2.0

# Anotado (recomendado - incluye metadata)
git tag -a v1.2.0 -m "Release v1.2.0"

# Firmado
git tag -s v1.2.0 -m "Release v1.2.0"

Publicar tags

git push origin v1.2.0
git push origin --tags  # Todos los tags

Navegar tags

git tag -l "v1.*"              # Listar tags que coinciden
git checkout v1.2.0            # Ir a tag específico
git describe --tags            # Tag más cercano desde HEAD

---

11. Git Hooks

Pre-commit hook

#!/bin/sh
# .git/hooks/pre-commit

# Evitar commits a ramas protegidas
branch=$(git symbolic-ref HEAD | sed 's|refs/heads/||')
if [ "$branch" = "main" ] || [ "$branch" = "develop" ]; then
  echo "❌ No puedes commitear directamente a $branch"
  exit 1
fi

# Verificar que no haya console.log
if git diff --cached --name-only | xargs grep -l "console\.log" 2>/dev/null; then
  echo "❌ Se encontró console.log en los archivos staged"
  exit 1
fi

commit-msg hook (validar Conventional Commits)

#!/bin/sh
# .git/hooks/commit-msg

commit_msg=$(cat "$1")
pattern="^(feat|fix|docs|style|refactor|perf|test|chore|revert)(\(.+\))?!?:\ .{1,}"

if ! echo "$commit_msg" | grep -qE "$pattern"; then
  echo "❌ El mensaje de commit no sigue Conventional Commits"
  echo "Formato: <tipo>(<scope>): <descripción>"
  echo "Ejemplo: feat(auth): add login form"
  exit 1
fi

Husky + lint-staged (recomendado)

pnpm add -D husky lint-staged

# package.json
{
  "lint-staged": {
    "*.{js,ts,tsx}": ["eslint --fix", "prettier --write"],
    "*.css": ["prettier --write"]
  }
}

# .husky/pre-commit
npx lint-staged

---

12. Comandos Avanzados

Stash

git stash push -m "WIP: login form validation"    # Guardar cambios
git stash list                                      # Listar stashes
git stash pop                                       # Recuperar + eliminar
git stash apply stash@{2}                           # Recuperar sin eliminar
git stash drop stash@{2}                            # Eliminar stash específico
git stash clear                                     # Eliminar todos
git stash branch feature/new-branch                 # Crear rama desde stash

Cherry-pick

# Aplicar un commit específico a la rama actual
git cherry-pick abc1234

# Aplicar múltiples commits
git cherry-pick abc1234 def5678

# Sin commitear (solo aplicar cambios)
git cherry-pick -n abc1234

Reflog (recuperación de desastres)

git reflog                    # Ver historial de movimientos de HEAD
git reflog show feature/42    # Reflog de una rama específica

# Recuperar commit "perdido" después de un reset
git reflog                    # Encontrar el hash
git cherry-pick <hash>        # Aplicarlo de nuevo

Bisect (debugging binario)

# Iniciar búsqueda
git bisect start
git bisect bad               # Commit actual es malo
git bisect good v1.0.0       # Tag/commit donde funcionaba

# Git checkout automático, probar en cada paso:
# - Si el bug existe: git bisect bad
# - Si el bug no existe: git bisect good
# Repetir hasta encontrar el commit culpable

git bisect reset             # Salir del modo bisect

# Automatizado
git bisect start HEAD v1.0.0
git bisect run npm test      # Corre test automáticamente
git bisect reset

Worktrees

# Trabajar en múltiples ramas simultáneamente
git worktree add ../project-feature feature/42
git worktree add ../project-hotfix hotfix/58

# Listar worktrees
git worktree list

# Eliminar
git worktree remove ../project-feature

Submodules

# Agregar submódulo
git submodule add https://github.com/user/shared-lib.git libs/shared

# Clonar repo con submódulos
git clone --recurse-submodules <url>

# Actualizar submódulos
git submodule update --init --recursive

# Pull con submódulos
git pull --recurse-submodules

Git LFS

# Instalar
git lfs install

# Trackear tipos de archivo
git lfs track "*.psd"
git lfs track "*.zip"
git lfs track "*.mp4"

# Ver archivos tracked
git lfs ls-files

---

13. Integración con GitHub / GitLab

GitHub CLI

# Autenticación
gh auth login

# Crear PR desde terminal
gh pr create --title "feat(auth): add login form" --body "Closes #42"

# Ver PRs
gh pr list
gh pr checkout 42
gh pr view 42

# Mergear PR
gh pr merge 42 --squash

# ⚠️ Mergear o cerrar un PR (`gh pr merge`, `gh pr close`, `gh pr review --approve`)
# requiere autorización explícita del usuario. Nunca ejecutarlo sin confirmación.

GitHub Actions (CI básico)

# .github/workflows/ci.yml
name: CI
on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: "pnpm"
      - run: pnpm install --frozen-lockfile
      - run: pnpm lint
      - run: pnpm test

Commit Status Checks

# Desde GitHub CLI
gh pr checks 42 --watch

# Bloquear PR si checks fallan (configurar en GitHub settings)
# Settings > Branches > Add rule > Require status checks

---

14. Solución de Problemas Comunes

# Commitear en la rama equivocada
git log --oneline -1              # Verificar último commit
git reset HEAD~1 --soft           # Deshacer commit (cambios en staging)
git stash                         # Guardar cambios
git checkout develop              # Ir a la rama correcta
git stash pop                     # Recuperar cambios

# Mensaje de commit incorrecto
git commit --amend -m "feat: correct message"

# Agregar archivo olvidado al último commit
git add archivo-olvidado.js
git commit --amend --no-edit

# Conflictos de merge
git merge feature/42
# ... resolver conflictos manualmente ...
git add .
git commit --no-edit

# Push rechazado (fueron push intermedias)
git fetch origin
git rebase origin/develop
git push origin feature/42 --force-with-lease

---

15. Prohibiciones

• ❌ NO hacer commit directamente a main o develop
• ❌ No usar git push --force en ramas compartidas (usar --force-with-lease)
• ❌ No commits gigantes (+200 líneas sin justificación)
• ❌ No mensajes de commit vacíos o sin sentido
• ❌ NO mergear PR sin autorización explícita del usuario
• ❌ NO cerrar PR sin autorización explícita del usuario
• ❌ NO auto-aprobar un PR (approve) sin autorización explícita del usuario
• ❌ No dejar WIP o fix en commits finales
• ❌ No ignorar .gitignore (no commitees node_modules, .env, dist/)
• ❌ No usar git commit --no-verify salvo emergencia justificada
• ❌ No pushear .env o secrets
• ❌ No hacer rebase en ramas compartidas con otros developers
• ❌ No borrar tags sin consenso del equipo

---

16. Workflow con Permiso del Usuario

Nunca ejecutes un comando git ni una acción sobre PR (merge, cierre, approve) sin permiso explícito del usuario. Sigue este workflow:

Paso a paso

1. Explicar plan
   → "Voy a commitear los cambios en SKILL.md y ../git/SKILL.md"
   → "Mensaje: feat: add execution permission constraints"

2. Mostrar evidencia
   → "Mensaje; En el archivo.ts:1-10 cambios realizados"
   → Mostrar el comando exacto que se va a ejecutar

3. Pedir confirmación
   → "¿Ejecuto? git add SKILL.md skills/git/SKILL.md && git commit -m 'feat: add execution permission constraints'"

4. Solo entonces ejecutar
   → Si el usuario confirma, ejecutar
   → Si el usuario no confirma, detenerse y esperar instrucciones

Ejemplo Workflow

$ git status
modified:   SKILL.md
modified:   skills/git/SKILL.md

$ git diff SKILL.md
+ | Commit / push | **NO hacer commit o push sin permiso explícito del usuario** |

¿Ejecuto?: git add SKILL.md skills/git/SKILL.md && git commit -m "feat: add execution permission constraints"
→ [usuario responde sí/no]

Reglas Workflow

1. Nunca ejecutar git add, git commit, git push sin permiso del usuario.
2. Nunca hacer merge, cierre o approve de un PR sin permiso explícito del usuario.
3. Siempre mostrar el comando exacto que se va a ejecutar antes de pedir confirmación
4. Siempre esperar respuesta explícita del usuario (sí/no)
5. Nunca asumir consentimiento por silencio
6. Nunca encadenar comandos sin permiso (ej: git add . && git commit sin pasar por pasos 1-3)
7. El "approval" de un agente o subagente NO cuenta como autorización — la autorización solo la da el usuario humano de forma explícita.

---

17. Referencias

Nota: Esta skill no depende de otras skills. Nota: Para linting y pre-commit hooks, ver Linting

---

Última actualización: 2026-07