Concept¶

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¶

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

Customize other commands with procedures¶

- 'datalad.<name>.proc-pre'

- 'datalad.<name>.proc-post'

where '<name>' is the name of a DataLad command. Using this mechanism DataLad can be instructed to run one or more procedures before or after the execution of a given command. For example, configuring a set of metadata types in any newly created dataset can be achieved via:

% datalad -c 'datalad.create.proc-post=cfg_metadatatypes xmp image' create -d myds

As procedures run on datasets, it is necessary to explicitly identify the target dataset via the -d (--dataset) option.