用途
DataLad 是 Git 与 git-annex 之上的数据管理层，面向需要版本化、分发和复现的科学数据集。Git 负责数据集结构、小型文本文件与历史；git-annex 负责大文件内容，把每个文件存为键，字节可以存放在本地仓库之外。这一分工意味着：新克隆的数据集包含完整历史和文件清单，但几乎不含数据内容，100 TB 的数据集可在数秒内克隆完成、仅占几 MB，实际字节需按文件用 datalad get 取回。
主要能力
- 数据获取与版本化：datalad clone、datalad get、datalad status --annex、git annex whereis 等用于克隆、按路径或递归取回内容、查看本地已有内容量以及哪些仓库持有某文件。whereis 读取的是记录状态，不会联系远端。
- 计算溯源：datalad run 执行命令并在同一提交中保存命令、输入与输出，形成机器可读运行记录；datalad rerun 读取该记录并重新执行，支持 --report 预览、--script 仅提取命令、-b 重放到新分支以便与原分支对比。
- 容器化运行：安装 datalad-container 后，用 datalad containers-add 登记镜像，containers-run 运行命令并记录所用镜像，使软件环境随数据和溯源一起保存。
- 保存与检查：datalad save 按 .gitattributes 决定文件进入 Git 还是 git-annex，--to-git 可强制小文本与代码留在 Git；datalad status 显示变更，包括子数据集状态。
- 数据集创建：datalad create 创建普通数据集，-c yoda 应用分析项目布局（code/ 由 Git 跟踪，README.md 与 CHANGELOG.md 预配置），-d . 将新数据集注册为父数据集的子数据集。
- 发布：通常同时发布到 Git 托管服务（保存历史）与存储远端（保存 annex 内容）。Git sibling 用 datalad create-sibling-* 创建，S3/WebDAV/SSH 等存储用 git annex initremote 创建为 special remote，再由 datalad siblings 识别；--publish-depends 确保存储先发布，避免他人克隆成功但每次 get 失败。
- 释放磁盘空间：先用 git annex whereis 确认存在另一份副本，再 datalad drop 删除本地内容保留指针；--reckless availability 是当前拼写，--nocheck 与 --if-dirty 已废弃。
使用方式
安装：uv pip install git-annex（PyPI 提供 Linux、macOS、Windows 预编译 wheel，但不附带 git），也可从系统包管理器安装；随后 uv pip install datalad，需要容器运行时再装 datalad-container。datalad wtf --section dependencies 用于确认 git-annex 版本可见。典型流程：克隆数据集、按需 datalad get、用 datalad run 记录分析、需要复现时 datalad rerun 重放，最后推送到配置好的 sibling。
适用场景
文件过大或总量超出协作者磁盘容量；数据分布在多个位置且需知道副本情况；分析必须可重新执行且提交信息不足以作为证据；使用 OpenNeuro、DANDI、datasets.datalad.org 等以 DataLad 分发的数据集；项目嵌套其他数据集且各自需要独立历史。若仓库只有代码和文本、全部内容可轻松放入 Git、无需部分检出，则纯 Git 更合适。
限制与常见失败
- 指针不是数据：克隆后 annex 文件是指向 .git/annex/objects/ 的符号链接（Windows 等环境为小指针文件），工具可能报文件为空、截断、损坏或不是 gzip 文件，磁盘大小仅数百字节，此时应先 datalad get，不能把“文件存在”当作内容已就位。
- 写入已有输出时报权限错误：git-annex 会写保护 annex 内容，需用 --output 声明输出或先 datalad unlock。
- datalad run 拒绝启动：数据集存在未保存修改，应先 save 或传 --explicit。
- datalad drop 拒绝：无法验证存在第二份副本，应先推送或接受 --reckless availability。
- 克隆成功但子数据集目录为空：子数据集默认不安装，需 datalad get -n -r . 再取所需路径。
- 命令行为异常：多为 git-annex 缺失或过旧，用 datalad wtf 检查。
- 许可：DataLad 为 MIT，git-annex 为 AGPL，仅在再分发修改过的 git-annex 时有影响。
关联与来源
相关技能 BIDS 覆盖多数神经影像数据集所用的 Brain Imaging Data Structure；典型流程是用 DataLad 克隆 BIDS 数据集、用 BIDS 工具校验、再在 datalad containers-run 下运行 BIDS-App 使衍生结果携带溯源。主要来源为 DataLad 文档、DataLad Handbook、datalad run 章节、YODA 与 STAMPED 原则、datalad-container 文档、git-annex 站点与数据集注册表。文档还列出代理操作流程与完整性规则（不编造结果、参数、标识或统计，未计算不报告指标，版本相关细节需对照已安装版本的官方文档）。