Implementation:Iterative Dvc Repo Ls

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

Overview

Repo_Ls provides functionality for listing files and directories within DVC repositories. It is implemented in dvc/repo/ls.py (182 lines) and exposes two primary public functions: ls() for flat file listing and ls_tree() for hierarchical tree-structured output.

from dvc.repo.ls import ls, ls_tree

Public Functions

ls()

Lists files and outputs in a DVC repository, returning a flat list of entry dictionaries.

Signature:

def ls(
    url: str,
    path: Optional[str] = None,
    rev: Optional[str] = None,
    recursive: Optional[bool] = None,
    dvc_only: bool = False,
    config: Union[dict[str, Any], str, None] = None,
    remote: Optional[str] = None,
    remote_config: Optional[dict] = None,
    maxdepth: Optional[int] = None,
) -> list[dict[str, Any]]:

Parameters:

Parameter	Type	Default	Description
url	str	required	The repository URL (local path or remote URL)
path	Optional[str]	None	Relative path within the repo to list
rev	Optional[str]	None	Git revision (SHA, branch, or tag)
recursive	Optional[bool]	None	Recursively walk the repository
dvc_only	bool	False	Show only DVC-tracked artifacts
config	Union[dict, str, None]	None	Config dict or path to config file
remote	Optional[str]	None	Remote name to set as default
remote_config	Optional[dict]	None	Remote config to merge with the repo remote
maxdepth	Optional[int]	None	Maximum depth for recursive listing

Return value: A list of dictionaries, each with the structure:

{
    "path": str,      # relative file path
    "isout": bool,     # whether the entry is a DVC output
    "isdir": bool,     # whether the entry is a directory
    "isexec": bool,    # whether the entry is executable
    "size": int,       # file size (or None)
    "md5": str,        # MD5 hash from DVC metadata (or None)
}

ls_tree()

Lists files in a DVC repository as a nested tree structure, where directories contain a "contents" key mapping to their children.

Signature:

def ls_tree(
    url: str,
    path: Optional[str] = None,
    rev: Optional[str] = None,
    dvc_only: bool = False,
    config: Union[dict[str, Any], str, None] = None,
    remote: Optional[str] = None,
    remote_config: Optional[dict] = None,
    maxdepth: Optional[int] = None,
) -> dict[str, Any]:

Return value: A nested dictionary keyed by name, where each entry includes path, isout, isdir, isexec, size, md5, and optionally contents for directories.

Internal Functions

_open_repo()

Opens a DVC repository from a URL, optionally at a specific revision. Handles loading config from a file path if a string is provided. Passes through to Repo.open() with subrepos=True and uninitialized=True.

_adapt_info()

Transforms a raw filesystem info dictionary into the standardized entry format used by ls() and ls_tree(). Extracts dvc_info metadata including isout status and md5 hashes (supporting both Unix and DOS line-ending variants).

_ls()

Core listing logic used by ls(). Walks the filesystem using fs.walk() and collects entries. When maxdepth is 0 or the path is a file, returns a single entry. The maxdepth parameter is only honored when recursive is set; otherwise it is ignored.

_ls_tree()

Core tree-building logic used by ls_tree(). Recursively descends into directories via fs.ls(), building a nested dictionary. Handles broken symlinks gracefully by catching FileNotFoundError. Respects maxdepth by decrementing on each recursive call.

Execution Flow

1. The caller invokes ls() or ls_tree() with a repository URL.
2. _open_repo() opens the repository via Repo.open(), yielding a context-managed Repo instance.
3. The DVCFileSystem (repo.dvcfs) is obtained from the repo, which transparently overlays DVC-tracked files onto the Git working tree.
4. For ls(): _ls() walks the filesystem flat, collecting entries sorted by path.
5. For ls_tree(): _ls_tree() recursively builds a nested tree from fs.ls() calls.
6. Each raw info dict is passed through _adapt_info() to produce the standardized output format.

Key Design Decisions

• Flat vs. tree output: Two separate public functions serve different use cases -- ls() for simple enumeration (used by dvc ls) and ls_tree() for tree display (used by dvc ls --tree).
• maxdepth gating: In _ls(), maxdepth is only applied when recursive=True. If recursive is not set, the walk breaks after the first level regardless.
• Broken symlink handling: _ls_tree() catches FileNotFoundError during fs.ls() to handle broken symlinks without crashing.
• Sorted output: Both _ls() and _ls_tree() sort entries by path/name for deterministic output.

Dependencies

• dvc.repo.Repo -- repository access and lifecycle
• dvc.config.Config -- loading config from file paths
• dvc.fs.dvc.DVCFileSystem -- DVC-aware filesystem overlay