datalad subdatasets - report subdatasets and their
properties.
datalad subdatasets [-h] [-d DATASET]
[--fulfilled FULFILLED] [-r] [--recursion-limit LEVELS]
[--contains PATH] [--bottomup] [--set-property NAME VALUE]
[--delete-property NAME]
The following properties are reported (if possible) for each
matching subdataset record.
"name"
Name of the subdataset in the parent (often identical with the
relative path in the parent dataset)
"path"
Absolute path to the subdataset
"parentds"
Absolute path to the parent dataset
"revision"
SHA1 of the subdataset commit recorded in the parent dataset
"state"
Condition of the subdataset: 'clean', 'modified', 'absent', 'conflict'
as reported by `git submodule`
"revision_descr"
Output of `git describe` for the subdataset
"gitmodule_url"
URL of the subdataset recorded in the parent
"gitmodule_<label>"
Any additional configuration property on record.
Performance note: Property modification, requesting BOTTOMUP
reporting order, or a particular numerical RECURSION_LIMIT implies an
internal switch to an alternative query implementation for recursive query
that is more flexible, but also notably slower (performs one call to Git per
dataset versus a single call for all combined).
The following properties for subdatasets are recognized by DataLad
(without the 'gitmodule_' prefix that is used in the query results):
"datalad-recursiveinstall"
If set to 'skip', the respective subdataset is skipped when DataLad
is recursively installing its superdataset. However, the subdataset
remains installable when explicitly requested, and no other features
are impaired.
- -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
- specify the dataset to query. If no dataset is given, an attempt is made
to identify the dataset based on the input and/or the current working
directory. Constraints: Value must be a Dataset or a valid identifier of a
Dataset (e.g. a path) [Default: None]
- --fulfilled
FULFILLED
- if given, must be a boolean flag indicating whether to report either only
locally present or absent datasets. By default subdatasets are reported
regardless of their status. Constraints: value must be convertible to type
bool [Default: None]
- -r,
--recursive
- if set, recurse into potential subdataset. [Default: False]
- --recursion-limit
LEVELS
- limit recursion into subdataset to the given number of levels.
Constraints: value must be convertible to type 'int' [Default: None]
- --contains
PATH
- limit report to the subdatasets containing the given path. If a root path
of a subdataset is given the last reported dataset will be the subdataset
itself. Constraints: value must be a string [Default: None]
- --bottomup
- whether to report subdatasets in bottom-up order along each branch in the
dataset tree, and not top-down. [Default: False]
- --set-property
NAME VALUE
- Name and value of one or more subdataset properties to be set in the
parent dataset's .gitmodules file. The property name is case-insensitive,
must start with a letter, and consist only of alphanumeric characters. The
value can be a Python format() template string wrapped in '<>' (e.g.
'<{gitmodule_name}>'). Supported keywords are any item reported in
the result properties of this command, plus 'refds_relpath' and
'refds_relname': the relative path of a subdataset with respect to the
base dataset of the command call, and, in the latter case, the same string
with all directory separators replaced by dashes. This option can be given
multiple times. Constraints: value must be a string [Default: None]
- --delete-property
NAME
- Name of one or more subdataset properties to be removed from the parent
dataset's .gitmodules file. This option can be given multiple times.
Constraints: value must be a string [Default: None]
datalad is developed by The DataLad Team and Contributors
<team@datalad.org>.