NAME

       datalad run - run an arbitrary shell command and record its impact on a dataset.

SYNOPSIS

       datalad  run  [-h]  [-d  DATASET]  [-i  PATH]  [-o  PATH]  [--expand  {inputs|outputs|both}] [--explicit]
              [-m MESSAGE] [--sidecar {yes|no}] ...

DESCRIPTION

       It is recommended to craft the command such that it can run in the root directory of the dataset that the
       command will be recorded in. However, as long as the command is executed somewhere underneath the dataset
       root, the exact location will be recorded relative to the dataset root.

       If the executed command did not alter the dataset in any way, no record of the command execution is made.

       If the given command errors, a COMMANDERROR exception with the same exit code  will  be  raised,  and  no
       modifications will be saved.

   Command format
       A few placeholders are supported in the command via Python format specification. "{pwd}" will be replaced
       with the full path of the current working directory. "{dspath}" will be replaced with the  full  path  of
       the  dataset  that  run  is  invoked  on.  "{tmpdir}"  will be replaced with the full path of a temporary
       directory. "{inputs}" and "{outputs}" represent the values specified by --input and --output. If multiple
       values  are  specified,  the  values  will be joined by a space.  The order of the values will match that
       order from the command line, with any globs expanded in alphabetical order (like bash). Individual values
       can be accessed with an integer index (e.g., "{inputs[0]}").

       Note  that the representation of the inputs or outputs in the formatted command string depends on whether
       the command is given as a list of arguments  or  as  a  string  (quotes  surrounding  the  command).  The
       concatenated  list  of inputs or outputs will be surrounded by quotes when the command is given as a list
       but not when it is given as a string. This means that the string form is required if  you  need  to  pass
       each  input as a separate argument to a preceding script (i.e., write the command as "./script {inputs}",
       quotes included). The string form should also be used if the input or  output  paths  contain  spaces  or
       other characters that need to be escaped.

       To escape a brace character, double it (i.e., "{{" or "}}").

       Custom  placeholders  can  be  added as configuration variables under "datalad.run.substitutions".  As an
       example:

       Add a placeholder "name" with the value "joe"::

         % git config --file=.datalad/config datalad.run.substitutions.name joe
         % datalad add -m "Configure name placeholder" .datalad/config

       Access the new placeholder in a command::

         % datalad run "echo my name is {name} >me"

   Examples
       Run an executable script and record the impact on a dataset::

        % datalad run -m 'run my script' 'code/script.sh'

       Run a command and specify a directory as a dependency for the run. The contents of the dependency will be
       retrieved prior to running the script::

        % datalad run -m 'run my script' --input 'data/*' 'code/script.sh'

       Run  an  executable  script  and  specify  output files of the script to be unlocked prior to running the
       script::

        % datalad run -m 'run my script' --input 'data/*' --output 'output_dir/*' 'code/script.sh'

       Specify multiple inputs and outputs::

        % datalad run -m 'run my script' --input 'data/*'
            --input 'datafile.txt' --output 'output_dir/*' --output
            'outfile.txt' 'code/script.sh'

OPTIONS

       COMMAND
              command for execution. A leading '--' can be used to disambiguate this command from the  preceding
              options to DataLad.

       -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
              specify the dataset to record the command results in. An attempt is made to identify  the  dataset
              based on the current working directory. If a dataset is given, the command will be executed in the
              root directory of this dataset. Constraints: Value must be a Dataset or a valid  identifier  of  a
              Dataset (e.g. a path)

       -i PATH, -\-input PATH
              A  dependency for the run. Before running the command, the content of this file will be retrieved.
              A value of "." means "run datalad get .". The value can also be a glob. This option can  be  given
              more than once.

       -o PATH, -\-output PATH
              Prepare this file to be an output file of the command. A value of "." means "run datalad unlock ."
              (and will fail if some content isn't present). For any other value, if the content of this file is
              present,  unlock  the file. Otherwise, remove it. The value can also be a glob. This option can be
              given more than once.

       -\-expand {inputs|outputs|both}
              Expand globs when storing inputs and/or outputs in the commit message. Constraints: value must  be
              one of (None, 'inputs', 'outputs', 'both')

       -\-explicit
              Consider  the  specification of inputs and outputs to be explicit. Don't warn if the repository is
              dirty, and only save modifications to the listed outputs.

       -m MESSAGE, -\-message MESSAGE
              a description of the state or the changes made to a dataset. Constraints: value must be a string

       -\-sidecar {yes|no}
              By default, the configuration variable 'datalad.run.record-sidecar' determines  whether  a  record
              with  information  on  a  command's execution is placed into a separate record file instead of the
              commit message (default: off). This option can be used to override the configured  behavior  on  a
              case-by-case  basis.  Sidecar  files  are  placed  into the dataset's '.datalad/runinfo' directory
              (customizable via the 'datalad.run.record-directory' configuration variable).  Constraints:  value
              must be NONE, or value must be convertible to type bool

AUTHORS

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