install

将 Git 钩子安装到 DVC 仓库 中，以自动执行某些常见操作。

概要

usage: dvc install [-h] [-q | -v] [--use-pre-commit-tool]

描述

DVC 在普通的 Git 仓库之上提供一个智能的数据仓库，用于存储代码和配置文件。通过使用 dvc install，两者能够更紧密地集成，从而自动触发一些便捷的操作。

请注意，此命令要求 DVC 项目 必须是一个 Git 仓库。但如果当前分支（提交、标签等）未初始化 DVC（即不存在 .dvc/ 目录），则钩子不会激活。

具体包括：

检出（Checkout）：对于任意提交哈希、分支或标签，git checkout 会恢复对应版本的 DVC 项目文件。其中部分文件引用了存储在 缓存 中的数据，但这些数据不一定存在于当前的 工作区。通常需要运行 dvc checkout 来同步更新工作区。

该钩子可在 git checkout 后自动执行 dvc checkout。

提交/复现（Commit/Reproduce）：在使用 Git 提交 DVC 更改之前，可能需要先使用 dvc commit 将尚未进入缓存的新数据文件保存下来；或者这些更改需要通过 dvc repro 重新运行相应的 流水线 来生成项目的最新结果（这也会隐式地将结果提交到 DVC）。

该钩子会在必要时于 git commit 前自动运行 dvc status，提醒用户应使用 dvc commit 或 dvc repro。

推送（Push）：当使用 git push 发布更改到远程 Git 仓库时，很容易忘记还需要运行 dvc push 才能将 DVC 跟踪的新建或更新的数据文件和目录上传至 远程存储。

该钩子可在 git push 前自动执行 dvc push。

已安装的 Git 钩子

• post-checkout 钩子会在 git checkout 后执行 dvc checkout，以自动用正确的数据文件版本更新工作区。
• pre-commit 钩子会在 git commit 前执行 dvc status，向用户提示缓存与工作区之间的差异。
• pre-push 钩子会在 git push 前执行 dvc push，将 DVC 跟踪的文件和目录上传到 dvc remote default。

如果某个钩子文件已存在，DVC 将抛出异常。此时可尝试手动编辑现有文件，或将其删除后重新运行 install。

有关 Git 钩子的更多信息，请参考 git-scm 文档。

禁用 Git 钩子

当你使用 dvc install 时，它会在 .git/hooks 目录下创建三个文件：

.git/hooks
├── post-checkout
├── pre-commit
└── pre-push

要禁用它们，你需要删除或编辑这些文件（例如：rm .git/hooks/post-checkout、vim .git/hooks/pre-commit）。

使用 Pre-commit 工具

DVC 支持通过 pre-commit 管理 Git 钩子。要调整 .pre-commit-config.yaml 文件，你可以使用 dvc install --use-pre-commit-tool，或者手动添加这些条目：

repos:
  - hooks:
      - id: dvc-pre-commit
        language_version: python3
        stages:
          - pre-commit
      - id: dvc-pre-push
        # use s3/gs/etc instead of all to only install specific cloud support
        additional_dependencies: ['.[all]']
        language_version: python3
        stages:
          - pre-push
      - always_run: true
        id: dvc-post-checkout
        language_version: python3
        stages:
          - post-checkout
    repo: https://github.com/iterative/dvc
    rev: 3.56.0
    # rev should be set to a specific revision (e.g. 3.56.0) since pre-commit
    # does not allow using mutable references.
    # If using `main`, see pre-commit guide:
    #    https://pre-commit.com/#using-the-latest-version-for-a-repository

请注意，默认情况下 pre-commit 工具仅安装 pre-commit 钩子。若要启用 pre-push 和 post-checkout 钩子，必须显式地进行如下配置：

$ pre-commit install --hook-type pre-push --hook-type post-checkout --hook-type pre-commit

选项

• --use-pre-commit-tool - 在 pre-commit 配置文件（.pre-commit-config.yaml）中配置 DVC 的 pre-commit、pre-push 和 post-checkout Git 钩子。

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

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

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

示例

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

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

$ python3 -m venv .env
$ source .env/bin/activate
$ pip install -r src/requirements.txt

$ dvc pull -aT

示例：同时检出 Git 和 DVC

从一个 Git 提交切换到另一个（使用 git checkout）可能会改变 工作区 中的 DVC 文件集合。这意味着当前存在的数据可能不再匹配项目的版本（可通过 dvc checkout 修复）。

首先列出 快速入门 仓库中可用的标签：

$ git tag
0-git-init
1-dvc-init
2-track-data
3-config-remote
4-import-data
5-source-code
6-prepare-stage
7-ml-pipeline
8-evaluation
9-bigrams-model
10-bigrams-experiment
...

这些标签用于标记项目开发过程中的关键点，并记录其中进行的特定实验。要查看其中一个，我们检出 7-ml-pipeline 标签：

$ git checkout 7-ml-pipeline
Note: checking out '7-ml-pipeline'.

You are in 'detached HEAD' state...

$ dvc status
featurize:
	changed outs:
		modified:           data/features
...
$ dvc checkout

$ dvc status
Data and pipelines are up to date.

运行 git checkout 后，我们会看到一条提示信息：“You are in 'detached HEAD' state”（你处于“分离头指针”状态）。要将工作区恢复为正常状态，需运行 git checkout master。

我们还注意到，第一次运行 dvc status 会提示项目缓存与工作区中当前数据文件之间的差异。Git 修改了工作区中的 DVC 文件，从而改变了对数据文件的引用。dvc status 首先告诉我们工作区中的数据文件已不再与相应的 .dvc 和 dvc.lock 文件中的哈希值匹配。运行 dvc checkout 后，这些文件被更新，再次运行 dvc status 则显示数据文件现在已与 DVC 文件匹配。

$ git checkout master
Previous HEAD position was 6666298 Create ML pipeline stages
Switched to branch 'master'
Your branch is up to date with 'origin/master'.

$ dvc checkout

我们已经看到了未安装 Git 钩子时的默认行为。现在我们希望查看安装 Git 钩子后行为的变化。在安装钩子之前，必须先将工作区重置到 HEAD 提交。

$ dvc install

$ cat .git/hooks/pre-commit
#!/bin/sh
exec dvc status

$ cat .git/hooks/post-checkout
#!/bin/sh
exec dvc checkout

两个 Git 钩子已安装，本练习中关注的是 post-checkout 脚本，它会在执行 git checkout 后运行。

我们现在可以重复之前运行过的命令，以观察差异。

$ git checkout 7-ml-pipeline
HEAD is now at 6666298 Create ML pipeline stages
M       model.pkl
M	data/features/

$ dvc status
Data and pipelines are up to date.

仔细查看此输出，可以清楚地看到 dvc checkout 命令确实已被执行。因此，工作区中的数据文件已更新为与 DVC 文件中引用的内容一致。

示例：使用 Git 提交时显示 DVC 状态

要跟随此示例，请使用与之前相同的工作区，并通过运行 git checkout master 确保其不处于 分离头指针（detached HEAD） 状态。

如果我们只是编辑其中一个代码文件：

$ vi src/featurization.py

$ git commit -a -m "modified featurization"

featurize:
    changed deps:
        modified:           src/featurization.py
[master 1116ddc] modified featurization
 1 file changed, 1 insertion(+), 1 deletion(-)

可以看到 dvc status 的输出出现在了 git commit 的交互过程中。这种新行为对应于已安装的 Git 钩子，它提示我们工作区已不同步。因此，我们知道需要运行 dvc repro 命令：

$ dvc repro
...
To track the changes with git run:

    git add dvc.lock

$ git status -s
M dvc.lock

$ git commit -a -m "updated data after modified featurization"
Data and pipelines are up to date.

[master 78d0c44] modified featurization
 5 files changed, 12 insertions(+), 12 deletions(-)

重新运行管道后，数据文件应与代码和配置保持同步，接下来我们希望使用 Git 提交这些更改。在此过程中，dvc status 会再次自动运行，提示我们数据文件确实已更新，并显示消息 Data and pipelines are up to date.（数据和管道已是最新）。