NAME

       datalad run-procedure - run prepared procedures (DataLad scripts) on a dataset

SYNOPSIS

       datalad run-procedure [-h] [-d PATH] [--discover] [--help-proc] ...

DESCRIPTION

   Concept
       A  "procedure"  is an algorithm with the purpose to process a dataset in a particular way.
       Procedures  can  be  useful  in  a  wide  range  of  scenarios,  like  adjusting   dataset
       configuration  in  a  uniform  fashion,  populating  a dataset with particular content, or
       automating other routine  tasks,  such  as  synchronizing  dataset  content  with  certain
       siblings.

       Implementations  of  some  procedures  are  shipped  together with DataLad, but additional
       procedures can be provided by 1) any DataLad extension, 2) any (sub-)dataset, 3)  a  local
       user,  or  4)  a  local  system  administrator.   DataLad  will look for procedures in the
       following locations and order:

       Directories identified by the configuration settings

       - 'datalad.locations.user-procedures' (determined by appdirs.user_config_dir; defaults  to
       '$HOME/.config/datalad/procedures'         on         GNU/Linux         systems)         -
       'datalad.locations.system-procedures' (determined by appdirs.site_config_dir; defaults  to
       '/etc/xdg/datalad/procedures'           on          GNU/Linux          systems)          -
       'datalad.locations.dataset-procedures'

       and subsequently in the 'resources/procedures/' directories of  any  installed  extension,
       and, lastly, of the DataLad installation itself.

       Please  note  that  a dataset that defines any dataset it is a subdataset of. That way you
       can have a collection of such procedures in a  dedicated  dataset  and  install  it  as  a
       subdataset  into  any  dataset  you want to use those procedures with. In case of a naming
       conflict with such a dataset hierarchy, the dataset you're calling run-procedures on  will
       take precedence over its subdatasets and so on.

       Each configuration setting can occur multiple times to indicate multiple directories to be
       searched. If a procedure matching a given name  is  found  (filename  without  a  possible
       extension),  the search is aborted and this implementation will be executed. This makes it
       possible for individual datasets, users,  or  machines  to  override  externally  provided
       procedures (enabling the implementation of customizable processing "hooks").

   Procedure implementation
       A  procedure can be any executable. Executables must have the appropriate permissions and,
       in the case of a script, must contain an appropriate "shebang" line. If a procedure is not
       executable, but its filename ends with '.py', it is automatically executed by the 'python'
       interpreter (whichever  version  is  available  in  the  present  environment).  Likewise,
       procedure implementations ending on '.sh' are executed via 'bash'.

       Procedures can implement any argument handling, but must be capable of taking at least one
       positional argument (the absolute path to the dataset they shall operate on).

       For further customization there are two configuration settings per procedure available:

       - 'datalad.procedures.<NAME>.call-format' fully customizable format  string  to  determine
       how  to  execute  procedure NAME (see also datalad-run).  It currently requires to include
       the following placeholders:

       - '{script}': will be replaced by the path to the procedure - '{ds}': will be replaced  by
       the absolute path to the dataset the
         procedure shall operate on - '{args}': (not actually required) will be replaced by
         all additional arguments passed into run-procedure after NAME

         As an example the default format string for a call to a python script is:
         "python  {script}  {ds}  {args}"  -  'datalad.procedures.<NAME>.help'  will  be shown on
       `datalad run-procedure --help-proc NAME` to provide a description and/or  usage  info  for
       procedure NAME

OPTIONS

       NAME [ARGS]
              Name  and possibly additional arguments of the to-be-executed procedure. Note, that
              all options to run-procedure need to  be  put  before  NAME,  since  all  ARGS  get
              assigned to NAME.

       -h, -\-help, -\-help-np
              show  this  help  message.  --help-np  forcefully  disables  the use of a pager for
              displaying the help message

       -d PATH, -\-dataset PATH
              specify the dataset to run the procedure on. An attempt is  made  to  identify  the
              dataset  based  on  the  current  working  directory.  Constraints: Value must be a
              Dataset or a valid identifier of a Dataset (e.g. a path)

       -\-discover
              if given, all configured paths are searched for procedures and  one  result  record
              per discovered procedure is yielded, but no procedure is executed.

       -\-help-proc
              if   given,   get   a   help   message  for  procedure  NAME  from  config  setting
              datalad.procedures.NAME.help.

AUTHORS

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