.. _configuration:

=============
Configuration
=============

Configuration of *gwf* is project-specific and thus all configuration must be
done in the project directory where the workflow file is located.

Commands for Configuration
==========================

To see the value of a configuration key, use:

.. code-block:: bash

    $ gwf config get KEY

To set the value of a key (or update it, if it already exists):

.. code-block:: bash

    $ gwf config set KEY VALUE

Keys are often of the form ``this.is.a.key``. For example, to use the Slurm
backend, run:

.. code-block:: bash

    $ gwf config set backend slurm

The local backend has no host or port setting. Its scheduler communicates over
a per-workflow Unix domain socket under ``$XDG_RUNTIME_DIR/gwf``. If
``XDG_RUNTIME_DIR`` is unavailable, *gwf* uses a private directory under the
system temporary directory.

.. versionchanged:: 3.0.0
    The local backend now uses a per-workflow Unix domain socket.
    ``local.host`` and ``local.port`` have been removed.

Your configuration is stored in the current working directory, which will
usually be your project directory, in a file called ``.gwfconf.json``. This
means that all configuration is project-specific, which helps with
reproducibility. You can inspect and change the file directly, but this is not
recommended unless you really know what you're doing.

Core settings are listed in the section below. To see which options are
available for a specific backend, refer to the :ref:`backends` documentation.

Available Settings
==================

This page lists settings that are used by *gwf*. Backends and plugins may define
their own settings, but these are documented for each backend/plugin
individually. See :ref:`configuration` if in doubt about how to configure *gwf*.

.. versionchanged:: 3.0.0
    The ``require_all_outputs`` setting was added for selective output checks
    during targeted runs.

* **backend (str):** Set the backend. Corresponds to the ``--backend`` flag (default: `local`).
* **verbose (str):** Set the verbosity. Corresponds to the ``--verbose`` flag (default: `info`).
* **no_color (bool):** If `true`, colors will not be used (default: `false`).
* **require_all_outputs (bool):** If `true`, a target is rerun
  when any declared output is missing, including outputs not needed by the
  requested targets (default: `true`). Set it to `false` to consider only the
  outputs needed by the requested targets and their dependencies. For example,
  ``gwf run B`` will not rerun a dependency solely because an output used only
  by another target is missing.