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