status

显示项目 管道 中的更改，以及 缓存 与 工作区 之间或缓存与 远程存储 之间的文件不匹配情况。

概要

usage: dvc status [-h] [-v] [-j <number>] [-q] [-c] [-r <name>] [-a] [-T]
                  [--all-commits] [-d] [-R] [--json] [--no-updates]
                  [targets [targets ...]]

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

描述

搜索现有已跟踪数据和管道中的变更。在本地模式下，它会显示工作区中哪些文件或目录发生了变化（因此可以再次 添加 或 重新运行）。在远程模式下，它报告缓存与 远程存储 之间的差异（可使用 dvc push 或 dvc pull 来同步这些内容）。

不带参数时，此命令会检查所有 dvc.yaml 和 .dvc 文件，以重建并验证管道。然后将这些文件中定义的 输出 与工作区中的实际数据进行比较。

为此命令提供的任何 targets 都会限制其显示更改的范围。它接受指向已跟踪文件或目录的路径（包括已跟踪目录内的路径）、.dvc 文件以及阶段名称（位于 dvc.yaml 中）。

--all-branches、--all-tags 和 --all-commits 选项可用于一次性比较多个 Git 提交中引用的 DVC 跟踪文件。

如果未检测到差异，dvc status 将输出 Data and pipelines are up to date，或者当使用 -c 或 -r 选项时输出 Cache and remote 'myremote' are in sync。如果检测到差异，则列出每个阶段的 依赖项 和/或 输出 的变更。对于列出的每一项，会显示文件名或哈希值，并附带一个状态描述，如下所述。

本地工作区状态

• changed checksum 表示 .dvc 文件的哈希值已更改（例如有人手动编辑了该文件）。

• always changed 表示该阶段（在 dvc.yaml 中）既没有依赖项也没有输出，或者设置了 always_changed 字段为 true（参见 dvc stage add --always-changed）。

• changed deps 或 changed outs 表示该阶段或 .dvc 文件所跟踪的依赖项或输出发生了变化。根据具体用例，可以使用诸如 dvc commit、dvc repro 或 dvc exp run 等命令来更新文件。可能的状态包括：

  • new：在 工作区 中发现了 输出，但尚未在 dvc.lock 或 .dvc 文件中保存对应的文件哈希。
  • modified：在工作区中发现了输出或依赖项，但其在 dvc.lock 或 .dvc 文件中的对应文件哈希不是最新的。
  • deleted：输出或依赖项在 dvc.lock 或 .dvc 文件中有引用，但在工作区中不存在。
  • not in cache：输出存在于工作区中，并且其在 dvc.lock 或 .dvc 文件中的对应文件哈希是最新的，但没有相应的缓存文件或目录。

• update available 表示一个导入阶段已过时（原始数据源已更改）。可通过使用 dvc update 将导入的数据更新到最新版本。

与远程存储的比较

• new 表示该文件/目录存在于缓存中，但不存在于远程存储中。
• deleted 表示该文件/目录不存在于缓存中，但存在于远程存储中。
• missing 表示该文件/目录既不在缓存中，也不在远程存储中。

对于 new 和 deleted 数据，缓存与远程存储不同。要使两者同步，需要使用 dvc pull 或 dvc push。

对于 missing 数据，无法从存储中恢复任何内容。例如，在克隆新的DVC 仓库时，如果原始仓库未上传数据，或者在某些使用了 dvc gc 的情况下，就可能发生这种情况。你可以尝试使用 dvc repro 在本地重新生成输出，然后使用 dvc push 将其推送到远程。

选项

• -c, --cloud - 启用与dvc remote的比较。如果不使用 --remote 选项，DVC 将与dvc remote default进行比较（参见 dvc config core.remote）。

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

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

• -a, --all-branches - 将缓存内容与所有 Git 分支以及当前工作区进行比较。这相当于在此仓库的每个分支上运行相同的 status 命令。状态输出中会显示对应的分支。仅当指定了 --cloud 或 -r 远程时才生效。注意，此选项可与下面的 -T 组合使用，例如使用 -aT 标志。

• -T, --all-tags - 将缓存内容与所有 Git 标签以及工作区进行比较。注意，此选项可与上面的 -a 组合使用，例如使用 -aT 标志。

• -A, --all-commits - 将缓存内容与所有 Git 提交以及工作区进行比较。这会针对项目整个提交历史中的缓存内容进行比对。

• -d, --with-deps - 仅在指定 targets 时有意义。此选项通过解析目标的所有依赖关系来确定需检查的文件：DVC 会从相应管道中的目标节点向前追溯。该选项不会显示发生在 targets 之后阶段的变更。

• -R, --recursive - 通过对每个目标目录及其子目录进行搜索，查找其中的阶段（在 dvc.yaml 中定义）和 .dvc 文件来进行状态检查。如果目标中不包含任何目录，则此选项无效。

• -r <name>, --remote <name> - 指定要对比的 dvc remote 名称（参见 dvc remote list）。该选项隐含启用 --cloud。

• --json - 以易于解析的 JSON 格式输出命令结果，而非人类可读的表格形式。

• --no-updates - 忽略对 导入阶段（import stages） 的更新检查。默认情况下，dvc status 会检查其源端是否有可用更新。--no-updates 将跳过这些检查。

• -j <number>, --jobs <number> - 指定 DVC 从远程存储读取数据时的并行任务数量。仅当使用 --cloud 选项或指定了 --remote 时生效。默认值为 4 * cpu_count()。注意，可通过 dvc remote modify 命令设置 jobs 配置项来自定义默认值。增加任务数可能加快操作速度。

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

• -q, --quiet - 不向标准输出写入任何内容。若数据和管道均为最新则返回退出码 0，否则返回 1。

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

示例

$ dvc status
baz.dvc:
	changed outs:
		modified:           baz
dofoo:
	changed deps:
		modified:           baz
	changed outs:
		modified:           foo
dobar:
	changed deps:
		modified:           foo
	changed outs:
		deleted:            bar

这表明对于阶段 dofoo，其依赖项 baz 和输出项 foo 已发生变化；同样地，对于阶段 dobar，其依赖项 foo 已改变，且输出项 bar 在工作区中不存在。对于 baz.dvc，其所跟踪的文件 baz 已发生更改。

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

dvc status 仅检查与给定 targets 对应的已跟踪数据：

$ dvc status foo.dvc dobar
foo.dvc:
	changed outs:
		modified:            foo
	changed checksum
dobar:
	changed deps:
		modified:           foo
	changed outs:
		not in cache:       bar

在此例中，目标 foo.dvc 是一个用于跟踪 foo 文件的 .dvc 文件，而 dobar 是在 dvc.yaml 中定义的一个阶段名称。

请注意，您可以检查被跟踪目录内的数据，例如 data/raw 目录（通过 data/raw.dvc 跟踪）：

$ tree data
data
├── raw
│   ├── partition.1.dat
│   ├── ...
│   └── partition.n.dat
└── raw.dvc

$ dvc fetch data/raw/partition.1.dat
new:                data/raw

示例：依赖关系

$ vi code/featurization.py
... edit the code

$ dvc status model.p
Data and pipelines are up to date.

$ dvc status model.p --with-deps
matrix-train.p:
	changed deps:
		modified:  code/featurization.py

dvc status 命令通常只检查指定目标本身是否变化，但添加 --with-deps 后，任何前置阶段的变更都会被检测到。

示例：远程比较

现在假设我们有一个共享的 S3 dvc remote，并希望检查哪些文件已经生成但尚未推送到远程：

$ dvc remote list
mystorage	s3://bucket/path

并希望检查哪些文件已经生成但尚未推送到远程：

$ dvc status --remote mystorage
...
	new:      data/model.p
	new:      data/eval.txt
	new:      data/matrix-train.p
	new:      data/matrix-test.p

输出结果显示了远程存储的位置，以及 缓存 与 mystorage 远程之间的任何差异。

示例：检查导入的数据

让我们使用 dvc import 从另一个 DVC 仓库 导入一个数据文件（data.csv）到当前项目中。

$ dvc import different/repo/location data.csv

生成的 data.csv.dvc 文件被称为一个 导入阶段（import stage）。如果原始文件或目录之后发生更改，dvc status 将显示“有更新可用”作为输出：

$ dvc status
data.csv.dvc:
	changed deps:
		update available:   data.csv (different/repo/location)

通过使用 dvc update，可以将导入的数据更新至最新版本。

若要跳过此检查（例如为了加快状态检查速度，或因为你没有权限访问原始源数据），请使用 --no-updates 参数：

$ dvc status --no-updates
Data and pipelines are up to date.