Git para Dados/Notebooks

Notebooks Jupyter, exports parquet e checkpoints de modelos precisam de políticas Git diferentes do código de aplicação - nbstripout, Git LFS e ferramentas de versionamento de dados mantêm os PRs revisáveis e os repositórios pequenos.

Receita

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

Quando usar isso:

Repositórios de ciência de dados com exploração em .ipynb
Equipes de ML compartilhando notebooks que devem ter diffs em PRs
Arquivos Parquet/modelos muito grandes para objetos git normais
Conformidade exigindo que PII nunca esteja no histórico do git

Exemplo de Trabalho

# Trecho do arquivo .pre-commit-config.yaml
repos:
  - repo: https://github.com/kynan/nbstripout
    rev: 0.7.1
    hooks:
      - id: nbstripout
 
# Rastrear artefatos grandes com 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"

# Preferir referenciar dados por URI em notebooks
DATA_URI = "s3://acme-analytics/processed/orders/dt=2026-07-08/"
# não: pd.read_csv("data/orders_10gb.csv")  # comitado no git

O que isso demonstra:

O hook nbstripout limpa as saídas antes do commit
Ponteiros LFS substituem blobs inchados no histórico do git
Notebooks referenciam caminhos de dados externos
.gitattributes documenta as regras de filtro

Mergulho Profundo

Como Funciona

JSON do Notebook - Armazena código, metadados e saídas - as saídas mudam a cada execução, causando diffs enormes.
nbstripout - Filtro git clean/smudge removendo outputs e execution_count.
Git LFS - Armazena arquivos grandes no servidor LFS; o repositório contém arquivos de texto ponteiro.
DVC - Versiona dados em S3/GCS com pequenos arquivos .dvc no git.

Seletor de Estratégia

Ativo	Estratégia
Notebooks	nbstripout + opcional Jupytext `.py`
Arquivos de 10MB-5GB	Git LFS com monitoramento de cota
Datasets	DVC, caminhos de partição na nuvem, catálogo
Segredos em notebooks	Nunca - use env + pydantic-settings

Notas Python

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

Armadilhas

Comitar saídas uma vez - Histórico para sempre inchado mesmo após nbstripout. Correção: filter-repo ou BFG se vazado; prevenir com hooks.
Custos de largura de banda LFS - CI clones baixam LFS. Correção: GIT_LFS_SKIP_SMUDGE=1 em CI que não precisa dos dados.
PII em CSV comitado - Incidente GDPR. Correção: fixtures sintéticas no git; dados de produção no vault bucket.
Conflitos de merge binários em notebooks - Inferno JSON. Correção: remover saídas; um editor por arquivo de notebook.
DVC lock fora de sincronia - Versão errada de dados puxada. Correção: comitar .dvc com código; dvc pull na documentação de CI.
Pickle em notebooks - Risco de execução de código arbitrário. Correção: parquet/JSON para intercâmbio.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Parâmetros do Papermill	Execuções agendadas de notebooks	Código de biblioteca pertence a módulos `.py`
Scripts Marimo / percent	Fonte amigável ao Git primeiro	Equipe padronizada em Jupyter clássico
SageMaker / Colab apenas	Sem git local para notebooks	Organização exige revisão de PR no git
Quarto	Pipeline de publicação de relatórios	Apenas EDA interna rápida

FAQs

nbstripout ou limpar manualmente?

Automatize com pre-commit - a limpeza manual é esquecida em cada commit.

LFS ou DVC?

LFS para poucos binários grandes no repositório; DVC para pipelines de dataset versionados e experimentos reprodutíveis.

Revisar PRs de notebooks?

Use o diff de notebook do GitHub ou revise .py emparelhado do Jupytext para alterações legíveis.

CI executar notebooks?

papermill ou nbclient com fixtures de dados fixadas - não dados de produção ao vivo.

ipynb em pacote de biblioteca?

Evite - mova a lógica para módulos src/; mantenha notebooks em notebooks/ ou docs/.

Limites do tier gratuito do Git LFS?

Monitore armazenamento e largura de banda no GitHub - migre grandes volumes de dados para object store quando exceder.

Conflitos de merge em ipynb?

Re-execute nbstripout em ambos os lados ou escolha o notebook de um autor e reaplique as células manualmente.

nbconvert outputs no git?

Não comite exports HTML/PDF - gere em artefatos de CI.

artefatos wandb vs git?

Armazene artefatos de execução em W&B/S3; git rastreia apenas o SHA do commit de treinamento e o YAML de configuração.

pre-commit lento em repositório enorme?

Escope nbstripout apenas para o caminho notebooks/ na regex files do hook.

Relacionados

Noções Básicas de Engenharia de Dados - normas de pipeline
Configuração do Git - configuração de hooks
Checklist de Resolução de Conflitos de Merge - conflitos de notebook
30 Regras de Código de Dados/ML - regras da equipe

Versões de Stack: Esta página foi escrita para Python 3.14.0 (stable 3.14, maintenance 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+, e uv 0.6+.

Git para Dados/Notebooks

Receita

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

Quando usar isso:

Repositórios de ciência de dados com exploração em .ipynb
Equipes de ML compartilhando notebooks que devem ter diffs em PRs
Arquivos Parquet/modelos muito grandes para objetos git normais
Conformidade exigindo que PII nunca esteja no histórico do git

Exemplo de Trabalho

# Trecho do arquivo .pre-commit-config.yaml
repos:
  - repo: https://github.com/kynan/nbstripout
    rev: 0.7.1
    hooks:
      - id: nbstripout
 
# Rastrear artefatos grandes com 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"

# Preferir referenciar dados por URI em notebooks
DATA_URI = "s3://acme-analytics/processed/orders/dt=2026-07-08/"
# não: pd.read_csv("data/orders_10gb.csv")  # comitado no git

O que isso demonstra:

O hook nbstripout limpa as saídas antes do commit
Ponteiros LFS substituem blobs inchados no histórico do git
Notebooks referenciam caminhos de dados externos
.gitattributes documenta as regras de filtro

Mergulho Profundo

Como Funciona

JSON do Notebook - Armazena código, metadados e saídas - as saídas mudam a cada execução, causando diffs enormes.
nbstripout - Filtro git clean/smudge removendo outputs e execution_count.
Git LFS - Armazena arquivos grandes no servidor LFS; o repositório contém arquivos de texto ponteiro.
DVC - Versiona dados em S3/GCS com pequenos arquivos .dvc no git.

Seletor de Estratégia

Ativo	Estratégia
Notebooks	nbstripout + opcional Jupytext `.py`
Arquivos de 10MB-5GB	Git LFS com monitoramento de cota
Datasets	DVC, caminhos de partição na nuvem, catálogo
Segredos em notebooks	Nunca - use env + pydantic-settings

Notas Python

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

Armadilhas

Comitar saídas uma vez - Histórico para sempre inchado mesmo após nbstripout. Correção: filter-repo ou BFG se vazado; prevenir com hooks.
Custos de largura de banda LFS - CI clones baixam LFS. Correção: GIT_LFS_SKIP_SMUDGE=1 em CI que não precisa dos dados.
PII em CSV comitado - Incidente GDPR. Correção: fixtures sintéticas no git; dados de produção no vault bucket.
Conflitos de merge binários em notebooks - Inferno JSON. Correção: remover saídas; um editor por arquivo de notebook.
DVC lock fora de sincronia - Versão errada de dados puxada. Correção: comitar .dvc com código; dvc pull na documentação de CI.
Pickle em notebooks - Risco de execução de código arbitrário. Correção: parquet/JSON para intercâmbio.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Parâmetros do Papermill	Execuções agendadas de notebooks	Código de biblioteca pertence a módulos `.py`
Scripts Marimo / percent	Fonte amigável ao Git primeiro	Equipe padronizada em Jupyter clássico
SageMaker / Colab apenas	Sem git local para notebooks	Organização exige revisão de PR no git
Quarto	Pipeline de publicação de relatórios	Apenas EDA interna rápida

FAQs

nbstripout ou limpar manualmente?

Automatize com pre-commit - a limpeza manual é esquecida em cada commit.

LFS ou DVC?

LFS para poucos binários grandes no repositório; DVC para pipelines de dataset versionados e experimentos reprodutíveis.

Revisar PRs de notebooks?

Use o diff de notebook do GitHub ou revise .py emparelhado do Jupytext para alterações legíveis.

CI executar notebooks?

papermill ou nbclient com fixtures de dados fixadas - não dados de produção ao vivo.

ipynb em pacote de biblioteca?

Evite - mova a lógica para módulos src/; mantenha notebooks em notebooks/ ou docs/.

Limites do tier gratuito do Git LFS?

Monitore armazenamento e largura de banda no GitHub - migre grandes volumes de dados para object store quando exceder.

Conflitos de merge em ipynb?

Re-execute nbstripout em ambos os lados ou escolha o notebook de um autor e reaplique as células manualmente.

nbconvert outputs no git?

Não comite exports HTML/PDF - gere em artefatos de CI.

artefatos wandb vs git?

Armazene artefatos de execução em W&B/S3; git rastreia apenas o SHA do commit de treinamento e o YAML de configuração.

pre-commit lento em repositório enorme?

Escope nbstripout apenas para o caminho notebooks/ na regex files do hook.

Relacionados

Noções Básicas de Engenharia de Dados - normas de pipeline
Configuração do Git - configuração de hooks
Checklist de Resolução de Conflitos de Merge - conflitos de notebook
30 Regras de Código de Dados/ML - regras da equipe

Versões de Stack: Esta página foi escrita para Python 3.14.0 (stable 3.14, maintenance 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+, e uv 0.6+.

Git para Dados/Notebooks

Buscar na documentação

Git para Dados/Notebooks