==============================
Command line interface - run
==============================

A general `doit` command goes like this:

.. code-block:: console

    $ doit [run] [<options>] [<task|target> <task_options>]* [<variables>]


The `doit` command line contains several sub-commands. Most of the time you just
want to execute your tasks, that's what *run* does. Since it is by far the most
common operation it is also the default, so if you don't specify any sub-command
to *doit* it will execute *run*. So ``$ doit`` and ``$ doit run`` do the same
thing.

The basics of task selection were introduced in :ref:`Task Selection
<task-selection>`.


`python -m doit`
-----------------

`doit` can also be executed without using the `doit` script.

.. code-block:: console

   $ python -m doit

This is specially useful when testing `doit` with different python versions.


dodo file
----------

By default all commands are relative to ``dodo.py`` in the current folder.
You can specify a different *dodo* file containing task with the flag ``-f``.
This flag is valid for all sub-commands.


.. code-block:: console

    $ doit -f release.py


*doit* can seek for the ``dodo.py`` file on parent folders if the the option ``--seek-file`` is specified.


verbosity
-----------

By default the stdout from a task is captured and its stderr is sent to the console. If the task fails or there is an error the stdout and a traceback (if any) is displayed.

There are 3 levels of verbosity:

0:
  capture (do not print) stdout/stderr from task.

1 (default):
  capture stdout only.

2:
  do not capture anything (print everything immediately).


You can control the verbosity by:

* --verbosity/-v command line option.

  change verbosity of all executed tasks.

.. code-block:: console

    $ doit --verbosity 2

* task attribute verbosity

.. literalinclude:: tutorial/verbosity.py

.. code-block:: console

    $ doit
    .  print
    hello


.. _parameters:

parameters
-----------

It is possible to pass option parameters to the task through the command line.

Just add a 'params' field to the task dictionary. `params` must be a list of
dictionaries where every entry is an option parameter. Each parameter must
define a name, and a default value. It can optionally define a "short" and
"long" names to be used from the command line (it follows unix command line
conventions). It may also specify a type the parameter should be converted to.



See the example:

.. literalinclude:: tutorial/parameters.py


For python-actions the python function must define arguments with the same name as a task parameter.

.. code-block:: console

    $ doit py_params -p abc --param2 4
    .  py_params
    abc
    9

For cmd-actions use python string substitution notation:

.. code-block:: console

    $ doit cmd_params -f "-c --other value"
    .  cmd_params
    mycmd -c --other value xxx


title
-------

By default when you run `doit` only the task name is printed out on the output. You can customize the output passing a "title" function to the task:

.. literalinclude:: tutorial/title.py

.. code-block:: console

    $ doit
    .  executing... Cmd: echo abc efg


dir (cwd)
-----------

By default the directory of the `dodo` file is used as the
"current working directory" on python execution.
You can specify a different *cwd* with the *-d*/*--dir* option.

.. code-block:: console

    $ doit --dir path/to/another/cwd


continue
---------

By default the execution of tasks is halted on the first task failure or error. You can force it to continue execution with the option --continue/-c

.. code-block:: console

    $ doit --continue


.. _parallel-execution:

parallel execution
-------------------

`doit` supports parallel execution --process/-n.
By default the `multiprocessing <http://docs.python.org/library/multiprocessing.html>`_
module is used.
So the same restrictions also apply to the use of multiprocessing in `doit`.

.. code-block:: console

    $ doit -n 3

You can also execute in parallel using threads by specifying the option
`--parallel-type/-P`.

.. code-block:: console

    $ doit -n 3 -P thread


.. _reporter:

reporter
---------

`doit` provides different "*reporters*" to display running tasks info
on the console.
Use the option --reporter/-r to choose a reporter.
Apart from the default it also includes:

 * executed-only: Produces zero output if no task is executed
 * json: Output results in JSON format
 * zero: display only error messages (does not display info on tasks
   being executed/skipped). This is used when you only want to see
   the output generated by the tasks execution.

.. code-block:: console

    $ doit --reporter json


custom reporter
-----------------

It is possible to define your own custom reporter. Check the code on `doit/reporter.py <https://bitbucket.org/schettino72/doit/src/tip/doit/reporter.py>`_ ... It is easy to get started by sub-classing the default reporter as shown below. The custom reporter must be configured using DOIT_CONFIG dict.

.. literalinclude:: tutorial/custom_reporter.py


Note that the ``reporter`` have no control over the *real time* output
from a task while it is being executed,
this is controlled by the ``verbosity`` param.



output-file
------------

The option --output-file/-o let you output the result to a file.

.. code-block:: console

    $ doit --output-file result.txt


initial_workdir
-----------------

When `doit` executes by default it will use the location of `dodo.py`
as the current working directory (unless --dir is specified).
The value of `doit.initial_workdir` will contain the path from where
`doit` was invoked from.

This can be used for example set which tasks will be executed:

.. literalinclude:: tutorial/initial_workdir.py


config
--------

Command line parameters can be set straight on a `dodo` file. This example below sets the default tasks to be run, the `continue` option, and a different reporter.

.. literalinclude:: tutorial/doit_config.py

So if you just execute

.. code-block:: console

   $ doit

it will have the same effect as executing

.. code-block:: console

   $ doit --continue --reporter json my_task_1 my_task_2

You need to check `doit_cmd.py <https://bitbucket.org/schettino72/doit/src/tip/doit/doit_cmd.py>`_ to find out how parameter maps to config names.

.. note::

  The parameters `--file` and `--dir` can not be used on config because they control how the dodo file itself is loaded.


minversion
^^^^^^^^^^^^

`minversion` can be used to specify the minimum/oldest `doit` version
that can be used with a `dodo.py` file.

For example if your `dodo.py` makes use of a feature added at `doit X`
and distribute it. If another user who tries this `dodo.py` with a version
older that `X`, doit will display an error warning the user to update `doit`.

.. code-block:: console

    DOIT_CONFIG = {
        'minversion': '0.24.0',
    }


.. note::

  This feature was added on `doit` 0.24.0.
  Older Versions will not check or display error messages.


returned value
------------------

``doit`` process returns:

 * 0 => all tasks executed successfully
 * 1 => task failed
 * 2 => error executing task
 * 3 => error before task execution starts
        (in this case the reporter is not used)

