fetch

从远程存储下载文件或目录到缓存中。

概要

usage: dvc fetch [-h] [-q | -v] [-j <number>] [-r <name>] [-a] [-T]
                 [--all-commits] [-d] [-R] [--run-cache | --no-run-cache]
                 [--max-size <bytes>] [--type {metrics,plots}]
                 [targets [targets ...]]

positional arguments:
  targets       Limit command scope to these tracked files/directories,
                .dvc files, or stage names.

描述

将被跟踪的文件和目录从dvc remote下载到缓存（不像dvc pull那样将其放置在工作区中）。这使得被跟踪的数据可用于链接（或复制）到工作区（参见dvc checkout）。

Tracked files                Commands
---------------- ---------------------------------

remote storage
     +
     |         +------------+
     | - - - - | dvc fetch  | ++
     v         +------------+   +   +----------+
project's cache                  ++ | dvc pull |
     +         +------------+   +   +----------+
     | - - - - |dvc checkout| ++
     |         +------------+
     v
 workspace

以下是一些使用 dvc fetch 而非 pull 的典型场景：

• 在检出一个 DVC 仓库的新副本后，从多个项目分支或标签获取 DVC 跟踪的数据到本地机器。
• 要在不同的 Git 提交之间使用比较命令，例如带有 --all-branches 选项的 dvc metrics show，或 dvc plots diff。
• 如果你希望避免从缓存中链接文件，或出于其他原因保持工作区干净。

不带参数时，该命令会下载当前工作区中缺失的所有被引用文件和目录（这些信息记录在dvc.yaml 和 .dvc 文件中）。提供给此命令的任何 targets 都会限制要下载的内容。它接受被跟踪文件或目录的路径（包括被跟踪目录内的路径）、.dvc 文件以及阶段名称（定义于dvc.yaml中）。

--all-branches、--all-tags 和 --all-commits 选项可用于获取多个 Git 提交中引用的文件/目录。

所使用的dvc remote按以下顺序确定：

1. 来自 dvc.yaml 或 .dvc 文件中的 remote 字段。
2. 通过 CLI 使用 --remote 选项传入的值。
3. core.remote 配置选项的值（参见 dvc remote default）。

选项

• -r <name>, --remote <name> - 指定要从中获取数据的dvc remote名称（参见dvc remote list）。

• -d, --with-deps - 仅在指定 targets 时有意义。它通过解析目标的所有依赖关系来确定需要下载的文件：DVC 会从相应流水线中的目标节点向后搜索。此操作不会获取在目标阶段之后的阶段中引用的文件。

• -R, --recursive - 通过递归查找每个目标目录及其子目录中的dvc.yaml 和 .dvc 文件来确定需获取的文件。如果 targets 中没有目录，则此选项无效。

• --run-cache, --no-run-cache - 是否从远程仓库下载所有可用的阶段运行历史。详见 dvc push 中的相同选项。默认为“--no-run-cache”。

• -j <number>, --jobs <number> - 设置 DVC 从远程存储下载数据时的并行任务数量。默认值为 4 * cpu_count()。注意，可以通过 dvc remote modify 的 jobs 配置项设置默认值。使用更多任务数可能加快操作速度。

• -a, --all-branches - 获取所有 Git 分支以及工作区的缓存。这意味着 DVC 可能会下载用于复现某个.dvc文件不同版本所需的文件，而不仅仅是当前工作区中存在的那些文件。注意，此选项可与下方的 -T 组合使用，例如通过 -aT 标志。

• -T，--all-tags - 获取所有 Git 标签的缓存，以及工作区的缓存。请注意，这可以与上面的 -a 结合使用，例如使用 -aT 参数。

• -A，--all-commits - 获取所有 Git 提交的缓存，以及工作区的缓存。这将下载项目整个提交历史中被跟踪的数据。

• --max-size <bytes> - 获取每个小于指定大小（字节）的数据文件/目录。注意：该大小由 .dvc/dvc.lock 文件中对应的 size 字段决定。这意味着即使某些文件或子目录在 DVC 跟踪的目录内部更小，整个目录仍会被跳过。

• --type <type> - 获取特定类型的文件/目录。目前仅支持 metrics 和 plots。

• -h, --help - 打印使用说明/帮助信息，然后退出。

• -q, --quiet - 不向标准输出写入任何内容。如果没有问题则以 0 退出，否则以 1 退出。

• -v, --verbose - 显示详细的跟踪信息。

示例

让我们使用一个包含一些数据、代码、机器学习模型和流水线阶段的简单 工作区，比如为快速入门创建的DVC 项目。然后我们可以查看在不同场景下dvc fetch 的行为。

$ git clone https://github.com/iterative/example-get-started
$ cd example-get-started

工作区结构如下：

.
├── data
│   └── data.xml.dvc
├── dvc.lock
├── dvc.yaml
├── params.yaml
├── prc.json
├── scores.json
└── src
    └── <code files here>

该项目附带了一个预定义的 HTTP 远程存储。我们现在只需运行 dvc fetch，即可将最新的 model.pkl、data.xml 及其他 DVC 跟踪的文件下载到本地 缓存中。

$ dvc status --cloud
...
	deleted:            data/features/train.pkl
	deleted:            model.pkl

$ dvc fetch

$ tree .dvc/cache/files/md5
.dvc/cache/files/md5
├── 20
│   └── b786b6e6f80e2b3fcf17827ad18597.dir
├── c8
│    ├── d307aa005d6974a8525550956d5fb3
│    └── ...
...

dvc status --cloud 将缓存内容与默认远程仓库进行比较。请参考 dvc status。

请注意，已创建并填充了 .dvc/cache 目录。

当前项目版本所需的所有数据现在都已进入你的缓存：20b786b... 和 c8d307a... 这些文件名分别对应 data/features/ 目录和 model.pkl 文件。

要将这些文件链接到工作区：

$ dvc checkout

示例：指定具体文件或目录

如果你尝试过前面的例子，请先删除 .dvc/cache 目录（例如执行 rm -Rf .dvc/cache），以便继续本示例。

dvc fetch 仅下载与给定 targets 对应的被跟踪数据：

$ dvc fetch prepare

$ tree .dvc/cache/files/md5
.dvc/cache/files/md5
├── 20
│   └── b786b6e6f80e2b3fcf17827ad18597.dir
├── 32
│   └── b715ef0d71ff4c9e61f55b09c15e75
└── 6f
    └── 597d341ceb7d8fbbe88859a892ef81

已下载 data/prepared 目录（输出自 prepare 目标）的缓存条目，以及实际的 test.tsv 和 train.tsv 文件。它们的哈希值如上所示。

请注意，你可以在被跟踪的目录内获取数据。例如，featurize 阶段以整个 data/features 目录作为输出，但我们也可以只获取其中部分内容：

$ dvc fetch data/features/test.pkl

如果再次检查 .dvc/cache，你会看到又下载了几个文件：data/features 目录的缓存条目，以及 data/features/test.pkl 本身。

示例：包含依赖关系

在完成前面的示例（特定阶段）后，只有与 prepare 阶段相关的文件被获取。其他流水线阶段的一些依赖项/输出仍然缺失：

$ dvc status -c
...
    deleted:            data/features/test.pkl
    deleted:            data/features/train.pkl
    deleted:            model.pkl

你可以简单地执行一次 dvc fetch 来获取所有数据，但如果你只想获取到第三个阶段 train 所需的数据呢？我们可以使用 --with-deps（或 -d）选项：

$ dvc fetch --with-deps train

$ tree .dvc/cache/files/md5
.dvc/cache/files/md5
├── 20
│   └── b786b6e6f80e2b3fcf17827ad18597.dir
├── c8
│   ├── 43577f9da31eab5ddd3a2cf1465f9b
│   └── d307aa005d6974a8525550956d5fb3
├── 32
│   └── b715ef0d71ff4c9e61f55b09c15e75
├── 54
│   └── c0f3ef1f379563e0b9ba4accae6807
├── 6f
│   └── 597d341ceb7d8fbbe88859a892ef81
├── a1
│   └── 414b22382ffbb76a153ab1f0d69241.dir
└── a3
    └── 04afb96060aad90176268345e10355

使用 --with-deps 获取时，会从目标阶段（train）开始，并向后搜索其管道中的数据，将其下载到项目的缓存中。现在，第二和第三阶段（featurize 和 train）的所有数据都已下载到缓存中。我们现在可以使用 dvc checkout 将工作区中用于复现此管道至第三阶段所需的数据文件恢复出来（配合使用 dvc repro train）。

请注意，在此示例项目中，最后一个阶段 evaluate 并未添加比之前阶段更多的数据文件，因此此时该管道的所有数据均已缓存，且 dvc status -c 将输出 Cache and remote 'storage' are in sync.