Implementation:Iterative Dvc Repo Update

Knowledge Sources	Iterative_Dvc
Domains	Data_Management, Import_Management
Last Updated	2026-02-10 10:00 GMT

Overview

Repo_Update provides functionality for updating DVC import stages and worktree stages to their latest versions. It is implemented in dvc/repo/update.py (67 lines) and exposes a single public function update().

from dvc.repo.update import update

This module is the backend for the dvc update CLI command.

Public Function

update()

Updates import stages to fetch the latest data from their source, or updates worktree stages.

Signature:

@locked
def update(
    self,
    targets=None,
    rev=None,
    recursive=False,
    to_remote=False,
    no_download=False,
    remote=None,
    jobs=None,
) -> list[Stage]:

Parameters:

Parameter	Type	Default	Description
self	Repo	required	The DVC repository instance
targets	list[str] or str or None	None	Specific targets to update (stage files, paths). Defaults to all.
rev	str or None	None	Git revision to update imports to (import stages only)
recursive	bool	False	Recursively collect targets
to_remote	bool	False	Push updated data directly to remote storage
no_download	bool	False	Update metadata without downloading data
remote	str or None	None	Remote storage name (requires to_remote=True)
jobs	int or None	None	Number of parallel jobs

Return value: A list of all Stage objects that were updated (both import stages and worktree stages).

Exceptions:

• dvc.exceptions.InvalidArgumentError -- raised for invalid option combinations:
  • --to-remote combined with --no-download
  • --remote without --to-remote
  • --rev with worktree update
  • --no-download with worktree update
  • --to-remote with worktree update

Execution Flow

1. The function acquires the repo lock via @locked.
2. targets is normalized to a list (defaulting to [None] for all stages).
3. Argument combinations are validated up front.
4. Stages are collected from the repo index via self.index.collect_targets().
5. Stages are partitioned into two groups:
   • Import stages (stage.is_import == True): collected into a set.
   • Other stages (worktree stages): collected as StageInfo objects.
6. Import stages are updated individually: stage.update(rev, ...) is called, then stage.dump() saves the updated stage file.
7. Worktree stages are updated in bulk via update_worktree_stages(), with additional argument validation (no --rev, --no-download, or --to-remote allowed).
8. A combined list of all updated stages is returned.

Stage Classification

Stage Type	Detection	Update Method	Supports --rev
Import stage	stage.is_import == True	stage.update(rev, ...)	Yes
Worktree stage	All other stages	update_worktree_stages()	No

Key Design Decisions

• Two-path update: The function separates import stages from worktree stages because they have fundamentally different update semantics. Import stages fetch data from external sources (possibly at a specific revision), while worktree stages sync with their filesystem-based dependencies.
• Strict option validation: Mutually exclusive or nonsensical option combinations are caught early with descriptive error messages, preventing confusing partial updates.
• Set-based deduplication: Import stages are collected into a set, automatically deduplicating when the same stage is matched by multiple targets.
• Dump after update: Each import stage is explicitly dumped after update, ensuring the .dvc file reflects the new data hash and metadata.

Dependencies

• dvc.repo.locked -- repository lock decorator
• dvc.exceptions.InvalidArgumentError -- argument validation errors
• dvc.repo.worktree.update_worktree_stages -- worktree stage update logic
• dvc.repo.stage.StageInfo -- stage information wrapper