SYNOPSIS

       datalad-metadata  [-h]  [-d  DATASET]  [-a KEY [VAL ...]] [-i KEY [VAL ...]] [--remove KEY
              [VAL ...]]  [--reset  KEY  [VAL  ...]]  [--define-key  KEY  DEFINITION]  [-g]  [-r]
              [--recursion-limit LEVELS] [PATH [PATH ...]]

DESCRIPTION

       Metadata manipulation for files and whole datasets

       Two types of metadata are supported:

       1. metadata describing a dataset as a whole (dataset-global), and

       2. metadata for individual files in a dataset.

       Both  types can be accessed and modified with this command.  Note, however, that this only
       refers to DataLad's native metadata, and not to any other metadata that is possibly stored
       in files of a dataset.

       DataLad's native metadata capability is primarily targeting data description via arbitrary
       tags and other (brief) key-value attributes (with possibly multiple values  for  a  single
       key).

       Metadata  key  names are limited to alphanumerics (and [_-.]). Moreover, all key names are
       converted to lower case.

   Dataset (global) metadata
       Metadata describing a dataset as a whole is stored  in  JSON  format  in  the  dataset  at
       .datalad/metadata/dataset.json.  The  amount of metadata that can be stored is not limited
       by DataLad. However, it should be kept brief as this information  is  stored  in  the  Git
       history of the dataset, and access or modification requires to read the entire file.

       Arbitrary  metadata  keys  can  be  used.  However,  DataLad  reserves  the keys 'tag' and
       'definition' for its own use. The can still be manipulated without any  restrictions  like
       any   other   metadata   items,   but  doing  so  can  impact  DataLad's  metadata-related
       functionality, handle with care.

       The 'tag' key is used to store a list of (unique) tags.

       The 'definition' key is used to store key-value mappings that define  metadata  keys  used
       elsewhere  in  the  metadata.  Using the feature is optional (see --define-key). It can be
       useful in the context of data discovery  needs,  where  metadata  keys  can  be  precisely
       defined by linking them to specific ontology terms.

   File metadata
       Metadata  storage  for  individual  files is provided by git-annex, and generally the same
       rules as for dataset-global metadata apply.  However, there is just one reserved key name:
       'tag'.

       Again,  the  amount  of  metadata  is  not  limited,  but metadata is stored in git-annex'
       internal data structures in the Git repository of a dataset. Large amounts of metadata can
       slow its performance.

   Output rendering
       By default, a short summary of the metadata for each dataset (component) is rendered::

       <path> (<type>): -|<keys> [<tags>]

       where  <path>  is  the  path  of  the respective component, <type> a label for the type of
       dataset components metadata is presented for. Non-existant  metadata  is  indicated  by  a
       dash, otherwise a comma-separated list of metadata keys (except for 'tag'), is followed by
       a list of tags, if there are any.

OPTIONS

       PATH   path(s) to set/get metadata. Constraints: value must be a string [Default: 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
              Constraints:  Value  must  be  a Dataset or a valid identifier of a Dataset (e.g. a
              path) [Default: None]

       -a KEY [VAL ...], --add KEY [VAL ...]
              metadata items to add. If only a key is given, a corresponding tag is added.  If  a
              key-value  mapping (multiple values at once are supported) is given, the values are
              added to the metadata item of  that  key.  Constraints:  value  must  be  a  string
              [Default: None]

       -i KEY [VAL ...], --init KEY [VAL ...]
              like  --add, but tags are only added if no tag was present before. Likewise, values
              are only added to a metadata key, if that key did not  exist  before.  Constraints:
              value must be a string [Default: None]

       --remove KEY [VAL ...]
              metadata  values to remove. If only a key is given, a corresponding tag is removed.
              If a key-value mapping (multiple values at once are supported) is given, only those
              values  are removed from the metadata item of that key. If no values are left after
              the removal, the entire item of that key is removed. Constraints: value must  be  a
              string [Default: None]

       --reset KEY [VAL ...]
              metadata items to remove. If only a key is given, a corresponding metadata key with
              all its values is removed. If a key-value mapping  (multiple  values  at  once  are
              supported)  is  given,  any  existing values for this key are replaced by the given
              ones. Constraints: value must be a string [Default: None]

       --define-key KEY DEFINITION
              convenience option to add an item in the dataset's  global  metadata  ('definition'
              key). This can be used to define (custom) keys used in the datasets's metadata, for
              example by providing a URL to an ontology term for a given key label.  This  option
              does  not  need --dataset-global to be set to be in effect. Constraints: value must
              be a string [Default: None]

       -g, --dataset-global
              Whether to perform metadata query or modification on the global  dataset  metadata,
              or  on  individual  dataset  components.  For  example, without this switch setting
              metadata using the root path of a dataset, will set  the  given  metadata  for  all
              files  in a dataset, whereas with this flag only the metadata record of the dataset
              itself will be altered. [Default: False]

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

AUTHORS

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