bionic (1) datalad-subdatasets.1.gz

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