1datalad subdatasets(1) General Commands Manual datalad subdatasets(1)
2
6 datalad subdatasets - report subdatasets and their properties.
7
9 datalad subdatasets [-h] [-d DATASET] [--state {present|absent|any}]
10 [--fulfilled FULFILLED] [-r] [-R LEVELS] [--contains PATH]
11 [--bottomup] [--set-property NAME VALUE] [--delete-
12 property NAME] [--version] [PATH ...]
13
17 The following properties are reported (if possible) for each matching
18 subdataset record.
19 "name"
21 Name of the subdataset in the parent (often identical with the
22 relative path in the parent dataset)
23 "path"
25 Absolute path to the subdataset
26 "parentds"
28 Absolute path to the parent dataset
29 "gitshasum"
31 SHA1 of the subdataset commit recorded in the parent dataset
32 "state"
34 Condition of the subdataset: 'absent', 'present'
35 "gitmodule_url"
37 URL of the subdataset recorded in the parent
38 "gitmodule_name"
40 Name of the subdataset recorded in the parent
41 "gitmodule_<label>"
43 Any additional configuration property on record.
44 Performance note: Property modification, requesting BOTTOMUP reporting
46 order, or a particular numerical `recursion_limit` implies an internal
47 switch to an alternative query implementation for recursive query that
48 is more flexible, but also notably slower (performs one call to Git per
49 dataset versus a single call for all combined).
50 The following properties for subdatasets are recognized by DataLad
52 (without the 'gitmodule_' prefix that is used in the query results):
53 "datalad-recursiveinstall"
55 If set to 'skip', the respective subdataset is skipped when DataLad
56 is recursively installing its superdataset. However, the subdataset
57 remains installable when explicitly requested, and no other features
58 are impaired.
59 "datalad-url"
61 If a subdataset was originally established by cloning, 'datalad-url'
62 records the URL that was used to do so. This might be different from
63 'url' if the URL contains datalad specific pieces like any URL of the
64 form "ria+<some protocol>...".
65
67 PATH path/name to query for subdatasets. Defaults to the current di‐
68 rectory. Constraints: value must be a string or value must be
69 NONE
70 -h, --help, --help-np
73 show this help message. --help-np forcefully disables the use of
74 a pager for displaying the help message
75 -d DATASET, --dataset DATASET
77 specify the dataset to query. If no dataset is given, an attempt
78 is made to identify the dataset based on the input and/or the
79 current working directory. Constraints: Value must be a Dataset
80 or a valid identifier of a Dataset (e.g. a path) or value must
81 be NONE
82 --state {present|absent|any}
84 indicate which (sub)datasets to consider: either only locally
85 present, absent, or any of those two kinds. Constraints: value
86 must be one of ('present', 'absent', 'any') [Default: 'any']
87 --fulfilled FULFILLED
89 DEPRECATED: use --state instead. If given, must be a boolean
90 flag indicating whether to consider either only locally present
91 or absent datasets. By default all subdatasets are considered
92 regardless of their status. Constraints: value must be convert‐
93 ible to type bool or value must be NONE [Default: None(DEPRECAT‐
94 ED)]
95 -r, --recursive
97 if set, recurse into potential subdatasets.
98 -R LEVELS, --recursion-limit LEVELS
100 limit recursion into subdatasets to the given number of levels.
101 Constraints: value must be convertible to type 'int' or value
102 must be NONE
103 --contains PATH
105 limit to the subdatasets containing the given path. If a root
106 path of a subdataset is given, the last considered dataset will
107 be the subdataset itself. This option can be given multiple
108 times, in which case datasets that contain any of the given
109 paths will be considered. Constraints: value must be a string or
110 value must be NONE
111 --bottomup
113 whether to report subdatasets in bottom-up order along each
114 branch in the dataset tree, and not top-down.
115 --set-property NAME VALUE
117 Name and value of one or more subdataset properties to be set in
118 the parent dataset's .gitmodules file. The property name is
119 case-insensitive, must start with a letter, and consist only of
120 alphanumeric characters. The value can be a Python format() tem‐
121 plate string wrapped in '<>' (e.g. '<{gitmodule_name}>'). Sup‐
122 ported keywords are any item reported in the result properties
123 of this command, plus 'refds_relpath' and 'refds_relname': the
124 relative path of a subdataset with respect to the base dataset
125 of the command call, and, in the latter case, the same string
126 with all directory separators replaced by dashes. This option
127 can be given multiple times. Constraints: value must be a string
128 or value must be NONE
129 --delete-property NAME
131 Name of one or more subdataset properties to be removed from the
132 parent dataset's .gitmodules file. This option can be given mul‐
133 tiple times. Constraints: value must be a string or value must
134 be NONE
135 --version
137 show the module and its version which provides the command
138
140 datalad is developed by The DataLad Team and Contributors <team@datal‐
141 ad.org>.
142datalad subdatasets 0.19.3 2023-08-11 datalad subdatasets(1)