13 ¡Miércoles, Git! — Prevención y Resolución de Problemas Comunes
Un capítulo práctico sobre Git para desarrolladores
Estás leyendo la primera edición en progreso y en castellano de este libro, basada en el currículum de formación del programa de rOpenSci.
Este capítulo está siendo migrado desde los materiales del currículum al formato del libro y puede no reflejar todavía la versión final del contenido.
Contenido pendiente de migración: ver https://github.com/ropensci-training/mierda-git-mejor para el repo fuente de este capítulo.
13.1 Introducción
Todas las personas que usamos git hemos experimentado momentos de frustración: un commit en la rama equivocada, cambios perdidos, o un error que no sabes cómo deshacer. Y muchas veces la documentación o la ayuda no son lo suficientemente claras para darnos el soporte que necesitamos.
La buena noticia es que Git es mucho menos peligroso de lo que parece. Fue diseñado para recuperación y control de versiones, asi que proporciona herramientas para prevenir muchos problemas y recuperarte de casi cualquier situación.
Hay un acuerdo general de que Git no es precisamente la tecnología más fácil de usar del mundo, pero si ya estas programando, seguro puedes aprender lo básico de Git.
La diferencia entre un Git que funciona y uno que no está a menudo en:
- Prevención: Conocer buenas prácticas antes de que ocurran los problemas
- Orientación situacional: Saber exactamente dónde estás en el flujo de Git
- Recuperación: Entender que casi siempre hay una forma de arreglar nuestro problema
13.1.1 Objetivos de aprendizaje
Después de leer este capítulo, podrás:
- Configurar Git de forma segura para evitar problemas comunes
- Identificar en qué punto del flujo de Git te encuentras
- Prevenir situaciones problemáticas mediante buenas prácticas
- Resolver los problemas más comunes que enfrentan los desarrolladores
- Recuperarte de situaciones más complejas con confianza
13.1.2 Prerequisitos
Para poder realizar este taller necesitas:
Tener un poco de experiencia con Git (git commit, git pull/push, ramas, GitHub u otra plataforma). Si querés repasar un poco, te recomendamos el workshop https://yabellini.netlify.app/courses/git_rstudio_course/.
Instalar {saperlipopette} en tu computadora:
install.packages(
"saperlipopette",
repos = c("https://packages.ropensci.org", "https://cloud.r-project.org")
)
saperlipopette, un paquete de R que crea ejercicios prácticos seguros en carpetas temporales. Así puedes experimentar con Git sin miedo a romper tus proyectos reales. Más información en https://docs.ropensci.org/saperlipopette/.
- Si querés, instalá Positron, pero los ejercicios se pueden hacer en RStudio o con tus herramientas usuales para R y Git.
13.1.3 ¿Por qué necesitamos Git?
En un proyecto de software libre es muy común trabajar entre varias personas, a veces estas personas son parte del equipo, otras veces son personas que usan nuestro software. Git es una herramienta para un problema fundamental en el desarrollo de software: ¿cómo mantengo un historial de cambios y cómo trabajo con otros sin perder trabajo?
Git soluciona esto mediante:
- Historial completo: Cada cambio queda registrado con quién lo hizo y cuándo
- Ramas: Trabajar en paralelo sin interferir con otras personas
- Recuperación: Puedes volver a cualquier punto anterior en la historia
- Colaboración: Múltiples personas pueden trabajar en el mismo proyecto
A veces, Git duele. Piensa en alguna ocasión en la que experimentaste un momento confuso o frustrante con Git.
13.2 Repaso de conceptos clave
En el taller desarrollo de software en comunidad vimos y practicamos estos conceptos claves, los refrescamos aqui:
13.2.1 El directorio o carpeta de trabajo
Es tu carpeta actual con tus archivos. Aquí es donde trabajas y modificas archivos.
Mi-Proyecto/
├── script.R
├── datos.csv
└── resultados.qmd
13.2.2 La staging area (area de preparación)
Cuando haces cambios en tu directorio de trabajo, Git los ve como “modificados pero no confirmados”. El staging area es donde le indicamos a Git que debe monitorear estos archivos y los cambios que hacemos en ellos.
13.2.3 El repositorio local
El repositorio local es la copia en nuestra computadora de nuestro proyecto. Alli se guardan todos los cambios que vamos siguiendo y que confirmamos por medio de un commit.
13.2.4 El repositorio remoto
El repositorio remoto es la copia de nuestro proyecto que esta en un servidor (usaremos GitHub como ejemplo) y es la copia a la que tienen acceso las personas que colaboran con nosotros.
13.2.5 Ramas: trabajar en paralelo
Una rama (branch) es como una línea alternativa de desarrollo. La rama por defecto es main pero podemos tener muchas ramas en las cuales trabajamos diferentes aspectos de nuestro software, donde experimentamos cosas y que una vez probadas podemos incorporar en la rama principal.
13.3 Prevención, o cómo evitar problemas
Esta sección te brindara las herramientas para prevenir algunos problemas. Puedes aplicarlas a tu forma habitual de trabajar. Los ejemplos son con Git en R usando la consola, la terminal, RStudio o Positron.
13.3.1 Configurar Git correctamente
Antes de hacer cualquier cosa, verifica tu configuración:
usethis::git_sitrep(tool = "git", scope = "user")Output típico:
── Git global (user)
• Name: "Tu Nombre"
• Email: "[email protected]"
• Global (user-level) gitignore file: ~/.gitignore
• Vaccinated: FALSE
ℹ See `usethis::git_vaccinate()` to learn more.
• Default Git protocol: "https"
• Default initial branch name: "main"
Nombre y email: Deben ser correctos. Aparecerán en todos tus commits.
Protocolo: Debería ser HTTPS (más fácil) o SSH (más seguro)
-
Rama inicial:
maines lo recomendado; algunos proyectos todavía usanmaster. Si tenes este nombre podes cambiarlo con:usethis::git_default_branch_rename(from = "master", to = "main") -
Vaccinated: Debería ser TRUE. Si es FALSE, ejecuta:
usethis::git_vaccinate()
13.3.1.1 Vacunate
La función git_vaccinate() crea un .gitignore global que previene accidentalmente hacer commit de: - Historiales de R (.Rhistory) - Datos temporales (.RData) - Archivos de sistema (.DS_Store)
La documentación sobre git_sitrep contiene mucho mas detalles útiles sobre esta función.
13.3.2 Saber dónde estás en cada momento
Antes de hacer cualquier cosa importante, siempre verifica dónde estás. Especialmente:
¿En qué rama estoy?
Para eso podes revisar el panel de Git en RStudio (panel superior derecho) o en Positron el badge de rama en la esquina inferior izquierda. El prompt de la terminal suele mostrar en que rama estamos.
De esta manera nos aseguramos estar en la rama con la cual queremos trabajar.
TODO: agregar captura de pantalla.
¿Qué archivos cambié?
En ese mismo panel de Git se pueden chequear los archivos modificados, en staging, etc. De esta manera tambien sabemos que modificaciones estaremos confirmando cuando hagamos un commit
TODO: agregar captura de pantalla.
Remote vs local
Tengo que chequear si mis dos repositorios estan sincronizados, por ejemplo, es una buena practica traer todos los cambios del repositorio remoto al local haciendo un pull antes de empezar a trabajar.
Entonces, antes de tomar una acción, siempre verifiquemos nuestro estado para asegurarnos que estamos haciendo la tarea en el repo, rama y archivos adecuados.
13.3.3 Nunca uses Vim como editor por defecto (a menos que lo domines)
El problema: Git a veces abre un editor de texto para escribir mensajes de commit. Si tu editor está configurado como Vim y no lo conoces, es fácil quedar atrapado.
¿Cómo evitarlo?
Configura un editor que ya uses. Opciones comunes:
# Usar VS Code
git config --global core.editor "code --wait"
# Usar RStudio (si estás en macOS)
git config --global core.editor "open -a rstudio"Verifica que funcione desde el terminal.
TODO: chequear si hay un ejercicio con saperlipopete.
13.4 Resolución de problemas comunes
13.4.1 Como vamos a trabajar
Vamos a usar saperlipopette, un paquete de R que crea ejercicios Git en carpetas temporales. Cada función del paquete genera un escenario problemático diferente que debes resolver.
Ventajas: - ✓ No rompees tus proyectos importantes - ✓ Puedes experimentar sin miedo - ✓ Tienes las instrucciones en R - ✓ Las soluciones son reales — aprendes Git de verdad
13.4.1.1 Cómo funciona
Típicamente:
- Creas una carpeta temporal con un escenario usando las funciones del paquete, por ejemplo:
withr::local_language("es")
carpeta <- withr::local_tempdir()
saperlipopette::exo_one_small_change(carpeta)- Vas a la carpeta creada.
- Se abre una nueva sesion con esa carpeta
- Lees las instrucciones
- Usas terminal/Git/tu herramienta favorita para resolver
- Verificas tu solución
- Cierras la sesion de ejercicio.
Cada ejercicio es un “rompecabezas”: tienes un problema real, lees las instrucciones, y tienes que solucionarlo usando Git. El paquete también tiene la función tip() para obtener ayuda si lo necesitamos.
TODO: agregar imagen de como funciona saperlippopete
13.4.2 Problema 1: “Mi último commit me da vergüenza”
Situación: Acabas de hacer un commit, pero: - El mensaje tiene un typo - Olvidaste incluir un archivo - Quieres cambiar el código
Solución: git commit --amend
# Si solo quieres cambiar el mensaje
git commit --amend -m "Nuevo mensaje correcto"
# Si quieres cambiar el código o añadir archivos
git add archivo_olvidado.R
git commit --amend
# Se abrirá tu editor; puedes cambiar el mensaje si quiereswithr::local_language("es")
carpeta <- withr::local_tempdir()
saperlipopette::exo_one_small_change(carpeta)- Vas a la carpeta indicada
- Lees las instrucciones
- Usas
git commit --amendpara solucionarlo - Verificas tu solución
withr::local_language("es")
carpeta <- withr::local_tempdir()
saperlipopette::exo_latest_message(carpeta)Similar al anterior, pero el problema es el mensaje del commit.
13.4.3 Problema 2: “Cambié de idea sobre estos cambios”
Situación: Hiciste cambios, pero ahora te das cuenta de que no son lo que querías.
13.4.3.1 Opción A: Cambios no están en staging
# Ver qué cambió
git diff
# Descartar todos los cambios (⚠️ no recuperable)
git checkout -- .
# O descartar solo un archivo
git checkout -- script.R13.4.3.2 Opción B: Cambios están en staging pero no hicimos commit
# Sacar del staging (los cambios permanecen)
git reset HEAD archivo.R
# Luego descarta si quieres
git checkout -- archivo.R13.4.3.3 Opción C: Ya hiciste commit, pero quieres deshacer
# Opción 1: Deshacer pero mantener los cambios
git reset HEAD~1 # Último commit se deshace, cambios permanecen
# Opción 2: Deshacer y perder cambios (⚠️ cuidado)
git reset --hard HEAD~1
# Opción 3: Crea un nuevo commit que deshace (seguro, deja historial)
git revert HEAD # Crea un nuevo commit inversowithr::local_language("es")
carpeta <- withr::local_tempdir()
saperlipopette::exo_undo_commit(carpeta)Practicas cómo deshacer cambios que ya hiciste commit, manteniendo opciones diferentes.
withr::local_language("es")
carpeta <- withr::local_tempdir()
saperlipopette::exo_revert_file(carpeta)Practicas cómo deshacer cambios en un archivo específico.
13.4.4 Problema 3: “Hice el commit en la rama equivocada”
Situación: Trabajaste en main pero deberías haber creado una rama feature/nueva-cosa.
Solución paso a paso:
# Paso 1: Deshacer el último _commit_ en main (mantiene cambios)
git reset HEAD~1
# Paso 2: Crear la rama correcta y cambiar a ella
git checkout -b feature/nueva-cosa
# Paso 3: Agregar los cambios a _staging_ y hacer _commit_
git add .
git commit -m "Implementar nueva cosa"
# Paso 4: Cambiar de vuelta a main y verificar que esté limpio
git checkout main
git status # Debería estar limpioPracticas cómo mover un commit de main a una rama nueva.
withr::local_language("es")
carpeta <- withr::local_tempdir()
saperlipopette::exo_committed_to_main(carpeta)withr::local_language("es")
carpeta <- withr::local_tempdir()
saperlipopette::exo_committed_to_wrong(carpeta)Variante más compleja donde el commit está en una rama incorrecta.
13.4.5 Problema 4: “Mis cambios eran equivocados”
Situación: El commit problemático no es el último. Hiciste varios commits después, pero uno de los anteriores rompió algo o tiene cambios que quieres deshacer.
Tenemos dos formas de manejar esta situación:
13.4.5.1 Situación A: Deshacer un commit completo en la mitad del historial
Escenario: Hace 5 commits hiciste un commit con mensaje “Fix reparar las cosas” que rompió tu código. Este commit está en la mitad del historial, no al final.
Solución: git revert
# Paso 1: Ver el historial para identificar el commit problemático
git log --oneline
# Paso 2: Copiar el ID del commit que quieres deshacer
# Ejemplo: abc123d Fix reparar las cosas
# Paso 3: Usar git revert para crear un nuevo commit que invierte los cambios
git revert abc123d
# Git abrirá tu editor. Por defecto dice "Revert Fix reparar las cosas"
# Puedes mantener el mensaje o editarlo. Guarda y cierra.Resultado: Se crea un nuevo commit que deshace los cambios del commit original. Esto es seguro porque no reescribe la historia, sino que agrega un nuevo commit inverso.
Importante: git revert funciona mejor cuando ese commit contiene solo los cambios que quieres deshacer. Si el commit tiene múltiples cambios y algunos sí quieres mantener, usa la siguiente estrategia.
13.4.5.2 Situación B: Deshacer cambios a un archivo específico cuando el commit cambió múltiples archivos
Escenario: Un commit antiguo modificó dos archivos: brap.txt y fix.txt. Quieres que brap.txt vuelva a su estado anterior, pero mantener los cambios en fix.txt.
Solución: git checkout para restaurar un archivo específico
# Paso 1: Ver el historial
git log --oneline
# Paso 2: Identificar el commit ANTES del problemático
# Ejemplo: si el commit problemático es abc123d, necesitas el anterior (def456e)
# Paso 3: Restaurar el archivo a su estado en ese commit anterior
git checkout def456e -- brap.txt
# El archivo está ahora automáticamente en staging (staged)
# Paso 4: Hacer un nuevo commit con este cambio
git commit -m "Restaurar brap.txt a su estado anterior"Resultado: El archivo brap.txt vuelve a su versión anterior, mientras que fix.txt sigue como estaba.
withr::local_language("es")
carpeta <- withr::local_tempdir()
saperlipopette::exo_revert_commit(carpeta)Practicas cómo identificar un commit problemático en la mitad del historial y deshacerlo de forma segura con git revert.
withr::local_language("es")
carpeta <- withr::local_tempdir()
saperlipopette::exo_restore_file(carpeta)Practicas cómo restaurar un archivo a su versión anterior sin afectar otros archivos del mismo commit.
13.4.6 Problema 5: “Necesito la versión anterior de este archivo”
Situación: Alguien cambió un archivo y quieres la versión de hace 3 commits.
# Ver el historial de un archivo
git log -- archivo.R
# Restaurar a una versión anterior
git checkout HASH -- archivo.R
# O simplemente deshacer el último cambio en ese archivo
git checkout HEAD~1 -- archivo.R13.4.7 Situaciones más complejas
13.4.7.1 Conflictos de merge (o merge conflicts)
¿Qué es? Cuando dos personas editan la misma línea de un archivo, Git no sabe qué versión mantener.
Apariencia:
<<<<<<< HEAD
versión_tuya()
=======
versión_de_otro()
>>>>>>> rama-de-otro
Cómo resolver: 1. Manualmente edita el archivo, manteniendo lo que quieres 2. Elimina los marcadores de conflicto (<<<<, ====, >>>>) 3. Haz git add archivo.R y git commit
Prevención: Comunícate con tu equipo, usa ramas, haz merge frecuente.
Para situaciones muy complicadas donde necesitas reescribir historial:
# Ejercicio avanzado
withr::local_language("es")
carpeta <- withr::local_tempdir()
saperlipopette::exo_time_machine(carpeta)Este es el ejercicio más desafiante. Solo inténtalo después de haber practicado los anteriores.
13.5 Mejores prácticas
13.5.1 Commits frecuentes y descriptivos
Mejor:
git commit -m "Agregar validación de entrada en función parse_data()"Evita:
git commit -m "cambios" # Demasiado vago13.5.2 Ramas para cada feature
# Rama por feature
git checkout -b feature/autenticación
# Rama por bugfix
git checkout -b fix/login-error
# Rama experimental
git checkout -b experiment/new-algorithm13.5.3 Antes de push, verifica
# ¿Qué cambios estoy por subir?
git log origin/main..HEAD
# ¿Hay conflictos con main?
git fetch origin
git merge --no-commit --no-ff origin/main
git merge --abort # Si no te gustan los cambios
# ¿Mi código funciona?
# (Ejecuta tests locales)13.5.4 Mensajes de commit claros
Formato útil:
<tipo>: <descripción breve (50 caracteres)>
<Explicación más larga si es necesario>
Fixes #123 # Si resuelve un issue
Tipos comunes: feat:, fix:, refactor:, test:, docs:
13.6 Resumen de ejercicios
Aquí está la lista completa de ejercicios con saperlipopette. Te recomendamos hacerlos en este orden:
| # | Ejercicio | Comando | Dificultad | Tiempo |
|---|---|---|---|---|
| 1 | Cambios menores | exo_one_small_change() |
Fácil | 5 min |
| 2 | Mensaje incorrecto | exo_latest_message() |
Fácil | 5 min |
| 3 | Deshacer commit | exo_undo_commit() |
Media | 8 min |
| 4 | Revertir archivo | exo_revert_file() |
Media | 8 min |
| 5 | Commit en main | exo_committed_to_main() |
Media | 10 min |
| 6 | Rama equivocada | exo_committed_to_wrong() |
Media | 10 min |
| 7 | Deshacer commit antiguo | exo_revert_commit() |
Media | 10 min |
| 8 | Restaurar archivo | exo_restore_file() |
Media | 10 min |
| 9 | Time machine | exo_time_machine() |
Difícil | 15 min |
Practica 1-2 ejercicios por sesión de estudio. No intentes hacerlos todos de una.
13.7 Resumen y puntos clave
13.7.1 Lo más importante
Git no es tan malo. Fue diseñado para recuperación, no para destrucción.
-
Prevención > solución:
- Configura bien tu editor
- Usa
.gitignore - Verifica con
git statusantes de push - Usa ramas para nuevos cambios
-
Cuando algo sale mal:
- Mantén la calma
- Ejecuta
git statuspara orientarte - Busca la solución (generalmente
git reset,git revert, ogit commit --amend) - No hagas
git push --forcesin antes analizar bien la situación
-
Practica con seguridad:
- Usa
saperlipopettepara practicar - No rompes tus proyectos reales
- Aprendes Git de verdad, con práctica real, no solo la teoría
- Usa
13.7.2 Recursos adicionales
-
Happy Git and GitHub for the useR: https://happygitwithr.com/
- Excelente guía práctica para usuarios de R
-
“Oh Shit, Git!”: https://ohshitgit.com/
- Soluciones rápidas para problemas comunes
-
Pro Git Book: https://git-scm.com/book/en/v2
- Referencia completa y profunda
-
Julia Evans’ Zines: https://wizardzines.com/
- Visualizaciones hermosas de cómo funciona Git
-
Documentación de saperlipopette: https://docs.ropensci.org/saperlipopette/
- Documentación completa con todos los ejercicios
13.8 El mensaje final
Git es una herramienta creada por desarrolladores, para desarrolladores. Tiene sus peculiaridades, pero es muy útil. La curva de aprendizaje es porque hay mucho poder disponible.
Lo importante es practicar en escenarios seguros y eso es exactamente lo que saperlipopette te permite hacer.
Cada persona experimentada en desarrollo de software ha estado en algún momento atrapado en Git. Todos aprendimos. Y tú también puedes.
13.9 Preguntas de repaso
Usa estas preguntas para verificar tu comprensión. Intenta responder sin mirar atrás:
Conceptos básicos: ¿Cuál es la diferencia entre el directorio de trabajo, el staging area y el repositorio local?
Prevención: ¿Qué hace
usethis::git_vaccinate()y por qué es útil?Ubicación: ¿Cómo verificarías en RStudio o Positron en qué rama estás?
Enmienda: ¿Qué comando usarías si necesitas cambiar el mensaje del último commit que acabas de hacer?
Deshacer: ¿Cuál es la diferencia entre
git reset HEAD~1ygit reset --hard HEAD~1?Rama equivocada: Si hiciste 3 commits en
mainpero deberían estar enfeature/nuevo, ¿qué pasos seguirías?Verificación: Antes de hacer
git push, ¿qué comando ejecutarías para verificar que todo está bien?saperlipopette: ¿Por qué usarías
saperlipopetteen lugar de practicar directamente en tus proyectos reales?