Git para datos/notebooks

Los notebooks de Jupyter, las exportaciones de parquet y los checkpoints de modelos necesitan políticas de Git diferentes a las del código de aplicación: nbstripout, Git LFS y las herramientas de versionado de datos mantienen las PRs revisables y los repositorios pequeños.

Receta

pip install nbstripout
nbstripout --install --attributes
git add .gitattributes notebooks/analysis.ipynb
git commit -m "chore: strip notebook outputs on commit"

Cuándo usar esto:

• Repositorios de ciencia de datos con exploración de .ipynb
• Equipos de ML que comparten notebooks que deben diferenciarse en las PRs
• Archivos Parquet/modelos demasiado grandes para objetos git normales
• Cumplimiento que requiere que la PII nunca esté en el historial de git

Ejemplo de trabajo

# Extracto de .pre-commit-config.yaml
repos:
  - repo: https://github.com/kynan/nbstripout
    rev: 0.7.1
    hooks:
      - id: nbstripout
 
# Rastrea artefactos grandes con LFS
git lfs install
git lfs track "*.parquet"
git lfs track "models/*.pt"
git add .gitattributes
git commit -m "chore: LFS track parquet and model weights"

# Prefiere referenciar datos por URI en notebooks
DATA_URI = "s3://acme-analytics/processed/orders/dt=2026-07-08/"
# no: pd.read_csv("data/orders_10gb.csv")  # confirmado en git

Lo que esto demuestra:

• El hook nbstripout borra las salidas antes de confirmar
• Los punteros LFS reemplazan los blobs inflados en el historial de git
• Los notebooks referencian rutas de datos externas
• .gitattributes documenta las reglas de filtro

Inmersión Profunda

Cómo funciona

• JSON de Notebook - Almacena código, metadatos y salidas. Las salidas cambian en cada ejecución, causando diffs enormes.
• nbstripout - Filtro git clean/smudge que elimina outputs y execution_count.
• Git LFS - Almacena archivos grandes en el servidor LFS; el repo contiene archivos de texto puntero.
• DVC - Versiona datos en S3/GCS con pequeños archivos .dvc en git.

Selector de Estrategia

Notas de Python

# Notebook emparejado con Jupytext
jupytext --set-formats ipynb,py:percent analysis.ipynb
git add analysis.ipynb analysis.py

Errores comunes

• Confirmar salidas una vez - Historial permanentemente inflado incluso después de nbstripout. Solución: filter-repo o BFG si se filtró; prevenir con hooks.
• Costos de ancho de banda de LFS - Las clones de CI descargan LFS. Solución: GIT_LFS_SKIP_SMUDGE=1 en CI que no necesita datos.
• PII en CSV confirmado - Incidente GDPR. Solución: fixtures sintéticas en git; datos de producción en bucket de bóveda.
• Conflictos de fusión binarios en notebooks - Infierno JSON. Solución: eliminar salidas; un editor por archivo de notebook.
• DVC fuera de sincronización - Se extrajo la versión incorrecta de los datos. Solución: confirmar .dvc con código; dvc pull en la documentación de CI.
• Pickle en notebooks - Riesgo de ejecución de código arbitrario. Solución: parquet/JSON para intercambio.

Alternativas

Preguntas frecuentes

Relacionado

• Conceptos básicos de ingeniería de datos - normas de pipelines
• Configuración de Git - configuración de hooks
• Lista de verificación de resolución de conflictos de fusión - conflictos de notebooks
• 30 Reglas de código de datos/ML - reglas del equipo

Versiones de Stack: Esta página fue escrita para Python 3.14.0 (estable 3.14, mantenimiento 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, y uv 0.6+.