SYNOPSIS

       datalad-subdatasets   [-h]   [-d   DATASET]  [--fulfilled  FULFILLED]  [-r]  [--recursion-
              limit LEVELS] [--contains PATH] [--bottomup] [--set-property NAME VALUE] [--delete-
              property NAME]

DESCRIPTION

       Report subdatasets and their properties.

       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.

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
              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]

AUTHORS

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