NAME

       datalad subdatasets - report subdatasets and their properties.

SYNOPSIS

       datalad     subdatasets     [-h]     [-d     DATASET]    [--state    {present|absent|any}]
              [--fulfilled FULFILLED] [-r] [-R LEVELS]  [--contains  PATH]  [--bottomup]  [--set-
              property NAME VALUE] [--delete-property NAME] [--version] [PATH ...]

DESCRIPTION

       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

       "gitshasum"
         SHA1 of the subdataset commit recorded in the parent dataset

       "state"
         Condition of the subdataset: 'absent', 'present'

       "gitmodule_url"
         URL of the subdataset recorded in the parent

       "gitmodule_name"
         Name 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.

       "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>...".

OPTIONS

       PATH   path/name to query for subdatasets. Defaults to the current directory. Constraints:
              value must be a string or value must be NONE

       -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) or value must be NONE

       --state {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']

       --fulfilled FULFILLED
              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)]

       -r, --recursive
              if set, recurse into potential subdatasets.

       -R LEVELS, --recursion-limit LEVELS
              limit  recursion into subdatasets to the given number of levels. Constraints: value
              must be convertible to type 'int' or value must be NONE

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

       --bottomup
              whether  to  report subdatasets in bottom-up order along each branch in the dataset
              tree, and not top-down.

       --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 or value must be 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 or value must be NONE

       --version
              show the module and its version which provides the command

AUTHORS

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