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 Data‐
       Lad'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/metada‐
       ta/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 dis‐
       covery 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 struc‐
       tures 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 map‐
              ping (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 convert‐
              ible to type 'int' [Default: None]

AUTHORS

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

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