.TH "datalad subdatasets" "1" "2024\-03\-10" "datalad subdatasets 0.19.6"
.SH NAME
\fBdatalad subdatasets\fR \- report subdatasets and their properties.
.SH SYNOPSIS
.nh
.HP
\fBdatalad subdatasets\fR [-h] [-d\~DATASET] [--state\~{present|absent|any}] [--fulfilled\~FULFILLED] [-r] [-R\~LEVELS] [--contains\~PATH] [--bottomup] [--set-property NAME VALUE] [--delete-property\~NAME] [--version] [PATH ...]


.hy
.SH DESCRIPTION

The following properties are reported (if possible) for each matching
subdataset record.
.PP
"name"
  Name of the subdataset in the parent (often identical with the
  relative path in the parent dataset)
.PP
"path"
  Absolute path to the subdataset
.PP
"parentds"
  Absolute path to the parent dataset
.PP
"gitshasum"
  SHA1 of the subdataset commit recorded in the parent dataset
.PP
"state"
  Condition of the subdataset: 'absent', 'present'
.PP
"gitmodule_url"
  URL of the subdataset recorded in the parent
.PP
"gitmodule_name"
  Name of the subdataset recorded in the parent
.PP
"gitmodule_<label>"
  Any additional configuration property on record.
.PP
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).
.PP
The following properties for subdatasets are recognized by DataLad
(without the 'gitmodule\_' prefix that is used in the query results):
.PP
"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.
.PP
"datalad\-url"
  If a subdataset was originally established by cloning, 'datalad\-url'
  records the URL that was used to do so. This might be different from
  'url' if the URL contains datalad specific pieces like any URL of the
  form "ria+<some protocol>...".
.SH OPTIONS
.TP
PATH
path/name to query for subdatasets. Defaults to the current directory. Constraints: value must be a string or value must be NONE

.TP
\fB-h\fR, \fB--help\fR, \fB--help-np\fR
show this help message. --help-np forcefully disables the use of a pager for displaying the help message
.TP
\fB-d\fR \fI\s-1DATASET\s0\fR, \fB--dataset\fR \fI\s-1DATASET\s0\fR
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) or value must be NONE
.TP
\fB--state\fR {present|absent|any}
indicate which (sub)datasets to consider: either only locally present, absent, or any of those two kinds. Constraints: value must be one of ('present', 'absent', 'any') [Default: 'any']
.TP
\fB--fulfilled\fR \fI\s-1FULFILLED\s0\fR
DEPRECATED: use --state instead. If given, must be a boolean flag indicating whether to consider either only locally present or absent datasets. By default all subdatasets are considered regardless of their status. Constraints: value must be convertible to type bool or value must be NONE [Default: None(DEPRECATED)]
.TP
\fB-r\fR, \fB--recursive\fR
if set, recurse into potential subdatasets.
.TP
\fB-R\fR LEVELS, \fB--recursion-limit\fR LEVELS
limit recursion into subdatasets to the given number of levels. Constraints: value must be convertible to type 'int' or value must be NONE
.TP
\fB--contains\fR PATH
limit to the subdatasets containing the given path. If a root path of a subdataset is given, the last considered dataset will be the subdataset itself. This option can be given multiple times, in which case datasets that contain any of the given paths will be considered. Constraints: value must be a string or value must be NONE
.TP
\fB--bottomup\fR
whether to report subdatasets in bottom-up order along each branch in the dataset tree, and not top-down.
.TP
\fB--set-property\fR 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 or value must be NONE
.TP
\fB--delete-property\fR 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 or value must be NONE
.TP
\fB--version\fR
show the module and its version which provides the command
.SH AUTHORS
 datalad is developed by The DataLad Team and Contributors <team@datalad.org>.