NAME

       datalad subdatasets - report subdatasets and their properties.

SYNOPSIS

       datalad   subdatasets   [-h]   [-d  DATASET]  [--fulfilled  FULFILLED]  [-r]  [-R  LEVELS]
              [--contains PATH] [--bottomup] [--set-property NAME VALUE] [--delete-property NAME]
              [PATH [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: 'clean', 'modified', 'absent', 'conflict'
         as reported by `git submodule`

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

OPTIONS

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

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

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

       -r, -\-recursive
              if set, recurse into potential subdataset.

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

       -\-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.  This
              option  can  be  given multiple times, in which case datasets will be reported that
              contain any of the given paths. Constraints: value must be a string

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

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

AUTHORS

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