DataLad

Visão Geral

DataLad é uma camada de gerenciamento de dados sobre Git e git-annex. O Git rastreia a estrutura do dataset, pequenos arquivos de texto e o histórico. O git-annex rastreia o conteúdo de arquivos grandes, armazenando cada arquivo como uma chave e mantendo os bytes em um local que não é necessariamente o repositório local.

Um clone normal recupera o histórico do Git e a lista de arquivos de nível superior, deixando os bytes anexados sem serem baixados. Subdatasets instalados têm seus próprios históricos; um clone não os popula automaticamente. O custo do clone depende do histórico do Git e da contagem de arquivos, não apenas do volume de dados. Recupere bytes anexados seletivamente com datalad get.

A segunda coisa que o DataLad adiciona é proveniência. datalad run executa um comando e commita o resultado junto com um registro legível por máquina do comando, suas entradas e suas saídas. datalad rerun lê esse registro e o reexecuta. Isso transforma "como esta figura foi produzida" de um problema de arqueologia em um comando.

Quando usar DataLad em vez de Git puro

Use DataLad quando qualquer um dos seguintes for verdadeiro:

• Arquivos são muito grandes para o Git lidar confortavelmente, ou o total excede o que cada colaborador deseja em disco.
• Os dados residem em mais de um local (um servidor de laboratório, um scratch de cluster, S3, um supercomputador) e você precisa saber quais cópias existem.
• A análise deve ser reexecutável, e uma mensagem de commit simples não é evidência suficiente.
• Você está consumindo datasets publicados de OpenNeuro, DANDI ou datasets.datalad.org, que são distribuídos como datasets DataLad.
• O projeto aninha outros datasets dentro dele e você quer que cada um mantenha seu próprio histórico independente.

Use Git puro quando o repositório for apenas código e texto, tudo couber confortavelmente no Git e ninguém precisar de checkouts parciais. DataLad sobre um pequeno repositório puramente de código adiciona indireção sem trazer benefícios.

Instalação

# git-annex is NOT written in Python but is available from PyPI if you already
# have git itself installed:
uv pip install git-annex
# You can also install it first from the system
# (Debian/Ubuntu: apt install git-annex; macOS: brew install git-annex;
#  conda-forge: conda install -c conda-forge git-annex)
uv pip install "datalad==1.6.5"
uv pip install "datalad-container==1.2.6"   # only for containers-run

datalad wtf --section dependencies   # confirm git-annex version is visible

O pacote PyPI git-annex fornece binários específicos da plataforma. As rodas revisadas 10.20260901.post1 cobrem Linux glibc 2.34+ (x86_64/ARM64), macOS ARM64 14+ e x86_64 15+, e Windows x86_64. Use um pacote do sistema quando nenhuma roda corresponder. Mantenha seu ambiente em PATH e verifique o executável; a roda não fornece o Git em si. Configure o nome/e-mail do autor do Git antes de criar ou salvar um dataset.

datalad wtf imprime o ambiente resolvido e é a primeira coisa a executar quando o comportamento parecer impossível. Um git-annex antigo ou ausente está por trás de uma grande parte de erros confusos.

DataLad é licenciado sob a licença MIT; git-annex tem uma licença AGPL separada. Consulte a licença upstream ao redistribuir qualquer uma das ferramentas.

A falha que morde primeiro: ponteiros não são dados

Após datalad clone, arquivos anexados existem como links simbólicos para .git/annex/objects/ (ou como pequenos arquivos ponteiro onde links simbólicos não estão disponíveis, como no Windows ou em um sistema de arquivos limitado). Nada baixou o conteúdo ainda.

Exemplo ilustrativo de dados remotos; inspecione a revisão selecionada para o caminho exato e instale NiBabel antes da leitura em Python. O refresh testou o comportamento equivalente de ponteiro/get local sem baixar dados de imagem.

datalad clone https://github.com/OpenNeuroDatasets/ds000001.git
cd ds000001
ls sub-01/anat/            # the file is listed
python -c "import nibabel; nibabel.load('sub-01/anat/sub-01_T1w.nii.gz')"   # fails
datalad get sub-01/anat/sub-01_T1w.nii.gz                                   # now it works

O modo de falha a reconhecer: uma ferramenta relata o arquivo como vazio, truncado, corrompido, "não é um arquivo gzip" ou um link simbólico quebrado, e o tamanho do arquivo em disco é de algumas centenas de bytes. Esses sintomas podem indicar um ponteiro de anexo não baixado; confirme com annex status antes de diagnosticar corrupção. Execute datalad get antes de ler os dados e trate "arquivo existe" como evidência insuficiente de que seu conteúdo está presente.

Antes que uma análise toque em um diretório, baixe-o explicitamente:

datalad get sub-01/                  # tudo sob um caminho

…