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 ab‐
              sent 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 convert‐
              ible 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 [De‐
              fault: 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  al‐
              phanumeric  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  direc‐
              tory  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>.

datalad-subdatasets 0.9.3                          2018-04-03                             datalad-subdatasets(1)