push

根据当前的 dvc 文件，将被追踪的文件或目录上传到远程存储。

概要

usage: dvc push [-h] [-q | -v] [-j <number>] [-r <name>] [-a] [-T]
                [--all-commits] [--glob] [-d] [-R]
                [--run-cache | --no-run-cache]
                [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 push 将数据从缓存上传到一个 dvc remote。

请注意，推送数据不会影响代码、dvc.yaml 或 .dvc 文件。这些文件应通过 git push 上传。此命令也会忽略 dvc import 的数据。

所使用的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 提供了一个 Git 钩子，可在执行 git push 后自动运行 dvc push。更多详情请参见 dvc install。

对于每个目标中引用的所有输出，DVC 会在缓存中查找对应的文件和目录（通过 dvc.lock 和 .dvc 文件中保存的哈希值识别）。然后 DVC 汇总出远程存储中缺失的文件列表，并将其上传。

注意：dvc status -c 命令可以列出 DVC 跟踪但在缓存中新出现的文件（相对于默认远程而言）。你可以用它来预览 dvc push 将要上传哪些文件。

选项

-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 中指定目录，则此选项无效。
-r <name>, --remote <name> - 指定要推送到的 dvc remote 名称（参见 dvc remote list）。
--run-cache, --no-run-cache - 是否将所有可用的阶段运行历史上传到dvc remote。默认值为 --no-run-cache。
-j <number>, --jobs <number> - DVC 上传数据到远程存储时使用的并行任务数。默认值为 4 * cpu_count()。注意，可以通过 dvc remote modify 命令设置 jobs 配置项来自定义默认值。使用更多任务可能加快操作速度。
--glob - 允许推送与 targets 中指定的模式匹配的文件和目录。支持 Shell 风格通配符：*、?、[seq]、[!seq] 和 **。
-h, --help - 打印使用说明/帮助信息，然后退出。
-q, --quiet - 不向标准输出写入任何内容。如果没有问题则以 0 退出，否则以 1 退出。
-v, --verbose - 显示详细的跟踪信息。

示例

使用 dvc push（不带选项）时，必须已定义一个dvc remote default（另请参见 dvc remote add --default）。以下是一个 SSH 远程示例：

$ dvc remote add --default r1 \
                 ssh://user@example.com/project/data/cache

对于已存在的项目，远程存储通常已经配置好。可以使用 dvc remote list 来查看它们：

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

将当前工作区的完整数据缓存推送到默认远程：

$ dvc push

仅推送与特定 .dvc 文件相关的文件：

$ dvc push data.zip.dvc

示例：包含依赖关系

演示 --with-deps 选项需要一个更复杂的例子。首先，假设已建立一个包含以下流水线的阶段：clean-posts、featurize、test-posts、matrix-train。

设想该项目已被修改，导致其中某些阶段的输出需要上传到远程存储。

$ dvc status --cloud
...
	new:            data/model.p
	new:            data/matrix-test.p
	new:            data/matrix-train.p

可以执行简单的 dvc push 来共享所有数据，但如果只想上传部分数据怎么办？

$ dvc push --with-deps test-posts

# Do some work based on the partial update...
# Then push the rest of the data:

$ dvc push --with-deps matrix-train

$ dvc status --cloud
Cache and remote 'r1' are in sync.

第一次推送时，我们指定了流水线中间的一个阶段（test-posts）。--with-deps 使 DVC 从该.dvc 文件开始，反向遍历流水线以查找需上传的数据文件。

由于 matrix-train 阶段发生在之后（它是最后一个阶段），其数据未被推送。但在第二次推送中我们指定了它，因此剩余的所有数据都被上传。

最后，我们使用 dvc status 再次确认所有数据均已上传。

示例：缓存中发生了什么？

让我们详细看看，在本地运行实验并将数据推送到远程存储时，缓存目录会发生什么变化。以一个已创建的项目为例，该项目包含一些代码、数据以及已配置好的dvc remote。

一些工作已在工作区中完成，新数据已准备上传到远程。运行 dvc status --cloud 将列出多个处于 new 状态的文件。我们可以通过查看项目中的缓存来确切了解其含义：

$ tree .dvc/cache/files/md5
.dvc/cache/files/md5
├── 02
│   └── 423d88d184649a7157a64f28af5a73
├── 0b
│   └── d48000c6a4e359f4b81285abf059b5
├── 38
│   └── 64e70211d3bdb367ad1432bfc14c1f.dir
├── 4a
│   └── 8c47036c79c01522e79ac0f518d0f7
├── 6c
│   └── 3074754e3a9b563b62c8f1a38670dc
├── 77
│   └── bea77463abe2b7c6b4d13f00d2c7b4
└── 88
    └── c3db1c257136090dbb4a7ddf31e678.dir

10 directories, 9 files

$ tree ~/vault/recursive/files/md5
~/vault/recursive/files/md5
├── 0b
│   └── d48000c6a4e359f4b81285abf059b5
├── 4a
│   └── 8c47036c79c01522e79ac0f518d0f7
└── 88
    └── c3db1c257136090dbb4a7ddf31e678.dir

5 directories, 5 files

目录 .dvc/cache 是本地缓存，而 ~/vault/recursive 是一个“本地远程”（即本地文件系统中的另一个目录）。该列表显示缓存中的文件数量多于远程端——这正是 new 状态的含义。

更多信息请参见缓存目录的结构。

接下来，我们可以使用 dvc push 将剩余的数据从缓存复制到远程：

$ tree ~/vault/recursive
~/vault/recursive
├── 02
│   └── 423d88d184649a7157a64f28af5a73
├── 0b
│   └── d48000c6a4e359f4b81285abf059b5
├── 38
│   └── 64e70211d3bdb367ad1432bfc14c1f.dir
├── 4a
│   └── 8c47036c79c01522e79ac0f518d0f7
├── 6c
│   └── 3074754e3a9b563b62c8f1a38670dc
├── 77
│   └── bea77463abe2b7c6b4d13f00d2c7b4
└── 88
    └── c3db1c257136090dbb4a7ddf31e678.dir

10 directories, 10 files

$ dvc status --cloud
Cache and remote 'r1' are in sync.

再次运行 dvc status --cloud，DVC 会确认确实没有更多文件需要推送到远程存储。