datalad_next.iter_collections.iter_annexworktree

datalad_next.iter_collections.iter_annexworktree(path: Path, *, untracked: str | None = 'all', link_target: bool = False, fp: bool = False, recursive: str = 'repository') → Generator[AnnexWorktreeItem | AnnexWorktreeFileSystemItem, None, None][source]

Companion to iter_gitworktree() for git-annex repositories

This iterator wraps iter_gitworktree(). For each item, it determines whether it is an annexed file. If so, it amends the yielded item with information on the respective annex key, the byte size of the key, and its (would-be) location in the repository's annex.

The basic semantics of all arguments are identical to iter_gitworktree(). Importantly, with fp=True, an annex object is opened directly, if available. If not available, no attempt is made to open the associated symlink or pointer file.

With link_target and fp disabled items of type AnnexWorktreeItem are yielded, otherwise AnnexWorktreeFileSystemItem instances are yielded. In both cases, annexkey, annexsize, and annnexobjpath properties are provided.

Note

Although annexobjpath is always set for annexed content, that does not imply that an object at this path actually exists. The latter will only be the case if the annexed content is present in the work tree, typically as a result of a datalad get- or git annex get-call.

Parameters:

  • path (Path) -- Path of a directory in a git-annex repository to report on. This directory need not be the root directory of the repository, but must be part of the repository's work tree.

  • untracked ({'all', 'whole-dir', 'no-empty-dir'} or None, optional) -- If not None, also reports on untracked work tree content. all reports on any untracked file; whole-dir yields a single report for a directory that is entirely untracked, and not individual untracked files in it; no-empty-dir skips any reports on untracked empty directories.

  • link_target (bool, optional) -- If True, information matching a FileSystemItem will be included for each yielded item, and the targets of any symlinks will be reported, too.

  • fp (bool, optional) -- If True, information matching a FileSystemItem will be included for each yielded item, but without a link target detection, unless link_target is given. Moreover, each file-type item includes a file-like object to access the file's content. This file handle will be closed automatically when the next item is yielded.

  • recursive ({'repository', 'no'}, optional) -- Pass on to iter_gitworktree(), thereby determining which items this iterator will yield.

Yields:

AnnexWorktreeItem or AnnexWorktreeFileSystemItem -- The name attribute of an item is a PurePath instance with the corresponding (relative) path, in platform conventions.