NAME

       datalad annotate-paths - analyze and act upon input paths

SYNOPSIS

       datalad annotate-paths [-h] [-d DATASET] [-r] [-R LEVELS] [--action LABEL] [--unavailable-
              path-status    LABEL]    [--unavailable-path-msg    message]    [--nondataset-path-
              status  LABEL] [--no-parentds-discovery] [--no-subds-discovery] [--revision-change-
              discovery] [--no-untracked-discovery] [--modified [MODIFIED]] [PATH [PATH ...]]

DESCRIPTION

       Given paths (or more generally location requests)  are  inspected  and  annotated  with  a
       number of properties. A list of recognized properties is provided below.

   Recognized path properties
       "action"
         label of the action that triggered the path annotation

       "annexkey"
         annex key for the content of a file

       "logger"
         logger for reporting a message

       "message"
         message (plus possible tsring expansion arguments)

       "orig_request"
         original input by which a path was determined

       "parentds"
         path of dataset containing the annotated path (superdataset
         for subdatasets)

       "path"
         absolute path that is annotated

       "process_content"
         flag that content underneath the path is to be processed

       "process_updated_only"
         flag that only known dataset components are to be processed

       "raw_input"
         flag whether this path was given as raw (non-annotated) input

       "refds"
         path of a reference/base dataset the annotated path is part of

       "registered_subds"
         flag whether a dataset is known to be a true subdataset of
         PARENTDS

       "revision"
         the recorded commit for a subdataset in a superdataset

       "revision_descr"
         a human-readable description of REVISION

       "source_url"
         URL a dataset was installed from

       "staged"
         flag whether a path is known to be "staged" in its containing
         dataset

       "state"
         state indicator for a path in its containing dataset (clean,
         modified, absent (also for files), conflict)

       "status"
         action result status (ok, notneeded, impossible, error)

       "type"
         nature of the path (file, directory, dataset)

       "url"
         registered URL for a subdataset in a superdataset

       In  the  case  of  enabled  modification  detection  the  results  may  contain additional
       properties regarding the nature of the modification. See the  documentation  of  the  DIFF
       command for details.

OPTIONS

       PATH   path to be annotated. 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
              an optional reference/base dataset for the paths.  Constraints:  Value  must  be  a
              Dataset or a valid identifier of a Dataset (e.g. a path)

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

       -\-action LABEL
              an "action" property value to include in the path  annotation.  Constraints:  value
              must be a string

       -\-unavailable-path-status LABEL
              a  "status"  property  value  to  include  in  the  annotation  for  paths that are
              underneath a dataset, but do not exist on the filesystem. Constraints:  value  must
              be a string [Default: '']

       -\-unavailable-path-msg message
              a  "message"  property  value  to  include  in  the  annotation  for paths that are
              underneath a dataset, but do not exist on the filesystem. Constraints:  value  must
              be a string

       -\-nondataset-path-status LABEL
              a  "status"  property  value  to  include  in the annotation for paths that are not
              underneath any dataset. Constraints: value must be a string [Default: 'error']

       -\-no-parentds-discovery
              Flag to disable reports of parent dataset information for any path,  in  particular
              dataset root paths. Disabling saves on command run time, if this information is not
              needed.

       -\-no-subds-discovery
              Flag to disable reporting type='dataset' for subdatasets, even when  they  are  not
              installed, or their mount point directory doesn't exist. Disabling saves on command
              run time, if this information is not needed.

       -\-revision-change-discovery
              Flag to disable discovery of changes which were not yet committed. Disabling  saves
              on command run time, if this information is not needed.

       -\-no-untracked-discovery
              Flag  to  disable  discovery  of  untracked changes. Disabling saves on command run
              time, if this information is not needed.

       -\-modified [MODIFIED]
              comparison reference specification for modification detection. This can be (mostly)
              anything  that  `git  diff`  understands  (commit,  treeish,  tag,  etc).  See  the
              documentation of `datalad diff --revision` for details. Unmodified paths  will  not
              be  annotated.  If a requested path was not modified but some content underneath it
              was, then the request is replaced by the modified paths  and  those  are  annotated
              instead.  This  option can be used without an argument to test against changes that
              have been made, but have not yet been staged for a commit. Constraints: value  must
              be a string, or value must be convertible to type bool

AUTHORS

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