datalad은(는) 무엇을 하나요?
개요
DataLad는 Git과 git-annex 위에서 동작하는 데이터 관리 계층입니다. Git은 데이터셋 구조, 작은 텍스트 파일, 그리고 변경 이력을 추적합니다. git-annex는 대용량 파일의 내용을 추적하며, 각 파일을 키(key)로 저장하고 실제 바이트는 로컬 저장소가 아닌 다른 곳에 보관합니다.
이러한 분리는 가장 중요한 개념이며, 새로 클론된 데이터셋이 전체 이력과 전체 파일 목록을 포함하면서도 거의 데이터를 포함하지 않는다는 것을 의미합니다. 100TB 데이터셋도 수초 내에 클론되며 수 메가바이트만 차지합니다. 실제 데이터는 datalad get 명령으로 파일 단위로 요청할 때만 도착합니다.
DataLad가 추가하는 두 번째 기능은 과정(provenance)입니다. datalad run은 명령어를 실행하고 그 결과를 명령어, 입력, 출력에 대한 기계가 읽을 수 있는 레코드와 함께 커밋합니다. datalad rerun은 그 레코드를 읽고 재실행합니다. 이는 "이 그림은 어떻게 만들어졌나"라는 질문을 고고학적 문제에서 명령어 하나로 바꿉니다.
일반 Git 대신 DataLad를 사용해야 하는 경우
다음 중 하나라도 해당된다면 DataLad를 사용하세요.
- 파일이 Git이 편안하게 처리하기에는 너무 크거나, 총 용량이 모든 협업자가 디스크에 저장하고 싶어하는 수준을 초과하는 경우
- 데이터가 여러 장소(연구실 서버, 클러스터 스크래치, S3, 슈퍼컴퓨터)에 존재하고 어떤 복사본이 있는지 알아야 하는 경우
- 분석이 재실행 가능해야 하며, 단순한 커밋 메시지만으로는 충분한 증거가 되지 못하는 경우
- OpenNeuro, DANDI, 또는
datasets.datalad.org에서 배포되는 DataLad 데이터셋인 공개 데이터셋을 사용하는 경우 - 프로젝트가 다른 데이터셋을 내부에 중첩하고 있으며 각각 독립적인 이력을 유지해야 하는 경우
저장소가 코드와 텍스트뿐이며 모든 내용이 Git에 잘 들어가고 부분 체크아웃이 필요하지 않다면 일반 Git을 사용하세요. 작은 순수 코드 저장소 위에 DataLad를 사용하면 아무 이점 없이 간접 비용만 추가됩니다.
설치
# git-annex는 Python으로 작성되지 않았지만, git 자체가 설치되어 있다면 PyPI에서 사용 가능합니다:
uv pip install git-annex
# 시스템 패키지 관리자로 먼저 설치할 수도 있습니다
# (Debian/Ubuntu: apt install git-annex; macOS: brew install git-annex;
# conda-forge: conda install -c conda-forge git-annex)
uv pip install datalad
uv pip install datalad-container # containers-run에만 필요
datalad wtf --section dependencies # git-annex 버전이 표시되는지 확인
PyPI git-annex 패키지는 Haskell 소스를 빌드하는 대신 Linux, macOS, Windows용 사전 빌드된 바이너리를 wheel로 제공하므로 다른 Python 의존성처럼 설치할 수 있으며 DataLad와 동일한 환경에서 고정(pin)할 수 있습니다. 이 패키지는 git을 함께 제공하지 않습니다.
datalad wtf는 해결된 환경을 출력하며, 동작이 불가능해 보일 때 가장 먼저 실행해야 하는 명령입니다. 오래되었거나 누락된 git-annex는 많은 혼란스러운 오류의 원인입니다.
DataLad 자체는 MIT 라이선스입니다. git-annex는 AGPL 하의 별도 도구로, 수정된 git-annex를 재배포하는 경우에만 중요합니다.
가장 먼저 부딪히는 문제: 포인터는 데이터가 아닙니다
datalad clone 이후, 관리(annex)된 파일은 .git/annex/objects/ 안의 심볼릭 링크(또는 Windows나 손상된 파일 시스템처럼 심볼릭 링크를 사용할 수 없는 경우 작은 포인터 파일)로 존재합니다. 아직 내용을 다운로드하지 않았습니다.
datalad clone https://github.com/OpenNeuroDatasets/ds000001.git
cd ds000001
ls sub-01/anat/ # 파일이 나열됨
python -c "import nibabel; nibabel.load('sub-01/anat/sub-01_T1w.nii.gz')" # 실패
datalad get sub-01/anat/sub-01_T1w.nii.gz # 이제 작동함
인식해야 할 실패 패턴: 도구가 파일을 비어 있거나, 잘렸거나, 손상되었거나, "gzip 파일이 아님", 또는 깨진 심볼릭 링크라고 보고하며 디스크 상의 파일 크기가 수백 바이트인 경우. 이는 손상된 다운로드가 아니라 포인터입니다. 데이터를 읽기 전에 datalad get을 실행하고, "파일이 존재함"을 내용이 존재한다는 충분한 증거로 간주하지 마세요.
분석이 디렉토리를 건드리기 전에 명시적으로 가져오세요:
datalad get sub-01/ # 경로 아래의 모든 것
datalad get -r . # 모든 것, 서브데이터셋 포함
datalad get -n -r . # 서브데이터셋 구조만, 파일 내용은 제외
datalad status --annex는 로컬에 얼마나 많은 내용이 있는지 보고하며, git annex whereis <path>는 특정 파일을 보유한 저장소를 보고합니다. whereis는 기록된 상태를 읽고 원격 저장소에 접촉하지 않으므로, 현재 정확한 상황이 아니라 git-annex가 마지막으로 알게 된 정보를 알려줍니다.
데이터셋 찾기, 서브데이터셋 동작, 콘텐츠 안전하게 삭제, 데이터셋 복구에 대해서는 data-access.md를 참조하세요.
datalad run으로 과정 기록하기
datalad run은 방법론 맥락에서 DataLad를 사용하는 이유입니다. 명령어를 그 효과와 함께 동일한 커밋에 저장합니다:
datalad run -m "뇌 마스크 추출" \
--input "sub-01/anat/sub-01_T1w.nii.gz" \
--output "derivatives/sub-01_brain.nii.gz" \
"bet {inputs} {outputs} -m"
각 부분의 역할과 생략 시 문제점:
--input은 실행 전에 내용을 검색하여 명령어가 포인터에서 실패하지 않도록 합니다. 또한 의존성을 기록하므로rerun이 다른 머신에서 동일한 입력을 가져올 수 있습니다.--output은 먼저 대상을 잠금 해제하거나 제거하여 git-annex가 보호 중인 내용 위에 쓰기를 거부하지 않도록 합니다. 이 옵션이 없으면 동일한 명령을 두 번째 실행할 때 읽기 전용으로 보이는 관리 파일에 대한 권한 오류가 자주 발생합니다.{inputs}와{outputs}는 해당 값으로 확장됩니다.{pwd},{dspath},{tmpdir}도 사용 가능하며,{inputs[0]}는 개별 항목을 인덱싱합니다.- 커밋 메시지는
=== Do not change lines below ===와^^^ Do not change lines above ^^^사이에 JSON 실행 레코드를 포함합니다. 해당 블록을 수동으로 편집하지 마세요.rerun이 이를 파싱합니다.
datalad run은 데이터셋에 저장되지 않은 수정 사항이 있을 경우 시작을 거부합니다. 깨끗하지 않은 시작 상태는 레코드를 신뢰할 수 없게 만들기 때문입니다. 먼저 저장하거나 폐기하거나, --explicit을 전달하여 나열된 입력과 출력이 전체 이야기임을 선언하세요. --dry-run basic 또는 --dry-run command로 커밋하기 전에 명령어를 확인하세요.
변경 사항이 없는 실행은 datalad save와 마찬가지로 커밋을 생성하지 않습니다.
재실행
datalad rerun # HEAD에 기록된 실행 다시 수행
datalad rerun --report # 수행될 작업을 보여주고, 변경하지 않음
datalad rerun --script recompute.sh # 실행하는 대신 명령어 추출
datalad rerun --since <commit> -b check <revision> # 범위를 새 브랜치로 재생
브랜치로 재실행하는 것(-b)은 재현 가능성을 테스트하는 안전한 방법입니다. 재생 결과는 다른 곳에 저장되며, 원본 브랜치와의 차이(diff)를 통해 출력이 동일하게 나왔는지 확인할 수 있습니다.
컨테이너
datalad-container 확장을 사용하여 이미지를 한 번 등록하면 이후 모든 실행이 어떤 이미지가 출력을 생성했는지 기록합니다:
datalad containers-add fsl --url docker://brainlife/fsl:6.0.4
datalad containers-run -n fsl -m "컨테이너 내 뇌 마스크" \
--input "sub-01/anat/sub-01_T1w.nii.gz" \
--output "derivatives/sub-01_brain.nii.gz" \
"bet {inputs} {outputs} -m"
이미지 자체는 데이터셋에서 추적되므로, 소프트웨어 환경이 누군가의 셸 기록이 아닌 데이터 및 과정 레코드와 함께 이동합니다. 컨테이너가 하나만 구성된 경우 -n은 생략할 수 있습니다.
STAMPED 원칙과 YODA 프로젝트 레이아웃, 실행 레코드 형식, --explicit 및 --assume-ready 의미, W3C PROV로 과정 내보내기에 대해서는 provenance.md를 참조하세요.
변경 사항 저장 및 검사
datalad status # 변경된 내용 확인 (서브데이터셋 상태 포함)
datalad save -m "QC 보고서 추가" path/to/file
datalad save -m "체크포인트" -r # 서브데이터셋까지 재귀
datalad save -m "작은 텍스트 파일" --to-git notes.md
datalad save는 파일별로 내용이 Git에 갈지 git-annex에 갈지 결정하며, 데이터셋의 .gitattributes를 따릅니다. --to-git으로 파일을 강제로 Git에 넣을 수 있으며, 이는 코드와 직접 읽을 수 있어야 하는 작은 텍스트 파일에 적합합니다. yoda 절차(datalad create -c yoda)는 code/, README.md, CHANGELOG.md에 대해 이를 자동으로 설정합니다.
데이터셋 생성
datalad create my_dataset # 일반 데이터셋
datalad create -c yoda my_analysis # 분석 레이아웃 (code/는 Git에서 추적,
# README.md와 CHANGELOG.md 미리 구성됨)
datalad create -d . inputs/raw # 기존 데이터셋 아래에 새 서브데이터셋 등록
-c yoda는 provenance.md에 설명된 분석 프로젝트 레이아웃을 적용합니다. -d .는 새 데이터셋을 상위 데이터셋의 서브데이터셋으로 등록하여 관련 없는 저장소가 내부에 남지 않도록 합니다.
게시
DataLad 데이터셋은 일반적으로 두 곳에 동시에 게시됩니다: 이력을 위한 Git 호스팅 서비스와 관리 콘텐츠를 위한 스토리지 원격 저장소입니다.
datalad create-sibling-github myaccount/mydataset
git annex initremote store type=S3 bucket=my-bucket encryption=none autoenable=true
datalad siblings configure -s github --publish-depends store
datalad push --to github
Git 형제와 스토리지 형제는 의도적으로 다른 도구로 생성됩니다. Git 형제는 Git 원격 저장소이며, datalad create-sibling-*가 호스팅 서비스의 것을 처리합니다. S3 버킷(또는 WebDAV, SSH 디렉토리)은 git-annex 특수 원격 저장소이므로 Git 원격 저장소가 아니며, 따라서 git annex initremote로 생성됩니다. datalad siblings는 이후에 특수 원격 저장소를 감지하여 다른 것처럼 처리합니다. 여기서 datalad siblings add --url s3://...를 사용하는 것은 이 섹션이 방지하려는 실수입니다. --url은 Git 원격 URL이고 S3는 그렇지 않으며, 아래의 push --to github는 --publish-depends 홉에서 실패합니다.
--publish-depends는 일반적인 손상된 게시를 방지합니다: 이력이 업로드되지 않은 콘텐츠를 참조하는 Git 저장소의 경우, 협업자는 성공적으로 클론한 다음 모든 datalad get이 실패하는 것을 발견합니다. 의존성을 선언하면 매번 스토리지 형제가 먼저 게시됩니다.
datalad push는 Git 이력과, 기본적으로(--data auto-if-wanted) 대상이 원하도록 구성된 관리 콘텐츠를 보냅니다. --data anything을 전달하면 대상의 선호도에 관계없이 모든 콘텐츠를 푸시합니다.
RIA 저장소, 특수 원격 저장소, 자격 증명 처리, 각 형제가 무엇을 보유하는지 구성에 대해서는 publishing.md를 참조하세요.
디스크 공간 확보
git annex whereis sub-01/ # 먼저 다른 복사본이 있는지 확인
datalad drop sub-01/ # 로컬 콘텐츠 제거, 포인터 유지
datalad drop --what all --reckless kill <path> # 최후의 수단, 데이터 파괴
datalad drop은 기본적으로 콘텐츠의 다른 복사본이 존재하는지 확인할 수 없을 때 거부하며, 이는 장애물이 아닌 안전 검사입니다. --nocheck와 --if-dirty는 더 이상 사용되지 않습니다. 현재 철자는 --reckless availability이며, 말 그대로 작동합니다. --what은 filecontent(기본값), allkeys, datasets, all 중에서 선택합니다.
알아두어야 할 실패 패턴
| 증상 | 원인 | 해결책 |
|---|---|---|
| 파일이 비어 있거나, 잘렸거나, 깨진 심볼릭 링크로 읽힘 | 내용이 검색되지 않음; 포인터만 있음 | datalad get <path> |
| 기존 출력에 "Permission denied" 쓰기 오류 | git-annex가 관리 콘텐츠를 쓰기 보호함 | --output으로 선언하거나 datalad unlock <path> 실행 |
datalad run이 시작을 거부함 | 데이터셋에 저장되지 않은 변경 사항이 있음 | 먼저 datalad save를 실행하거나 --explicit 전달 |
datalad drop이 거부함 | 콘텐츠의 검증된 두 번째 복사본이 없음 | 먼저 형제에 푸시하거나 --reckless availability 수락 |
협업자가 클론했지만 모든 get이 실패함 | 콘텐츠 없이 이력만 게시됨 | 스토리지 형제를 게시하고 --publish-depends 설정 |
| 클론 성공, 서브데이터셋 디렉토리가 비어 있음 | 기본적으로 서브데이터셋이 설치되지 않음 | datalad get -n -r . 실행 후 필요한 경로 get |
| 명령어가 불가능하게 동작함 | git-annex가 없거나 너무 오래됨 | datalad wtf --section dependencies |
상세 참고 자료
- data-access.md: 게시된 데이터셋 찾기 (
registry.datalad.org, OpenNeuro, DANDI,datasets.datalad.org및///단축키), 클론 및 get 옵션, 서브데이터셋 처리, annex 콘텐츠 상태, 삭제 및 제거,fsck복구. - provenance.md: STAMPED 원칙과 YODA 레이아웃, 실행 레코드 형식,
run및rerun옵션 전체,containers-run, W3C PROV로 DataLad 과정 내보내기의 현재 상태. - publishing.md: 형제와 그 동작,
create-sibling-*변형, RIA 저장소, 특수 원격 저장소,push의미, 자격 증명 처리.
관련 스킬
bids 스킬은 DataLad를 통해 배포되는 대부분의 신경영상 데이터셋이 구성되는 Brain Imaging Data Structure를 다룹니다. 일반적인 워크플로는 DataLad로 BIDS 데이터셋을 클론하고, BIDS 도구로 검증한 다음, BIDS-앱을 datalad containers-run 하에 실행하여 파생물이 과정을 가지도록 합니다.
주요 출처
- DataLad 문서: https://docs.datalad.org/en/stable/
- DataLad 핸드북: https://handbook.datalad.org/en/latest/
datalad run챕터: https://handbook.datalad.org/en/latest/basics/101-108-run.html- YODA 원칙: https://handbook.datalad.org/en/latest/basics/101-127-yoda.html
- STAMPED 원칙 (YODA에서 운영화됨): https://stamped-principles.org
- datalad-container: https://docs.datalad.org/projects/container/en/stable/
- git-annex: https://git-annex.branchable.com/
- 데이터셋 레지스트리: https://registry.datalad.org
감사의 말
이 스킬의 주제 범위는 @bcmcpher의 MIT 라이선스 [datalad-cli](https://github.com/bcmcpher/my-...
…