list

是 dvc ls 的别名。

列出项目内容，包括由 DVC 和 Git 跟踪的文件、模型和目录。

可用于查找可通过 dvc get、dvc import 获取的数据，或用于 dvc.api 函数的数据。

概要

usage: dvc list [-h] [-q | -v] [-R|-T] [-L depth] [--dvc-only]
                [--json] [--rev [<commit>]]
                [--config <path>] [--remote <name>]
                [--remote-config [<name>=<value> ...]]
                [--size] [--show-hash]
                url [path]

positional arguments:
  url            Location of DVC or Git repository to list from
  path           Path to a file or directory in the repository

描述

生成一个 DVC 仓库（通常为在线仓库）的视图，列出由 DVC 跟踪的数据文件和目录，以及 Git 仓库中的其余内容。这非常有用，因为当你浏览托管的仓库（例如在 GitHub 上或使用 git ls-remote）时，你只能看到与代码一起被 Git 跟踪的 dvc.yaml 和 .dvc 文件。

此命令的输出等同于克隆该仓库并拉取数据（只是不会实际下载任何内容），如下所示：

$ git clone <url> example
$ cd example
$ dvc pull
$ ls <path>

url 参数指定包含数据源的 DVC 或 Git 仓库的地址。支持 HTTP 和 SSH 协议（例如 [user@]server:project.git）。url 也可以是本地文件系统路径（包括当前项目，例如 .）。DVC 项目内的任何路径都会被解析为项目的根目录。

可选的 path 参数用于指定要列出的文件或目录（支持被跟踪目录内的路径）。它应相对于仓库根目录（当 url 为本地路径时支持绝对路径）。这类似于向 ls 或 aws s3 ls 等列出命令传递路径。

默认仅列出根目录，但可以使用 -R 选项递归列出所有子目录中的文件。

请注意，dvc list 不会检查所列出的数据（由 DVC 跟踪）是否实际存在于远程存储中，因此无法保证这些数据可以通过 dvc get、dvc import 或 dvc.api 访问。

选项

-R, --recursive - 递归列出所有子目录中的文件。
-T, --tree - 以树形结构递归显示目录内容。
-L, --level <depth> - 限制递归深度。
--dvc-only - 仅显示由 DVC 跟踪的文件和目录（输出项）。
--rev <commit> - 指定要列出内容的仓库的提交哈希、分支或标签名称等（任意 Git 版本）。若未指定此选项，则默认使用默认分支的最新提交。
--json - 以易于解析的 JSON 格式输出命令结果，而非人类可读的表格形式。
--config <path> - 指向配置文件的路径，该文件将与目标仓库中的配置合并。
--remote <name> - 在目标仓库中设置为默认的 dvc remote 名称。
--remote-config [<name>=<value> ...] - 要与远程存储配置（默认或通过 --remote 指定的远程）合并的 dvc remote 配置选项。
--size - 显示文件大小。
--show-hash - 显示每个项目的哈希值。
-h, --help - 打印使用说明/帮助信息，然后退出。
-q, --quiet - 不向标准输出写入任何内容。如果没有问题则以 0 退出，否则以 1 退出。
-v, --verbose - 显示详细的追踪信息。当未指定此选项时，默认不显示。

示例：从仓库中查找可下载的文件

我们可以在使用 dvc get 或 dvc import 等命令复用仓库中的任意文件或目录之前，使用此命令获取有关该仓库的信息。这包括由 DVC 或 Git 跟踪的文件（或目录）：

$ dvc list https://github.com/iterative/example-get-started
.dvcignore
.gitignore
README.md
data
dvc.lock
dvc.yaml
model.pkl
params.yaml
prc.json
scores.json
src

如果你打开example-get-started项目的页面，会看到一个类似的列表，但不会看到model.pkl文件。该文件由 DVC 跟踪，对 Git 不可见。它在dvc.yaml文件中作为train阶段的输出（位于outs字段）被导出。

现在我们可以例如通过以下命令下载模型文件：

$ dvc get https://github.com/iterative/example-get-started model.pkl

示例：列出数据注册表中的所有文件

假设一个 DVC 仓库被用作数据注册表，其中不同数据集以独立目录结构组织。我们可以使用-R选项递归地执行此操作：

$ dvc list -R https://github.com/iterative/dataset-registry
.gitignore
README.md
get-started/.gitignore
get-started/data.xml
get-started/data.xml.dvc
images/.gitignore
images/dvc-logo-outlines.png
images/dvc-logo-outlines.png.dvc
images/owl_sticker.png
...

示例：创建你的 DVC 项目的归档文件

就像你可以使用git archive快速生成当前代码的压缩包（ZIP）一样，dvc list也可以轻松结合简单的归档工具，将项目中的当前数据文件打包。

例如，以下是整个工作区的 TAR 归档（Linux/GNU）：

$ dvc list . -R | tar -cvf project.tar

或者分别对代码和 DVC 跟踪的数据创建 ZIP 归档（POSIX 终端并安装了zip）：

$ git archive -o code.zip HEAD
$ dvc list . -R --dvc-only | zip -@ data.zip

适用于Windows 上的 POSIX 环境（已安装 Python）的 ZIP 替代方法：

$ dvc list . -R --dvc-only | xargs python -m zipfile -c data.zip

示例：为默认远程设置 AWS 配置文件

$ dvc list https://github.com/iterative/example-get-started-s3 data/prepared --remote-config profile=myprofile

示例：设置默认远程

$ dvc list https://github.com/iterative/example-get-started-s3 data/prepared --remote myremote