Git es la herramienta que registra la historia de un proyecto y GitHub es el lugar donde esa historia se comparte. Juntos permiten que varias personas trabajen sobre el mismo código sin pisarse, que cada cambio tenga un motivo registrado y que cualquier error se pueda deshacer. El miedo a romper algo suele venir de no entender tres o cuatro conceptos, no de falta de memoria para comandos.
Esta guía propone un flujo de trabajo simple —ramas cortas, pull requests y revisión— que funciona igual en un equipo de dos personas o de veinte. Incluye los diez comandos que se usan el 90% del tiempo, cómo resolver conflictos sin pánico, un ejemplo de una funcionalidad de punta a punta y las limitaciones del modelo.
El modelo mental mínimo
Con cuatro ideas alcanza para trabajar con seguridad:
- Commit. Una foto del proyecto con un mensaje que explica el porqué de un cambio. La historia del proyecto es la suma de commits.
- Rama. Una línea de trabajo paralela. Se crea para hacer un cambio y se integra cuando está listo.
- Remoto. La copia del repositorio que vive en un servidor (GitHub, GitLab, Bitbucket).
pushsube,pullbaja. - Pull request (PR). Una propuesta de integración: "quiero que estos commits entren en la rama principal". Es el espacio donde se revisa y se discute.
El resto son comandos. Y los comandos se aprenden cuando el modelo está claro.
Los diez comandos que vas a usar todo el tiempo
git clone <url> # traer un repositorio
git switch -c feature/busqueda # crear y moverte a una rama
git status # qué cambió y qué está pendiente
git diff # ver el cambio antes de guardarlo
git add -p # elegir qué partes del cambio entran
git commit -m "mensaje" # registrar el cambio
git pull --rebase origin main # traer lo último antes de subir
git push -u origin feature/busqueda
git log --oneline --graph -20 # revisar la historia
git switch main && git pull # volver a la rama principal actualizada
Dos hábitos que evitan el 80% de los problemas: git status antes de cualquier operación grande y git pull --rebase antes de subir tu rama.
Convención de ramas y commits
No necesitas una convención compleja, pero sí una que todos entiendan. Un esquema que funciona:
| Tipo de rama | Ejemplo | Cuándo usarla |
|---|---|---|
| feature | feature/reporte-mensual | Funcionalidad nueva |
| fix | fix/error-total-carrito | Corrección de un error |
| docs | docs/readme-instalacion | Solo documentación |
| chore | chore/actualizar-dependencias | Mantenimiento |
En los mensajes de commit, el formato más útil es una línea corta en imperativo y, si hace falta, un párrafo con el motivo:
fix: corregir redondeo en el total del carrito
El total acumulaba errores de centavos cuando había más de tres productos
con decimales. Ahora se calcula en centavos enteros y se convierte al final.
Refs: #142
"fix: corregir redondeo" se entiende en el futuro; "cambios varios" no. Un mensaje que explica el porqué ahorra media hora de arqueología cuando alguien investiga un error seis meses después.
Pull requests que se revisan rápido
Un PR bien armado es corto, tiene contexto y es fácil de verificar. Plantilla mínima:
## Qué cambia
Una o dos frases.
## Por qué
El problema o el ticket que resuelve.
## Cómo probarlo
Los pasos exactos para verificar el cambio.
## Riesgos
Qué podría romperse y cómo lo mitigaste.
## Capturas o registros
Solo si aportan.
Reglas prácticas para que tu PR se revise en horas y no en días:
- Menos de 400 líneas de cambio. Los PR gigantes se dejan para el final.
- Una cosa por PR. Si el cambio hace dos cosas independientes, son dos PR.
- Antes de pedir revisión, revisá tu propio diff. Encontrarás comentarios olvidados y archivos que no querías incluir.
- Respondé cada comentario. Aunque sea con "hecho" o "lo dejo para otro PR porque…".
Resolver conflictos sin pánico
Un conflicto ocurre cuando dos personas tocan las mismas líneas del mismo archivo. No es un error: es Git pidiéndote una decisión. El procedimiento:
git statuspara ver qué archivos están en conflicto.- Abrí cada archivo y buscá los marcadores que Git insertó:
<<<<<<<,=======,>>>>>>>. - Elegí qué queda: tu versión, la de la otra rama o una mezcla. Borrá los marcadores.
git adda cada archivo resuelto ygit commitpara cerrar la fusión.- Ejecutá las pruebas. Un conflicto resuelto que compila pero rompe la lógica sigue siendo un problema.
Si el conflicto se vuelve inmanejable, git merge --abort devuelve todo al estado anterior. No hay penalidad por abortar y volver a intentarlo con calma.
Qué hacer cuando rompiste algo
- Revertir un commit ya publicado:
git revert HASHcrea un commit nuevo que deshace el anterior. Es la opción segura en ramas compartidas. - Deshacer el último commit local sin perder los cambios:
git reset --soft HEAD~1deja los archivos listos para volver a ordenarlos. - Recuperar algo que creías perdido:
git reflogmuestra los movimientos recientes del repositorio y permite volver casi a cualquier estado. - Descartar cambios locales de un archivo:
git restore archivo.
Regla de oro: nunca uses reset --hard ni push --force sobre una rama compartida sin coordinarlo con el equipo. En tu rama personal, con cuidado, están permitidos.
Ejemplo trabajado: una funcionalidad de punta a punta
Supongamos que tenés que agregar un filtro por fecha a un reporte. El recorrido completo, con los comandos:
| Paso | Comando | Qué logra |
|---|---|---|
| 1 | git switch main && git pull | Partir de la versión más reciente |
| 2 | git switch -c feature/filtro-fecha | Aislar el trabajo |
| 3 | git add -p && git commit -m "feat: agregar parámetros de fecha al reporte" | Commits chicos y revisables |
| 4 | git push -u origin feature/filtro-fecha | Compartir la rama |
| 5 | Abrir el PR con la plantilla completa | Dar contexto al revisor |
| 6 | Responder comentarios con cambios nuevos en commits aparte | Mantener la revisión entendible |
| 7 | git pull --rebase origin main antes de integrar | Evitar conflictos tardíos |
| 8 | Integrar el PR y borrar la rama | Cerrar el ciclo |
En un equipo con revisión, el paso 6 puede repetirse dos o tres veces. No es burocracia: cada ronda suele encontrar un caso borde que nadie había pensado.
Reglas de equipo que evitan dolores
- Proteger la rama principal. Nadie hace
pushdirecto; todo entra por PR. - Nunca subir archivos
.envni claves. Si ocurre, hay que rotar las credenciales, no solo borrar el archivo. - Nombrar ramas con claridad.
feature/,fix/,docs/,chore/. - Un PR, una idea. Facilita revisar y revertir.
- Acordar rebase o merge y no mezclar los dos. La historia se vuelve ilegible cuando conviven criterios.
- Ejecutar pruebas antes de pedir revisión. El revisor no es un servidor de integración.
- Documentar decisiones técnicas en el PR, no en el chat, para que queden asociadas al cambio.
Limitaciones
- Git no arregla un proceso desordenado. Si el equipo no acuerda nada, un repositorio impecable no evita el caos.
- Los archivos binarios son incómodos. Imágenes, videos y datasets pesan mucho en la historia; para eso existe Git LFS o almacenamiento externo.
- Los repositorios muy grandes se vuelven lentos. Monorepos enormes requieren estrategias específicas de clonado y filtrado.
- La historia se puede reescribir. Que algo esté en Git no significa que sea verdad; los mensajes y los pasos siguen dependiendo de las personas.
- No es un sistema de respaldo. Un
pusha un remoto ayuda, pero un respaldo real necesita copias independientes. - Aprender rebase interactivo lleva tiempo. No es obligatorio para trabajar; es una optimización que se incorpora cuando la necesitás.
Preguntas frecuentes
¿Git y GitHub son lo mismo? No. Git es el sistema de control de versiones que corre en tu máquina; GitHub, GitLab y Bitbucket son servicios que alojan repositorios Git y agregan revisión, tickets e integraciones.
¿Cuándo conviene usar ramas cortas? Siempre. Una rama que vive más de dos o tres días acumula conflictos y pierde contexto. Si el cambio es grande, dividilo.
¿Debo hacer merge o rebase? Para integrar una rama de trabajo, rebase deja una historia lineal y limpia; merge preserva el contexto de la rama. Lo importante es que el equipo acuerde una y la sostenga.
¿Qué hago si mi PR fue rechazado? Preguntá el motivo, ajustá y volvé a intentarlo en la misma rama. Un PR rechazado con buenos argumentos es aprendizaje, no fracaso.
¿Necesito saber Git para trabajar en tecnología? Sí, en cualquier rol técnico. Incluso perfiles de datos y diseño lo usan a diario.
¿Cómo practico sin arriesgar el repositorio del trabajo? Creá un repositorio de práctica propio y provocá conflictos a propósito: es la mejor forma de aprender a resolverlos.
Siguiente paso
El flujo de ramas se entiende mejor cuando el proyecto tiene una forma de trabajo clara: la guía de principios ágiles explica cómo se organizan las iteraciones. Si estás armando tu primer proyecto, el curso completo de desarrollo web y Express desde cero te dan el código sobre el que practicar. Y cuando quieras publicarlo, seguí la guía para desplegar una app Node.js en un VPS. Si preferís una ruta guiada, revisá los cursos de Cursalo y la categoría Herramientas y comparativas.