1datalad run-procedure(1) General Commands Manual datalad run-procedure(1)
2
6 datalad run-procedure - run prepared procedures (DataLad scripts) on a
7 dataset
8
10 datalad run-procedure [-h] [-d PATH] [--discover] [--help-proc]
11 [--version] ...
12
16 Concept
17 A "procedure" is an algorithm with the purpose to process a dataset in
18 a particular way. Procedures can be useful in a wide range of scenar‐
19 ios, like adjusting dataset configuration in a uniform fashion, popu‐
20 lating a dataset with particular content, or automating other routine
21 tasks, such as synchronizing dataset content with certain siblings.
22 Implementations of some procedures are shipped together with DataLad,
24 but additional procedures can be provided by 1) any DataLad extension,
25 2) any (sub-)dataset, 3) a local user, or 4) a local system administra‐
26 tor. DataLad will look for procedures in the following locations and
27 order:
28 Directories identified by the configuration settings
30 - 'datalad.locations.user-procedures' (determined by platformdirs.us‐
32 er_config_dir; defaults to '$HOME/.config/datalad/procedures' on
33 GNU/Linux systems) - 'datalad.locations.system-procedures' (determined
34 by platformdirs.site_config_dir; defaults to '/etc/xdg/datalad/proce‐
35 dures' on GNU/Linux systems) - 'datalad.locations.dataset-procedures'
36 and subsequently in the 'resources/procedures/' directories of any in‐
38 stalled extension, and, lastly, of the DataLad installation itself.
39 Please note that a dataset that defines any dataset it is a subdataset
41 of. That way you can have a collection of such procedures in a dedicat‐
42 ed dataset and install it as a subdataset into any dataset you want to
43 use those procedures with. In case of a naming conflict with such a
44 dataset hierarchy, the dataset you're calling run-procedures on will
45 take precedence over its subdatasets and so on.
46 Each configuration setting can occur multiple times to indicate multi‐
48 ple directories to be searched. If a procedure matching a given name is
49 found (filename without a possible extension), the search is aborted
50 and this implementation will be executed. This makes it possible for
51 individual datasets, users, or machines to override externally provided
52 procedures (enabling the implementation of customizable processing
53 "hooks").
54 Procedure implementation
56 A procedure can be any executable. Executables must have the appropri‐
57 ate permissions and, in the case of a script, must contain an appropri‐
58 ate "shebang" line. If a procedure is not executable, but its filename
59 ends with '.py', it is automatically executed by the 'python' inter‐
60 preter (whichever version is available in the present environment).
61 Likewise, procedure implementations ending on '.sh' are executed via
62 'bash'.
63 Procedures can implement any argument handling, but must be capable of
65 taking at least one positional argument (the absolute path to the
66 dataset they shall operate on).
67 For further customization there are two configuration settings per pro‐
69 cedure available:
70 - 'datalad.procedures.<NAME>.call-format' fully customizable format
72 string to determine how to execute procedure NAME (see also datal‐
73 ad-run). It currently requires to include the following placeholders:
74 - '{script}': will be replaced by the path to the procedure - '{ds}':
76 will be replaced by the absolute path to the dataset the
77 procedure shall operate on - '{args}': (not actually required) will
78 be replaced by
79 all additional arguments passed into run-procedure after NAME
80 As an example the default format string for a call to a python script
82 is:
83 "python {script} {ds} {args}" - 'datalad.procedures.<NAME>.help' will
84 be shown on `datalad run-procedure --help-proc NAME` to provide a de‐
85 scription and/or usage info for procedure NAME
86 Examples
88 Find out which procedures are available on the current system::
89 % datalad run-procedure --discover
91 Run the 'yoda' procedure in the current dataset::
93 % datalad run-procedure cfg_yoda
95
98 NAME [ARGS]
99 Name and possibly additional arguments of the to-be-executed
100 procedure. [PY: Can also be a dictionary coming from run-proce‐
101 dure(discover=True).]Note, that all options to run-procedure
102 need to be put before NAME, since all ARGS get assigned to NAME.
103 -h, --help, --help-np
106 show this help message. --help-np forcefully disables the use of
107 a pager for displaying the help message
108 -d PATH, --dataset PATH
110 specify the dataset to run the procedure on. An attempt is made
111 to identify the dataset based on the current working directory.
112 Constraints: Value must be a Dataset or a valid identifier of a
113 Dataset (e.g. a path) or value must be NONE
114 --discover
116 if given, all configured paths are searched for procedures and
117 one result record per discovered procedure is yielded, but no
118 procedure is executed.
119 --help-proc
121 if given, get a help message for procedure NAME from config set‐
122 ting datalad.procedures.NAME.help.
123 --version
125 show the module and its version which provides the command
126
128 datalad is developed by The DataLad Team and Contributors <team@datal‐
129 ad.org>.
130datalad run-procedure 0.19.3 2023-08-11 datalad run-procedure(1)