El despertar de la lentitud
Llevas un rato trabajando en tu proyecto de data science. Tienes veinte notebooks, unas cuantas imágenes, y la típica estructura de carpetas que parecía buena idea hace tres meses.
Haces git status para ver qué has tocado y… esperas. Y esperas. Y mientras esperas te da tiempo a preguntarte si el ordenador se ha quedado pillado o simplemente está meditando.
Spoiler: no está meditando. Está sufriendo.
El problema tiene nombre (y apellidos)
Git no es lento. Tu repo sí.
Cuando ejecutas git status, git tiene que hacer dos cosas que parecen sencillas pero no lo son:
- Escanear todo el árbol de ficheros para ver qué ha cambiado
- Comparar cada fichero con lo que tiene guardado
En un repo normal esto es instantáneo. Pero los notebooks de Jupyter son JSON disfrazado de documento. Y no un JSON cualquiera: uno que incluye código, salidas, imágenes codificadas en base64, metadatos del kernel, y básicamente todo lo que se le ocurrió meter al que diseñó el formato.
Un notebook «pequeño» con unas pocas gráficas puede pesar varios megas. Multiplica eso por veinte notebooks y tienes un repo que gime cada vez que lo miras.
Y si encima renombras una carpeta… git lo interpreta como «has borrado 50 ficheros y has creado 50 nuevos». Diversión asegurada.
Solución 1: Ponle un portero a tu repo
La primera solución es tan elegante que da rabia no haberla conocido antes.
Se llama FSMonitor y funciona así: en vez de que git escanee todo el repo cada vez que haces algo, el sistema operativo le avisa de qué ficheros han cambiado.
Dicho en cristiano: es como tener un portero en la entrada que te dice «solo ha entrado Juan» en vez de tener que revisar toda la lista de invitados cada vez.
Para activarlo:
git config core.fsmonitor true
git config core.untrackedcache true
Listo. Ya está.
La primera vez que hagas git status después de activarlo tardará lo mismo (o más, porque tiene que inicializar la caché). Pero a partir de la segunda… magia.
En mi repo de 400+ ficheros, git status pasó de 2-3 segundos a ser instantáneo. No «rápido». Instantáneo.
¿Funciona en todos lados?
- macOS: Sí, usa FSEvents
- Linux: Sí, usa inotify (si tu kernel lo soporta, que lo soporta)
- Windows: Sí, usa ReadDirectoryChangesW
O sea, sí.
Solución 2: Guarda la receta, no la foto del plato
FSMonitor acelera el escaneo, pero hay otro problema: los notebooks siguen siendo enormes. Y cada vez que ejecutas una celda y guardas, aunque el código sea el mismo, el fichero cambia porque las salidas son diferentes.
Esto significa:
- Diffs ilegibles (¿quién quiere revisar base64 de una imagen?)
- Commits inflados
- Merges del infierno
La solución se llama nbstripout y hace exactamente lo que su nombre indica: strippea el output de los notebooks antes de commitear.
Es como guardar la receta sin las fotos del plato terminado. El código está ahí, los resultados los regeneras cuando quieras.
Para instalarlo con uv:
uv add nbstripout
uv run nbstripout --install
O con pip, si eres de la vieja escuela:
pip install nbstripout
nbstripout --install
El --install configura git automáticamente para que use nbstripout como filtro. A partir de ese momento, cuando hagas commit de un notebook, se guarda sin outputs.
Para verificar que está funcionando:
git config --get filter.nbstripout.clean
Si devuelve algo como nbstripout, vas bien.
¿Y si necesito guardar los outputs?
Buena pregunta. A veces quieres commitear un notebook ya ejecutado, por ejemplo para documentación o para que alguien lo vea sin tener que ejecutarlo.
nbstripout te deja marcar notebooks específicos para que se salten el filtro:
git -c diff.nbstripout.textconv=cat diff
O puedes configurar excepciones en tu .gitattributes. Pero en general, mi consejo es: no guardes outputs. Los notebooks son código, no documentos finales.
Mención honorífica: git-lfs
Si además de notebooks tienes imágenes o vídeos que cambian frecuentemente, existe git-lfs (Large File Storage).
La idea es sencilla: en vez de guardar el binario gordo en el repo, guardas un puntero y el fichero real vive en un servidor aparte.
Es como guardar las maletas en la consigna del aeropuerto y llevar solo el resguardo.
git lfs install
git lfs track "*.png"
git lfs track "*.mp4"
¿Por qué es solo mención honorífica y no solución principal? Porque añade complejidad. Necesitas un servidor LFS (GitHub y GitLab lo ofrecen, pero tienen límites), y si alguien clona el repo sin git-lfs instalado, se lleva los punteros en vez de los ficheros.
Para notebooks, FSMonitor + nbstripout suelen ser suficientes. git-lfs es para cuando tienes datasets de verdad o assets multimedia.
El combo ganador
Mi configuración para cualquier repo con notebooks:
# Velocidad
git config core.fsmonitor true
git config core.untrackedcache true
# Notebooks limpios
uv add nbstripout
uv run nbstripout --install
Cuatro comandos y tu repo pasa de abuelo con artritis a atleta olímpico.
Verifica que todo funciona
# FSMonitor activo
git config --get core.fsmonitor
# Debería devolver: true
# nbstripout configurado
git config --get filter.nbstripout.clean
# Debería devolver: nbstripout
Si ambos devuelven lo esperado, ya está. Disfruta de tu git status instantáneo y tus diffs legibles.
Cierre
La próxima vez que alguien te diga «git es lento», ya sabes qué responder: git no es lento, tu repo está mal configurado.
FSMonitor para que el sistema operativo haga el trabajo sucio. nbstripout para que los notebooks no pesen como si llevaran lastre.
Y si después de todo esto sigue lento… igual es hora de plantearse si de verdad necesitas 200 notebooks en el mismo repo. Pero esa es otra historia.
Read this article in English.
