Implementation:Iterative Dvc Repo Install

Knowledge Sources	Iterative_Dvc
Domains	Git_Integration, Repository_Management
Last Updated	2026-02-10 10:00 GMT

Overview

The Repo_Install implementation adds DVC commands to Git hooks, enabling automatic DVC operations during Git workflows. It resides in dvc/repo/install.py (86 lines) and is the core logic behind the dvc install command.

from dvc.repo.install import install

Functions

The module provides three functions that work together to install DVC hooks.

install

def install(self: "Repo", use_pre_commit_tool: bool = False) -> None:

Parameter	Type	Default	Description
self	Repo	N/A	The DVC repository instance
use_pre_commit_tool	bool	False	If True, uses the pre-commit framework; otherwise installs hooks directly

This is the main entry point. It first installs a Git merge driver for DVC files, then delegates to either pre_commit_install or install_hooks depending on the use_pre_commit_tool flag.

pre_commit_install

def pre_commit_install(scm: "Git") -> None:

Integrates DVC with the pre-commit framework by modifying the .pre-commit-config.yaml file.

install_hooks

def install_hooks(scm: "Git") -> None:

Directly installs Git hook scripts for DVC operations.

Internal Mechanics

Merge Driver Installation

The install function always registers a custom Git merge driver for DVC files:

driver = "dvc git-hook merge-driver --ancestor %O --our %A --their %B "
scm.install_merge_driver("dvc", "DVC merge driver", driver)

This enables Git to use DVC-specific merge logic when conflicts arise in DVC-tracked files.

Git Type Check

The function checks that the SCM is a Git instance before proceeding. If the repository does not use Git, the function returns None:

from dvc.scm import Git

scm = self.scm
if not isinstance(scm, Git):
    return None

Pre-commit Framework Integration

When use_pre_commit_tool=True, the function adds a DVC entry to .pre-commit-config.yaml with three hooks:

Hook ID	Stage	Description
dvc-pre-commit	pre-commit	Runs DVC checks before each commit
dvc-pre-push	pre-push	Runs DVC operations before each push
dvc-post-checkout	post-checkout	Runs DVC operations after each checkout (always runs)

The hook configuration includes:

entry = {
    "repo": "https://github.com/treeverse/dvc",
    "rev": ".".join(map(str, version_tuple[:3])),
    "hooks": [
        {
            "id": "dvc-pre-commit",
            "additional_dependencies": [".[all]"],
            "language_version": "python3",
            "stages": ["pre-commit"],
        },
        {
            "id": "dvc-pre-push",
            "additional_dependencies": [".[all]"],
            "language_version": "python3",
            "stages": ["pre-push"],
        },
        {
            "id": "dvc-post-checkout",
            "additional_dependencies": [".[all]"],
            "language_version": "python3",
            "stages": ["post-checkout"],
            "always_run": True,
        },
    ],
}

The entry is only appended if it does not already exist in the configuration.

Direct Hook Installation

When not using the pre-commit framework, install_hooks installs three Git hook scripts directly:

Hook	Command
post-checkout	exec dvc git-hook post-checkout $@
pre-commit	exec dvc git-hook pre-commit $@
pre-push	exec dvc git-hook pre-push $@

Before installing each hook, the function verifies that no existing hook script conflicts with the installation. If a conflict is found, a DvcException is raised with a link to the documentation:

from scmrepo.exceptions import GitHookAlreadyExists

for hook in hooks:
    try:
        scm.verify_hook(hook)
    except GitHookAlreadyExists as exc:
        link = format_link("https://man.dvc.org/install")
        raise DvcException(f"{exc}. Please refer to {link} for more info.")

Usage Example

from dvc.repo import Repo

with Repo() as repo:
    # Install hooks directly
    repo.install()

    # Install using pre-commit framework
    repo.install(use_pre_commit_tool=True)

Dependencies

Module	Purpose
dvc.version_tuple	Provides the current DVC version for the pre-commit hook configuration
dvc.exceptions.DvcException	Raised when a Git hook already exists and conflicts
dvc.utils.serialize.modify_yaml	Modifies the .pre-commit-config.yaml file safely
dvc.utils.format_link	Formats documentation links for error messages
dvc.scm.Git	Git SCM interface for hook installation and merge driver registration
scmrepo.exceptions.GitHookAlreadyExists	Exception caught when an existing hook conflicts

See Also

• Repo_Init -- Initializes the DVC repository where hooks are installed
• Repo_Gc -- Another repository-level operation managed via SCM integration