datalad next-status

Synopsis

datalad next-status [-h] [-d DATASET] [--untracked {no,whole-dir,no-empty-dir,normal,all}] [-r [{no,repository,datasets,mono}]] [-e {no,commit,full}] [--version]

Description

Report on the (modification) status of a dataset

NOTE

This is a preview of an command implementation aiming to replace the DataLad status command.

For now, expect anything here to change again.

This command provides a report that is roughly identical to that of git status. Running with default parameters yields a report that should look familiar to Git and DataLad users alike, and contain the same information as offered by git status.

The main difference to git status are:

  • Support for recursion into submodule. git status does that too, but the report is limited to the global state of an entire submodule, whereas this command can issue detailed reports in changes inside a submodule (any nesting depth).

  • Support for directory-constrained reporting. Much like git status limits its report to a single repository, this command can optionally limit its report to a single directory and its direct children. In this report subdirectories are considered containers (much like) submodules, and a change summary is provided for them.

  • Support for a "mono" (monolithic repository) report. Unlike a standard recursion into submodules, and checking each of them for changes with respect to the HEAD commit of the worktree, this report compares a submodule with respect to the state recorded in its parent repository. This provides an equally comprehensive status report from the point of view of a queried repository, but does not include a dedicated item on the global state of a submodule. This makes nested hierarchy of repositories appear like a single (mono) repository.

  • Support for "adjusted mode" git-annex repositories. These utilize a managed branch that is repeatedly rewritten, hence is not suitable for tracking within a parent repository. Instead, the underlying "corresponding branch" is used, which contains the equivalent content in an un-adjusted form, persistently. This command detects this condition and automatically check a repositories state against the corresponding branch state.

Presently missing/planned features

  • There is no support for specifying paths (or pathspecs) for constraining the operation to specific dataset parts. This will be added in the future.

  • There is no reporting of git-annex properties, such as tracked file size. It is undetermined whether this will be added in the future. However, even without a dedicated switch, this command has support for datasets (and their submodules) in git-annex's "adjusted mode".

Differences to the ``status`` command implementation prior DataLad v2

  • Like git status this implementation reports on dataset modification, whereas the previous status also provided a listing of unchanged dataset content. This is no longer done. Equivalent functionality for listing dataset content is provided by the ls_file_collection command.

  • The implementation is substantially faster. Depending on the context the speed-up is typically somewhere between 2x and 100x.

  • The implementation does not suffer from the limitation re type change detection.

  • Python and CLI API of the command use uniform parameter validation.

Examples

Options

-h, --help, --help-np

show this help message. --help-np forcefully disables the use of a pager for displaying the help message

-d DATASET, --dataset DATASET

Dataset to be used as a configuration source. Beyond reading configuration items, this command does not interact with the dataset.

--untracked {no,whole-dir,no-empty-dir,normal,all}

Determine how untracked content is considered and reported when comparing a revision to the state of the working tree. 'no': no untracked content is considered as a change; 'normal': untracked files and entire untracked directories are reported as such; 'all': report individual files even in fully untracked directories. In addition to these git-status modes, 'whole-dir' (like normal, but include empty directories), and 'no-empty-dir' (alias for 'normal') are understood. [Default: 'normal']

-r [{no,repository,datasets,mono}], --recursive [{no,repository,datasets,mono}]

Mode of recursion for status reporting. With 'no' the report is restricted to a single directory and its direct children. With 'repository', the report comprises all repository content underneath current working directory or root of a given dataset, but is limited to items directly contained in that repository. With 'datasets', the report also comprises any content in any subdatasets. Each subdataset is evaluated against its respective HEAD commit. With 'mono', a report similar to 'datasets' is generated, but any subdataset is evaluate with respect to the state recorded in its parent repository. In contrast to the 'datasets' mode, no report items on a joint submodule are generated. If no particular value is given with this option the 'datasets' mode is selected. [Default: 'repository']

-e {no,commit,full}, --eval-subdataset-state {no,commit,full}

Evaluation of subdataset state (modified or untracked content) can be expensive for deep dataset hierarchies as subdataset have to be tested recursively for uncommitted modifications. Setting this option to 'no' or 'commit' can substantially boost performance by limiting what is being tested. With 'no' no state is evaluated and subdataset are not investigated for modifications. With 'commit' only a discrepancy of the HEAD commit gitsha of a subdataset and the gitsha recorded in the superdataset's record is evaluated. With 'full' any other modifications are considered too. [Default: 'full']

--version

show the module and its version which provides the command

Authors

datalad is developed by The DataLad Team and Contributors <team@datalad.org>.