Cómo dejar de ahogarte en enormes Pull Requests con gh-stack

Todos hemos estado ahí: estás trabajando en una funcionalidad compleja que toca la API, la lógica del backend y el frontend. El resultado es un PR gigante con tres mil líneas de código. El revisor lo abre, ve el volumen, suspira en silencio y cierra la pestaña hasta tiempos mejores. O peor, lo repasa en cinco minutos y escribe "LGTM", perdiéndose errores críticos.

Para ahorrarles a nuestros compañeros, intentamos dividir los cambios en piezas pequeñas. Pero entonces comienza el infierno de las dependencias: la rama feature-ui depende de feature-api, que depende de feature-db. Corrige algo en la parte inferior de esta cadena, y tienes que hacer rebase manualmente de todas las ramas superiores, mantener registro de las ramas base en GitHub y esperar que nada se rompa.

Parece que los ingenieros de GitHub también se cansaron de esto y lansaron una extensión para su CLI — gh-stack. Automatiza el trabajo con los llamados pull requests "apilados".

Qué son los PR apilados y por qué los necesitas

La idea es simple: en lugar de un cambio masivo, creas una cadena de PRs pequeños y lógicamente conectados. Cada uno posterior se construye sobre el anterior.

Piénsalo de esta manera:

1. PR #1: Agregar esquema de base de datos (base: main).
2. PR #2: Implementar endpoints de API (base: rama del PR #1).
3. PR #3: Construir la interfaz del frontend (base: rama del PR #2).

Los revisores pueden revisarlos individualmente. Es más rápido, más fácil y más exhaustivo. El problema es que Git y GitHub no funcionan nativamente bien con esta estructura. Si actualizas el PR #1, tienes que "jalar" manualmente los cambios a todos los demás. gh-stack maneja esta rutina por ti.

Cómo funciona en la práctica

La herramienta se instala como una extensión del CLI oficial de GitHub. Si ya tienes gh, la instalación toma un par de segundos:

gh extension install github/gh-stack

Creando tu primera pila

Digamos que estás comenzando a trabajar en una nueva tarea. En lugar del habitual git checkout -b, inicializas una pila:

gh stack init

Luego haces commits como de costumbre. Cuando la primera parte lógica está lista, en lugar de crear una rama manualmente, simplemente dices:

gh stack add feature-api

Este comando crea una nueva rama encima de la actual e inmediatamente te cambia a ella. Sigues escribiendo código. Cuando la pila está lista, un solo comando gh stack submit envía todo a GitHub. La herramienta creará múltiples pull requests y configurará correctamente su base branch para que cada PR muestre solo el diff relevante, no un desastre de todas las ramas anteriores.

Navegación y ediciones

Una de las funciones más útiles en gh-stack es la navegación. ¿Olvidaste los nombres de las ramas? Sin problema.

• gh stack up — subir un nivel en la pila.
• gh stack down — bajar a la base.
• gh stack tree — ver toda la estructura.

Si un revisor te pide que corrijas algo en el primer PR, simplemente bajas (gh stack bottom), haces los cambios y ejecutas gh stack rebase. La magia es que la herramienta propaga automáticamente estos cambios a través de toda la pila hacia arriba, actualizando todas las ramas intermedias. No más hacer rebase manualmente de cinco ramas seguidas.

Gestión a través de TUI

Para quienes prefieren control visual, existe el comando gh stack modify. Abre una interfaz interactiva directamente en la terminal. Ahí puedes:

• Reordenar ramas.
• Combinar múltiples ramas en una.
• Eliminar partes innecesarias de la pila.
• Renombrar capas.

Esto es mucho más intuitivo que intentar hacer lo mismo a través de git rebase -i y el cambio interminable de ramas.

Sincronización y finalización del trabajo

Cuando tus PRs comienzan a fusionarse en la rama principal, es hora de gh stack sync. El comando hace varias cosas útiles a la vez: extrae cambios de main, actualiza tu pila local y sugiere eliminar ramas de los pull requests ya fusionados.

Por cierto, la utilidad también puede trabajar con agentes de IA. Si usas automatización para generación de código, puedes instalar la habilidad gh skill install github/gh-stack para que el agente entienda tu estructura de ramas y no rompa la pila.

¿Alguna advertencia?

El proyecto actualmente está en Vista Previa Pública. Esto significa que para que algunas funciones funcionen (como la bonita visualización de relaciones de PR directamente en la interfaz de GitHub), la funcionalidad debe estar habilitada para tu repositorio. Si aún no está activa, puedes unirte a la lista de espera.

Sin embargo, incluso sin el componente del lado del servidor, como asistente local para gestionar cadenas de ramas, gh-stack ya es bastante usable.

Para quién es esto

Si trabajas en un equipo grande con un proceso estricto de revisión de código, esta herramienta te ahorrará horas. Elimina el miedo a la "delaminación" de ramas y te permite enfocarte en el código en lugar de la administración de Git.

Si eres el único desarrollador en un proyecto y fusionas todo directamente a main, probablemente no necesitas esto. Pero para todos los demás — esta es una excelente manera de hacer que tus PRs sean amigables para humanos y fáciles de revisar.

Vale la pena probarlo solo por el comando gh stack alias. Crea un alias corto gs, después de lo cual trabajar con la pila se vuelve completamente fluido. Por ejemplo, gs push en lugar de construcciones largas y verbosas. Una herramienta simple y efectiva de los creadores de GitHub.