pull

根据当前的远程存储中的 dvc.yaml 和 .dvc 文件，下载被追踪的文件或目录，并使其在工作区中可见。

概要

usage: dvc pull [-h] [-q | -v] [-j <number>] [-r <name>] [-a] [-T]
                [-d] [-f] [-R] [--all-commits]
                [--run-cache | --no-run-cache] [--allow-missing]
                [targets [targets ...]]

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

描述

dvc push 和 dvc pull 命令用于将数据上传和下载到/自远程存储（如 S3、SSH、GCS 等）。这两个命令分别类似于 git push 和 git pull。跨环境的数据共享以及远程保存数据版本（输入数据集、中间结果、模型、dvc metrics 等）是这些命令最常见的使用场景。

dvc pull 会从 dvc remote 下载被追踪的数据到缓存中，并通过链接（或复制）方式将文件或目录放入工作区（参见 dvc config cache.type）。

请注意，拉取数据不会影响代码、dvc.yaml 或 .dvc 文件。这些内容应通过 git pull 下载。

其效果等同于依次运行 dvc fetch 和 dvc checkout：

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

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

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

来自 dvc.yaml 或 .dvc 文件中的 remote 字段。
通过 CLI 传递给 --remote (-r) 选项的值。
core.remote 配置选项的值（参见 dvc remote default）。

不带参数时，它会下载当前工作区中引用的所有文件和目录（在 dvc.yaml 和 .dvc 文件中定义），但缺失于工作区中的部分。提供给该命令的任何 targets 参数将限制拉取的内容范围。它接受指向被追踪文件或目录的路径（包括被追踪目录内的路径）、.dvc 文件以及阶段名称（在 dvc.yaml 中定义）。

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

数据进入缓存后，dvc pull 会使用操作系统特定的机制（如 reflinks 或硬链接）将其放入工作区，尽量避免实际复制。更多细节请参见 dvc checkout。

请注意，命令 dvc status -c 可以列出当前阶段（在 dvc.yaml 中）或 .dvc 文件中引用但缺失于缓存中的文件。可用于查看 dvc pull 将要下载哪些文件。

选项

-a, --all-branches - 通过检查所有 Git 分支以及工作区中的 dvc.yaml 和 .dvc 元文件来确定要下载的文件。如果使用分支来追踪实验，则此选项非常有用。注意，此选项可与下方的 -T 组合使用，例如使用 -aT 标志。
-T, --all-tags - 检查所有 Git 标签以及工作区中的元文件。如果使用标签标记实验或项目的特定版本，则此选项非常有用。注意，此选项可与上方的 -a 组合使用，例如使用 -aT 标志。
-A, --all-commits - 检查所有 Git 提交中的元文件，以及工作区中的文件。这将下载项目整个提交历史中被跟踪的数据。
-d, --with-deps - 仅在指定 targets 时有意义。该选项通过解析目标的所有依赖关系来确定要拉取的文件：DVC 会从相应管道中的目标节点向前追溯。但不会拉取在目标阶段之后的阶段中引用的文件。
-R, --recursive - 通过在每个目标目录及其子目录中搜索 dvc.yaml 和 .dvc 文件来确定需要拉取的文件。如果 targets 中不包含任何目录，则此选项无效。
-f, --force - 当移除工作区文件时不再提示，这种情况通常发生在这些文件不再与当前 stage 或 .dvc 文件匹配时。此行为源自 dvc fetch 和 dvc checkout 命令，因为 dvc pull 实际上是将这两个命令的功能合并在了一起。
-r <name>, --remote <name> - 指定要从中拉取数据的 dvc remote 名称（参见 dvc remote list）。
--run-cache, --no-run-cache - 是否从 dvc remote 下载所有可用的阶段运行历史（仅下载到缓存中，类似于 dvc fetch --run-cache）。请注意，需要运行 dvc repro <stage_name> 才能将这些文件检出到工作区，并更新 dvc.lock。默认值为 --no-run-cache。
--allow-missing - 即使某些文件或目录缺失，也允许命令执行成功。
-j <number>, --jobs <number> - 设置 DVC 从远程存储下载数据时的并行任务数量。默认值为 4 * cpu_count()。注意，可以通过 dvc remote modify 的 jobs 配置项设置默认值。使用更多任务数可能加快操作速度。
-h, --help - 打印使用说明/帮助信息，然后退出。
-q, --quiet - 不向标准输出写入任何内容。如果没有问题则以 0 退出，否则以 1 退出。
-v, --verbose - 显示详细的跟踪信息。

示例

让我们使用一个包含一些数据、代码、机器学习模型和流水线阶段的简单工作区，例如为入门指南创建的 DVC 项目。然后我们可以观察 dvc pull 的实际效果。

点击并展开以设置项目

如果你还没有该项目，请先克隆我们的示例仓库：

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

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

现在我们只需运行 dvc pull，即可将最新的 data/data.xml、model.pkl 以及其他由 DVC 跟踪的文件下载到工作区：

$ dvc pull

$ tree
.
├── data
│   ├── data.xml
│   ├── data.xml.dvc
...
└── model.pkl

我们也可以只下载某个特定阶段的输出：

$ dvc pull train

示例：包含依赖关系

如果你之前运行过前面的例子，请先删除 .dvc/cache 目录（使用 rm -Rf .dvc/cache），以便正确执行本示例。

我们的流水线已配置了以下阶段：prepare、featurize、train、evaluate。

假设已修改了 dvc remote，使得该工作流中某些阶段的数据需要在 workspace 中更新。

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

可以简单地执行 dvc pull 来获取所有数据，但如果只想获取部分数据该怎么办？

$ dvc pull --with-deps featurize

# Use the partial update...
# Then pull the remaining data:

$ dvc pull
Everything is up to date.

在第一次使用 dvc pull 时，我们指定了此工作流中的一个中间阶段（featurize），并使用了 --with-deps 参数。DVC 从该阶段开始，反向遍历整个工作流以下载所需的数据文件。随后我们再次运行 dvc pull 来下载其余的所有数据文件。

示例：从特定的远程存储下载

使用 dvc pull 命令前，必须定义一个 dvc remote 存储位置。对于已存在的项目，远程存储通常已经配置好，你可以使用 dvc remote list 查看它们。为了回顾配置方法并为示例提供上下文，我们来定义一个默认的 SSH 远程存储：

$ dvc remote add -d r1 \
                 ssh://user@example.com/project/data/cache
$ dvc remote list
r1    ssh://user@example.com/project/data/cache   (default)
r2    ssh://user@example.com/other/storage

请注意，当你运行 dvc remote list 时，也会显示默认远程存储（如果已设置）。

DVC 支持多种存储类型。

要从特定远程存储下载 DVC 跟踪的数据，请使用 dvc pull 的 --remote (-r) 选项：

$ dvc pull --remote r1