Git para Equipos: Workflows, Problemas Comunes y Soluciones

📝 El Recordatorio Inicial

Antes de nada, aquí está el comando que deberías ejecutar cuando trabajas en un equipo y necesitas actualizar tu rama local con los últimos cambios:

git fetch --all
git branch -a
git checkout develop
git status  # Si hay cambios → stash
git stash   # Solo si es necesario
git pull origin develop
git stash pop  # Si hiciste stash

Este flujo básico te ahorrará muchos headaches. Pero vamos más allá.

🧠 Por Qué Git es Complicado en Equipo

Trabajar solo con Git es fácil. Nadie más está tocando tu código, no hay conflictos, haces lo que quieres. Pero cuando múltiples personas trabajan en el mismo proyecto, las cosas se complican:

Dos personas editan el mismo archivo
Alguien hace push de cambios que rompen la build
La rama principal tiene cambios que no tienes
Conflicts aparecen de la nada
Alguien hizo git push --force y borraste trabajo de otros

Vamos a ver cómo evitar estos problemas y mantener un workflow saludable.

🔄 Modelos de Workflow en Equipo

1. Git Flow (Para proyectos con releases formales)

Estructura de ramas:

main - código en producción
develop - rama de integración
feature/* - nuevas features
release/* - preparación de releases
hotfix/* - fixes urgentes en producción

Flujo típico:

# Empezar una nueva feature
git checkout develop
git pull origin develop
git checkout -b feature/nueva-funcionalidad

# Trabajar, hacer commits...
git add .
git commit -m "feat: añade nueva funcionalidad"

# Merge cuando está lista
git checkout develop
git merge feature/nueva-funcionalidad
git push origin develop

Cuándo usarlo:

Proyectos con ciclos de release definidos
Equipos que necesitan control estricto sobre qué entra en producción
Software que requiere versionado formal

2. GitHub Flow (Más simple, para deploy continuo)

Estructura de ramas:

main - siempre desplegable
feature/* o fix/* - ramas de trabajo
Pull Requests para todo

Flujo típico:

# Crear rama desde main
git checkout main
git pull origin main
git checkout -b fix/arreglo-bug

# Trabajar y hacer PR
git add .
git commit -m "fix: arregla bug en login"

# Push y crear PR desde GitHub
git push origin fix/arreglo-bug

Cuándo usarlo:

Deploy continuo es posible
Equipos pequeños o medianos
Proyectos web/app que pueden desplegarse frecuentemente

3. Trunk-Based Development (Para equipos de entrega continua)

Concepto:

Ramas de vida muy corta (menos de 2 días)
Commits directos a main o ramas de duración muy corta
Feature flags para incomplete features

Cuándo usarlo:

Equipos muy maduros
Cultura de CI/CD fuerte
Deployment automatizado y tests extensivos

🚨 Problemas Comunes y Soluciones

Problema 1: Conflictos de Merge Que Parecen Imposibles

El escenario: Haces git pull y de repente tienes 50 conflictos. En archivos que ni tocaste. ¿Qué pasó?

Por qué ocurre:

Tú:           A --- C --- E (tu rama)
              \         /
Otros:        B --- D --- F (origin/main)

Tu rama está muy desactualizada. Mientras trabajabas, otros hicieron cambios que afectan tu código.

La solución - merge vs rebase:

Opción 1: Merge (más seguro para equipos)

git fetch origin
git merge origin/main
# Resolver conflictos
git add .
git commit -m "merge: resuelve conflictos con main"

Opción 2: Rebase (más limpio, requiere cuidado)

git fetch origin
git rebase origin/main
# Resolver conflictos uno por uno
# IMPORTANTE: No hacer force push después de rebase público

Mi recomendación para equipos:

Usa merge cuando múltiples personas trabajan en la misma rama
Usa rebase solo en ramas que tú solo estás modificando
Nunca hacer git push --force en ramas compartidas

Problema 2: Archivos en el Staging Incorrecto

El escenario: Hiciste git add . pero no querías añadir ese archivo con passwords. O inversamente, te olvidaste de añadir un archivo importante.

Solución:

# Ver qué está en staging
git status

# Quitar archivo del staging (mantiene los cambios)
git restore --staged archivo.js

# Quitar todos los archivos del staging
git restore --staged .

# Ver diferencias
git diff            # cambios no staged
git diff --staged   # cambios staged

Prevention:

# Usar .gitignore desde el principio
# Revisar siempre antes de hacer commit:
git status
git diff --staged

Problema 3: Commits con Mensajes Inútiles

Mal:

git commit -m "fix"
git commit -m "wip"
git commit -m "changes"
git commit -m "oops"

Bien (Conventional Commits):

feat: añade validación de email en formulario de registro
fix: corrige bug en calculo de precio total
docs: actualiza README con nuevas instrucciones de instalación
refactor: reorganiza lógica de autenticación
test: añade tests para función de descuento
chore: actualiza dependencias del proyecto

Herramientas para mejores commits:

# Commit interactivo - elige qué incluir
git add -p

# Amend - añadir cambios al último commit
git commit --amend --no-edit

# Change último commit message
git commit --amend -m "nuevo mensaje"

# Commit parcial (solo partes del archivo)
git add -p archivo.js

Problema 4: Rama Desactualizada y No Saber Qué Hacer

El escenario: Llevas días trabajando en tu feature. Quieres mergear pero tienes miedo.

Solución paso a paso:

# 1. Ver estado actual
git status
git log --oneline -5

# 2. Actualizar main/develop
git fetch origin
git checkout main
git pull origin main

# 3. Rebasar tu rama
git checkout feature/mi-rama
git rebase main

# 4. Resolver conflictos si los hay
# Editar archivos en conflicto
git add archivo-resuelto.js
git rebase --continue

# Si te arrepientes del rebase:
git rebase --abort

# 5. Push si es necesario
git push origin feature/mi-rama --force-with-lease

Problema 5: El Clásico "Working Tree is Dirty"

El escenario: Necesitas cambiar urgentemente de rama pero tienes cambios sin commitear.

Solución:

# Opción 1: Stash (guardar temporalmente)
git stash
# ... cambiar de rama, trabajar ...
git stash pop  # recuperar cambios

# Opción 2: Commit temporal
git add .
git commit -m "WIP: trabajo en progreso"
# ... cambiar de rama ...
git checkout -
git reset HEAD~1  # deshacer commit, mantener archivos

Problema 6: git push --force y Borraste Trabajo

Si ya hiciste push:

# Buscar commit perdido
git reflog
git checkout -b recovered COMMIT-ID

# Recover rama anterior
git reset --hard ORIG_HEAD

Prevención:

# Nunca hacer force push a ramas compartidas
# Usar --force-with-lease en vez de --force
git push --force-with-lease

# Proteger ramas principales en GitHub
# Settings → Branches → Add rule
# Require pull request reviews
# Require status checks

Problema 7: Diferentes Entornos (Windows vs Mac vs Linux)

El problema: git commit funciona diferente en diferentes sistemas. Fin de líneas, permisos, etc.

Solución - .gitattributes:

# Fix line endings
* text=auto

# Specific files
*.js text eol=lf
*.sh text eol=lf
*.md text eol=lf

# Binary
*.png binary
*.jpg binary
*.ico binary

En Windows:

# Configurar para evitar problemas de line endings
git config --global core.autocrlf true

Problema 8: Tags vs Branches - Cuándo Usar Qué

Tags (para versions):

# Crear tag
git tag v1.0.0

# Tag con anotación (recomendado)
git tag -a v1.0.0 -m "Versión 1.0.0"

# Ver tags
git tag -l

# Push tags
git push origin v1.0.0
git push origin --tags

# Eliminar tag
git tag -d v1.0.0
git push origin --delete v1.0.0

Branches (para desarrollo):

Vida larga
Continuamente actualizados
Para trabajo activo

Tags:

Inmutables
Referencia a un punto específico
Para releases, versions

🛡️ Best Practices para Equipos

1. Pull Requests Que Funcionan

Antes de crear el PR:

# Tests pasando
npm test

# Lint pasando
npm run lint

# Build funcionando
npm run build

# Actualizado con main
git fetch origin
git rebase origin/main

En el PR:

Título claro siguiendo conventional commits
Descripción que explique qué y por qué
Screenshots para cambios visuales
Tests añadidos/actualizados
Checklist de cosas revisadas

2. Code Review Efectivo

Como autor del PR:

Revisa tu propio código primero
Responde a comentarios con gracias o clarificaciones
No te pongas a la defensiva
Haz los cambios sugeridos

Como reviewer:

Sé específico en los comentarios
Sugiere soluciones, no solo problemas
Aprueba cuando esté bien, pide cambios cuando sea necesario
Responde rápido

3. Conventional Commits en Práctica

<tipo>(<ámbito>): <descripción>

[body opcional]

[footer opcional]

Tipos:

feat - nueva característica
fix - bug fix
docs - cambios en documentación
style - formatting, no cambia código
refactor - reorganización de código
test - añadir o modificar tests
chore - mantenimiento general

Ejemplos:

feat(auth): añade login con Google

fix(payment): corrige cálculo de IVA para productos digitales

docs(readme): actualiza instrucciones de instalación

refactor(database): optimiza queries de reports

test(auth): añade tests para logout

4. Git Hooks para Automatización

pre-commit (antes de commit):

#!/bin/bash
npm run lint
npm run test

post-merge (después de pull):

#!/bin/bash
npm install

5. Aliases Útiles

# Tu .gitconfig
[alias]
  st = status
  co = checkout
  br = branch
  ci = commit
  df = diff
  log = log --oneline --graph --decorate
  unstage = restore --staged
  undo = reset --soft HEAD~1
  last = log -1 HEAD

# Usage
git st
git co main
git log

🆘 Chuleta de Comandos de Emergencia

Recuperar algo perdido:

# Ver todos los commits (incluidos "borrados")
git reflog

# Recuperar archivo específico
git checkout COMMIT-ID -- archivo.js

# Recuperar rama "borrada"
git checkout -b recovered COMMIT-ID

Deshacer cosas:

# Deshacer último commit (mantiene archivos)
git reset --soft HEAD~1

# Deshacer último commit (y archivos)
git reset HEAD~1

# Deshacer todo (RIESGO)
git reset --hard HEAD~1

# Deshacer cambios en archivo específico
git checkout -- archivo.js

# Descartar todos los cambios locales
git reset --hard
git clean -fd

Ver historia:

# Log básico
git log

# Log comprimido
git log --oneline

# Log con gráfica
git log --graph --oneline --all

# Quién cambió qué
git blame archivo.js

# Cambios en archivo específico
git log -p archivo.js

Trabajar con remotos:

# Ver remotos
git remote -v

# Añadir remoto
git remote add origin URL

# Cambiar remoto
git remote set-url origin NUEVA_URL

# Ver todas las ramas remotas
git branch -a

# Eliminar rama remota
git push origin --delete nombre-rama

# Descargar sin merge
git fetch origin

🔒 Seguridad con Git

NO hacer nunca:

# ❌ NUNCA
git push --force

# ❌ NUNCA commitear credentials
git add config.php
git commit -m "adding config"

SÍ hacer:

# Usar .gitignore correctamente
# Revisar antes de commitear
git status
git diff --staged

# Usar variables de entorno
const apiKey = process.env.API_KEY

# Usar GitHub Secrets para CI/CD

📦 Herramientas Recomendadas

GUI para Git:

GitHub Desktop - gratuito, simple
Sourcetree - gratuito, potente
GitKraken - freemium, muy visual
VS Code - integrado, liviano

CLI enhancements:

git-extras - comandos adicionales
tig - interface textual
lazygit - terminal interactivo

Para PRs:

GitHub CLI - gh pr create, gh pr review
Conventional Commits - validate commits

💡 Conclusión

Git es una herramienta poderosa, pero con curva de aprendizaje. La clave para trabajar bien en equipo:

Communication - Habla con tu equipo sobre el workflow
Consistency - Usa los mismos comandos, mismas convenciones
Patience - Los conflictos pasan, respira y resuélvelos
Practice - Cuanto más uses Git, más natural se vuelve
Backup - Nunca subas código sin entenderlo

Y recuerda: ante la duda, git reflog te salva.

Referencias útiles:

Happy coding! 🚀