Integración de Git en Jupyter Notebooks con NB Dime

Clase 9 de 17 • Curso de Entornos Virtuales con Anaconda y Jupyter

Resumen

¿Cómo integrar Git con Jupyter Notebooks?

Incorporar control de versiones en archivos de Jupyter Notebooks puede ser bastante desafiante debido a que están basados en JSON. Esto complica la tarea de visualizar cambios y comparaciones, ya que Git no se adapta bien a archivos de este tipo. Sin embargo, no estás solo en este reto: existen herramientas diseñadas para facilitar la integración de Git con estos notebooks, permitiéndote visualizar los cambios a nivel de celdas y mejorando la colaboración.

¿Qué problemas presenta el control de versiones en GitHub con Jupyter Notebooks?

Cuando trabajas con GitHub y Jupyter Notebooks, podrías notar que los cambios realizados en los notebooks no siempre son tan ilegibles o fáciles de interpretar como te gustaría. Esto se debe a que las modificaciones no se muestran de manera explícita y suelen incluir cambios innecesarios dentro de la estructura del archivo JSON del notebook.

¿Qué es NB Dime y cómo puede ayudar?

NB Dime es una herramienta potentemente útil para manejar las diferencias y cambios en notebooks, enfocándose en las modificaciones de las celdas. Esta herramienta puede instalarse mediante conda y configurarse con Git para una integración eficiente en tu flujo de trabajo.

conda install nbdime
nbdime config-git

Con NB Dime, no solo puedes comparar notebooks celda por celda, sino también fusionar cambios conflictivos entre diferentes versiones del mismo archivo, asegurando que el resultado final combine lo mejor de ambas fuentes.

¿Cómo comparar y fusionar cambios en notebooks con NB Dime?

Comparar notebooks:

NB Dime permite ver claras las diferencias entre diferentes versiones de un notebook, especificando qué celdas han cambiado.
```
nbdiff <file1.ipynb> <file2.ipynb>
```
Este comando revelará las diferencias específicas entre los notebooks especificados.
Fusionar cambios:

En caso de conflictos, NB Dime permite fusionar notebooks, requiriendo tres archivos: un archivo base y dos archivos modificados. Esto facilita la colaboración simultánea.
```
nbmerge <base_file.ipynb> <modified_file1.ipynb> <modified_file2.ipynb> --output <output_file.ipynb>
```
Se recomienda crear siempre un archivo de salida para preservar los cambios y mantener su trabajo organizado.

¿Cuáles son las mejores prácticas para usar Git en Jupyter Notebooks?

Implementar Git en tus notebooks de manera efectiva requiere algunas recomendaciones clave:

Utilizar .gitignore: Filtrar archivos innecesarios como checkpoints que generan los notebooks para evitar que interfieran en tu control de versiones.
División de tareas: Cuando trabajes con notebooks extensos, divídelos en diferentes archivos para facilitar su manejo y documentación.
Documentación de commits: Cada cambio debe estar bien documentado para que tanto tú como tus colaboradores puedan entender fácilmente qué se ha almacenado en cada commit.

Tomar estas medidas no solo mejorará tu flujo de trabajo, sino que también facilitará la colaboración con otros profesionales en proyectos de ciencia de datos y Machine Learning.

Siguiendo estas recomendaciones, puedes estar seguro de que utilizarás Git de manera efectiva en todos tus futuros proyectos de ciencia de datos. ¡Es hora de llevar tu control de versiones al siguiente nivel!

Alberto Duque Villegas

student•

Nosotros que nos estamos formando como científicos de datos, debemos cuidar al máximo el carácter científico de nuestro quehacer con datos.

El control de versiones, además de ser muy útil en el trabajo individual y de equipo, hacer parte de una tendencia contemporánea que consiste en documentar meticulosamente cada cambio en el proceso investigativo, tendencia que tiene un nombre específico: versionado de investigación o control de versiones científicas (scientific version control).

Este concepto, aunque en esencia forma parte de la metodología científica, se ha popularizado como una práctica formal en los últimos años con el auge de la ciencia reproducible (reproducible science) y de un movimiento más amplio de ciencia abierta (open science), que busca hacer accesibles todos los aspectos del proceso científico, desde los datos hasta los métodos y resultados.

Paola Alapizco

student•

📝 Les dejo mis apuntes de la clase

Los Jupyter notebooks son basados en JSON, por lo cuál los cambios que hagamos en una notebook resultan un tanto difíciles de leer a partir de un commit de git, ya que este nos muestra los cambios realizados a un archivo línea a línea de tipo texto; cuando trabajamos con Jupyter notebooks lo que queremos ver son los cambios a nivel de código.

La herramienta nbdime nos permite comparar dos archivos .ipynb a nivel de celdas, esto quiere decir que solo nos mostrará los cambios solo en las celdas modificadas.

Otra funcionalidad que nbdime tiene es la de fusionar (merge) dos notebooks.

Manejo de cambios en notebooks con nbdime

# Activamos el entorno
conda activate [NOMBRE_ENTORNO]

# instalamos la herrmaienta
conda install nbdime

# Si el proyecto esta en otro directorio nos mevemos a el
cd [RUTA_DIRECTORIO]

📌 Si el proyecto no esta inicializado con git, debemos inicializarlo.

git init

Configuramos el proyecto para utilizar nbdime:

# Condifugramos el repositorio
nbdime config-git --enable

# Comparamos las diferencias entre dos archivos
nbdiff [ARCHIVO_1].ipynb [ARCHIVO_2].ipynb 

# Creamos una copia base de uno de los archivos a fusionar
cp [ARCHIVO_1].ipynb base.ipynb

# Fusionamos los notebooks en base.
bnmerge base.ipynb [ARCHIVO_1].ipynb [ARCHIVO_2].ipynb 


# Generamos un archivo con el resultado del merge
bnmerge base.ipynb [ARCHIVO_1].ipynb [ARCHIVO_2].ipynb --out [NOMBRE_ARCHIVO].ipynb

Buenas prácticas en el uso de git dentro de Jupyter Notebooks

Usar .gitignore: Para evitar añadir al repositorio archivos que van generando los notebooks.
Dividir notebooks grandes: Dividir notebooks extensos en notebooks más pequeños, cada uno con un objetivo especio.
Documentar commits: Llevar un registro claro de cada cambio en el código y notebooks.

Francisco Cisneros

student•

El comando nbdime se utiliza para manejar diferencias y conflictos en archivos de Jupyter Notebooks. A diferencia de Git, que compara archivos de texto a nivel de línea, nbdime permite visualizar cambios a nivel de celdas, lo que facilita la colaboración entre desarrolladores. Ayuda a integrar Jupyter Notebooks con Git de manera más efectiva y a resolver conflictos que puedan surgir cuando múltiples personas editan el mismo notebook.

Mario Alexander Vargas Celis

student•

La integración de Git en Jupyter Notebooks con NB Dime (también conocido como nbdime) permite comparar, fusionar y visualizar diferencias entre notebooks .ipynb de manera más comprensible que con Git tradicional, que trata los notebooks como archivos JSON.

🧠 ¿Qué es nbdime?

nbdime es una herramienta diseñada para comparar y fusionar notebooks de Jupyter. Proporciona diferencias visuales y comprensibles, tanto en contenido como en metadatos.

⚙️ Instalación

Para instalar nbdime:

pip install nbdime

O con conda:

conda install -c conda-forge nbdime

🚀 Configuración con Git

Una vez instalado, puedes integrarlo con Git para que use nbdime automáticamente cuando hagas un git diff o git merge.

nbdime config-git --enable

Esto configura Git para usar nbdiff, nbmerge, y nbshow en notebooks.

🔍 Comandos Principales

ComandoDescripciónnbdiff notebook1.ipynb notebook2.ipynbCompara notebooks.nbdiff-web notebook1.ipynb notebook2.ipynbCompara notebooks en una interfaz web.nbmerge base.ipynb local.ipynb remote.ipynbFusiona notebooks (similar a git merge).nbshow notebook.ipynbMuestra el contenido de un notebook como texto plano.

🧪 Ejemplo básico

Para ver diferencias visuales entre dos versiones de un notebook:

nbdiff-web notebook_v1.ipynb notebook_v2.ipynb

Esto abrirá una interfaz web donde podrás ver diferencias en:

Celdas de código
Resultados de salida
Metadatos
Celdas Markdown

✅ Beneficios clave

Comprensión clara de cambios entre versiones de notebooks.
Ideal para equipos que colaboran en notebooks científicos o de análisis de datos.
Mejora el control de versiones en proyectos con notebooks.

JOHN RICHARD HERNANDEZ VASQUEZ

student•

El comando correcto para fusionar archivos usando nbmerge debe especificar el archivo de salida. En tu comentario, señalas que debería ser nbmerge base.ipynb ejemplo2.ipynb -o base.ipynb. Tienes razón en que la opción -o indica el archivo donde se guardará el resultado, el cual puede sobreescribir el original si se desea. Es fundamental tener claro este detalle para evitar confusiones y asegurar una correcta gestión de versiones en Jupyter Notebooks.

Daniel Andres Rojas Paredes

student•

tenia la duda y preguntandole a la ia me da a enternder que no es necesario inicializar un repo the git para poder hacer uso de las funcionalidades de nbdime.

Daniel Andres Rojas Paredes

student•

al parecer estaba terriblemente equivocada, cuando corri el comando nbdime config-git --enable lo note

Pablo Torres Pérez

student•

¿Qué puedo hacer si estuve trabajando en el mismo archivo de jupyter notebook que otro compañero y hay conflictos al hacer pull? ¿Cómo se resuelven los conflictos en este caso con nbdime de forma visual?

En mi caso, use el siguiente comando que abre una interfaz web gráfica bastante amigable que permite resolver los conflictos.

nbdime mergetool

Es importante que el comando sea ejecutado en la terminal de colab con el entorno activo.

Les comparto una captura de la interfaz.

Pablo Torres Pérez

student•

Pablo Torres Pérez

student•

Otra cosa importante es que genera archivos auxiliares: BACKUP, BASE, LOCAL y REMOTE justo en la ruta del .ipynb. Después de verificar que todo está correcto, puedes eliminar los archivos ya que son temporales y no se necesitan después de la fusión.