add

使用 DVC 跟踪数据文件或目录。

概要

usage: dvc add [-h] [-q | -v] [-f] [--no-commit]
               [--glob] [-o <path>]
               [--to-remote] [-r <name>] [--remote-jobs <number>]
               [--no-relink]
               targets [targets ...]
positional arguments:
  targets               Files or directories to add or update

描述

DVC 允许使用 .dvc 文件作为指向数据的轻量级指针来跟踪数据集。dvc add 命令通过创建或更新 .dvc 文件来跟踪和更新你的数据。

使用 dvc add，你可以通过指定要跟踪的目标，无缝地跟踪数据集、模型或大文件。DVC 会管理相应的 .dvc 文件，确保数据与工作区的一致性。

targets 可以是单个文件、目录，或已跟踪数据集内的特定路径。对于尚未被跟踪的新文件和目录，DVC 将创建新的 .dvc 文件来跟踪新增的数据，并将其存储在缓存中。

如果目标是现有数据集的一部分，则仅更新该部分数据集，并更新相关的 .dvc 文件以反映更改。如果目标路径在工作区中不存在但之前已被跟踪，则它将从数据集中移除，并相应地更新 .dvc 文件。

借助 .dvc 文件中的元数据和缓存结构，数据集无需完整存在于工作区中即可进行更新。你可以部分拉取数据集并在其上操作，DVC 将自动更新相关 .dvc 文件以反映变更。此功能使你能够处理大型数据集而无需将整个数据集下载到本地机器。

此命令可用于跟踪 Git 无法直接处理的大型文件、模型、数据集目录等，从而实现通过 Git 对它们进行间接的版本管理。

有关跟踪和版本化中间及最终结果（如机器学习模型）的更高级方法，请参见 dvc.yaml 和 dvc stage add。

该命令会将 targets 添加到 .gitignore 中，防止它们被提交至 Git 仓库（除非初始化DVC 项目时使用了 dvc init --no-scm）。如果设置了 core.autostage，生成的 .dvc 文件可自动暂存。

若要排除特定文件或目录不被添加，可在 .dvcignore 文件中添加相应的匹配模式。

你也可以撤销 dvc add 操作，停止对文件或目录的跟踪。

默认情况下，DVC 会尝试使用 reflinks（参见文件链接类型）以避免复制文件内容，并优化大文件的 .dvc 文件操作。DVC 还支持其他类型的链接，用于不支持 reflink 的文件系统，但需要手动指定。更多信息请参考 dvc config cache 中的 cache.type 配置选项。

添加整个目录

`dvc add` 的目标可以是文件或目录。在后一种情况下，会在目录层级的顶部创建一个 `.dvc` 文件（默认名称为 `.dvc`）。

目录中的每个文件都会被正常缓存（除非使用了 `--no-commit` 选项），但 DVC 不会为每个文件单独生成 `.dvc` 文件。相反，单个 `.dvc` 文件会引用缓存中的一个特殊 JSON 文件（扩展名为 `.dir`），该 JSON 文件再指向被添加的各个文件。

有关 `.dir` 缓存条目的更多信息，请参阅缓存目录结构。

请注意，使用被追踪数据的 DVC 命令支持对文件和目录进行细粒度操作，即使这些文件或目录位于作为整体添加的父目录中。例如：dvc push、dvc pull、dvc get、dvc import 等。

为避免意外将目录内的文件加入 DVC，可将相应的匹配模式添加到 `.dvcignore` 文件中。

添加符号链接目标

`dvc add` 支持将符号链接文件作为 `targets`。但如果目标路径是一个目录的符号链接，或包含任何中间目录的符号链接，则无法将其添加到 DVC 中。

例如，给定以下项目结构：

.
├── .dvc
├── dir
│   └── file
├── link_to_dir -> dir
├── link_to_external_dir -> /path/to/dir
├── link_to_external_file -> /path/to/file
└── link_to_file -> dir/file

`link_to_file` 和 `link_to_external_file` 都是有效的符号链接目标，可用于 `dvc add`。但 `link_to_dir`、`link_to_external_dir` 和 `link_to_dir/file` 则无效。

选项

`--no-commit` - 不将 `targets` 存储到缓存中（仍会创建 `.dvc` 文件）。请使用 `dvc commit` 完成操作（类似于 `git add` 后执行 `git commit`）。
`--glob` - 允许添加与 `targets` 中指定的模式匹配的文件和目录。支持 Shell 风格通配符：`*`、`?`、`[seq]`、`[!seq]` 和 `**`
`-o `、`--out ` - 指定工作区中的目标路径，用于放置 `targets`（从当前位置复制过来）。此选项支持引入项目外部的数据。
`--to-remote` - 添加项目外部的目标，既不将其移入工作区，也不缓存在本地，而是直接传输到远程存储（除非通过 `-r` 明确指定，否则使用默认远程）。该选项隐含 `--out .`。使用 `dvc pull` 可将数据拉取到本地。
`-r `、`--remote ` - 指定用于传输外部目标的 dvc remote 名称（仅可与 `--to-remote` 一起使用）。
`--remote-jobs ` - 使用 `--to-remote` 时，DVC 传输数据的并行任务数。默认值为 `4 * cpu_count()`。对于 SSH 远程存储，默认值为 `4`。使用更多任务可能加快操作速度。
-f, --force - 当使用 --out 指定本地目标文件或目录时，如果这些路径已存在，操作将失败。使用此标志会强制执行操作，导致命令覆盖现有的本地文件/目录。
--no-relink - 不从缓存重新创建文件链接类型到工作区。在处理大量文件时可节省时间，但即使配置了其他链接类型，文件仍可能从缓存中重新建立硬链接或被复制。
-h, --help - 打印使用说明/帮助信息，然后退出。
-q, --quiet - 不向标准输出写入任何内容。如果没有问题则以 0 退出，否则以 1 退出。
-v, --verbose - 显示详细的跟踪信息。

示例：单个文件

使用 DVC 跟踪一个文件：

$ dvc add data.xml

如上所示，已为 data.xml 创建了一个 .dvc 文件。让我们查看结果：

$ tree
.
├── data.xml
└── data.xml.dvc

让我们检查一下 data.xml.dvc 文件的内容：

outs:
  - md5: 6137cde4893c59f76f005a8123d8e8e6
    path: data.xml

这是一个标准的 .dvc 文件，仅包含一个输出（outs 字段）。哈希值（md5 字段）对应于缓存中的一个文件路径。

$ file .dvc/cache/files/md5/d8/acabbfd4ee51c95da5d7628c7ef74b
.dvc/cache/files/md5/61/37cde4893c59f76f005a8123d8e8e6: ASCII text

⚠️ 不建议跟踪压缩文件（例如 ZIP 或 TAR 归档文件），因为 dvc add 支持直接跟踪目录（详见下文）。

示例：目录

假设你的目标是构建一个识别图片中猫和狗的算法。你可能会在一个目录中存放数百或数千张这些动物的图片，这就是你的训练数据集：

$ tree pics --filelimit 3
pics
├── train
│   ├── cats [many image files]
│   └── dogs [many image files]
└── validation
    ├── cats [more image files]
    └── dogs [more image files]

使用 DVC 跟踪一个目录，就像跟踪单个文件一样简单：

$ dvc add pics

在此目录结构中不会为每张图片生成单独的 .dvc 文件，但所有图片文件都会被缓存。会在顶层目录生成一个单独的 pics.dvc 文件，其内容如下：

outs:
  - md5: ce57450aa92ab8f2b957c24b0df73edc.dir
    path: pics

更多信息请参考添加整个目录。

这使我们能够将整个目录结构视为单一的数据产物。例如，你可以将其作为依赖项传递给某个阶段定义：

$ dvc stage add -n train \
                -d train.py -d pics \
                -M metrics.json -o model.h5 \
                python train.py

要尝试此示例，请参阅版本控制教程。

示例 .dvcignore

我们通过一个例子来说明 .dvcignore 如何与 dvc add 交互。

$ mkdir dir
$ echo file_one > dir/file1
$ echo file_two > dir/file2

现在将 file1 添加到 .dvcignore，并使用 dvc add 跟踪整个 dir 目录。

$ echo dir/file1 > .dvcignore
$ dvc add dir

现在修改 file1（已在 .dvcignore 中列出），然后运行 dvc status：

$ echo file_one_changed > dir/file1
$ dvc status
Data and pipelines are up to date.

dvc status 会忽略 .dvcignore 中列出文件的更改。

让我们查看缓存目录：

$ tree .dvc/cache/files/md5
.dvc/cache/files/md5
├── 0a
│   └── ec3a687bd65c3e6a13e3cf20f3a6b2.dir
└── 52
    └── 4bcc8502a70ac49bf441db350eafc2

只有 dir/ 目录（带有 .dir 文件扩展名）和 file2 的哈希值被缓存了。

示例：传输到远程存储

有时本地环境没有足够的空间导入大型数据集，但仍希望在项目中对其进行跟踪，以便后续可通过 dvc pull 下载该数据集。

只要您已设置一个能够处理数据的 dvc remote，就可以通过使用 --to-remote 标志来实现。它会创建一个 .dvc 文件而不下载任何内容，而是将目标直接传输到远程存储。

让我们通过 HTTP 将一个 data.xml 文件直接“添加到远程”：

$ dvc add https://data.dvc.org/get-started/data.xml --to-remote
...
$ ls
data.xml.dvc

由于在工作区中创建了一个 .dvc 文件，因此每当有人需要实际下载数据时，他们都可以使用 dvc pull：

$ dvc pull data.xml.dvc
A       data.xml
1 file added

请注意，您也可以使用 dvc import-url 来完成此操作。这样做的额外好处是能保持与数据源的连接，以便日后更新（使用 dvc update）。