Implementation:Iterative Dvc Repo Init

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

Overview

The Repo_Init implementation creates an empty DVC repository by setting up the .dvc directory with its configuration and cache structure. It resides in dvc/repo/init.py (96 lines) and is the core logic behind the dvc init command.

from dvc.repo.init import init

Function Signature

def init(root_dir=os.curdir, no_scm=False, force=False, subdir=False):

Parameters

Parameter	Type	Default	Description
root_dir	str	os.curdir	Path to the repository root directory
no_scm	bool	False	Initialize without SCM integration (no Git requirement)
force	bool	False	Overwrite an existing .dvc directory
subdir	bool	False	Initialize inside a subdirectory of a parent Git repository

Return Value

Returns a Repo instance representing the newly initialized DVC repository.

Exceptions

Exception	Condition
InvalidArgumentError	Both --no-scm and --subdir are specified (mutually exclusive)
InitError	The directory is not tracked by a supported SCM tool (when SCM is required)
InitError	The .dvc directory is ignored by the SCM tool
InitError	The .dvc directory already exists and --force was not provided

Internal Mechanics

Argument Validation

The function rejects the combination of no_scm and subdir, as they are mutually exclusive:

if no_scm and subdir:
    raise InvalidArgumentError(
        "Cannot initialize repo with `--no-scm` and `--subdir`"
    )

SCM Detection

The function attempts to detect the SCM system (Git) for the repository:

from dvc.scm import SCM, SCMError

try:
    scm = SCM(root_dir, search_parent_directories=subdir, no_scm=no_scm)
except SCMError:
    raise InitError(
        f"{root_dir} is not tracked by any supported SCM tool (e.g. Git)."
    )

When subdir=True, the SCM search includes parent directories to find the enclosing Git repository.

Directory Safety Checks

Before creating the .dvc directory, two safety checks are performed:

1. SCM ignore check: Ensures .dvc is not listed in .gitignore or equivalent.
2. Existing directory check: If .dvc already exists and force=False, an error is raised. With force=True, the existing directory is removed.

Initialization Steps

The initialization proceeds through these steps:

1. Create .dvc directory using os.makedirs.
2. Initialize configuration via Config.init(dvc_dir).
3. Set no-SCM mode in configuration if no_scm=True:

   conf["core"]["no_scm"] = True

4. Initialize .dvcignore file via init_dvcignore(root_dir).
5. Create the Repo instance and clean up any stale site cache directory.
6. Track generated files using SCM auto-staging.

Site Cache Cleanup

If a site cache directory exists from a previous initialization, it is removed to ensure a clean state:

if os.path.isdir(proj.site_cache_dir):
    proj.close()
    try:
        remove(proj.site_cache_dir)
    except OSError:
        logger.debug("failed to remove %s", dvc_dir, exc_info=True)
    proj = Repo(root_dir)

SCM File Tracking

The function auto-stages the following files for Git tracking:

with proj.scm_context(autostage=True) as context:
    files = [config.files["repo"], dvcignore]
    ignore_file = context.scm.ignore_file
    if ignore_file:
        files.extend([os.path.join(dvc_dir, ignore_file)])
    proj.scm_context.track_file(files)

This typically includes:

• .dvc/config -- the repository configuration
• .dvcignore -- the DVC ignore patterns
• .dvc/.gitignore -- Git ignore rules for the DVC directory internals

Usage Example

from dvc.repo.init import init

# Initialize DVC in the current directory
repo = init()

# Initialize without Git (standalone mode)
repo = init(root_dir="/path/to/project", no_scm=True)

# Force re-initialization in a subdirectory
repo = init(root_dir="/path/to/subdir", force=True, subdir=True)

Dependencies

Module	Purpose
dvc.config.Config	Initializes and manages the DVC configuration file
dvc.exceptions.InitError	Raised for initialization failures
dvc.exceptions.InvalidArgumentError	Raised for invalid parameter combinations
dvc.ignore.init	Creates the .dvcignore file
dvc.repo.Repo	The DVC repository class instantiated after initialization
dvc.scm.SCM	Detects and interfaces with the source control manager
dvc.utils.fs.remove	Removes existing directories during forced re-initialization

See Also

• Repo_Install -- Installs DVC hooks into the initialized repository
• Repo_Gc -- Operates on the cache directory created during initialization