.. _user-guide-clean:

Cleaning run artifacts
======================

A |pyretis| run leaves a number of generated files and directories
behind -- log files, the regenerated ``out.toml`` / ``out.rst``, restart
files, the ``NNN`` ensemble directories, the ``report`` directory, the
infinite-swapping ``worker*`` / ``load`` directories, Python byte-code
caches, and so on. The ``pyretis clean`` sub-command removes them so a run
(or example) directory can be reset to its committed inputs:

.. code-block:: bash

   pyretis clean              # clean the current directory
   pyretis clean some/dir     # clean another directory
   pyretis clean --dry-run    # list what would be removed, delete nothing

``pyretis clean`` deletes immediately; use ``--dry-run`` (or ``-n``) first
if you want to preview the list.

What is removed
---------------

The removed set is the union of a small built-in default and an optional
per-directory configuration file. The built-in defaults cover the
artifacts every run can leave behind:

* files: ``*.pyc``, ``*.pyo``, ``infswap.toml``, ``restart.toml*``;
* directories: ``__pycache__``, ``load``, ``worker*``.

Reference outputs that are *committed* in some examples (for instance the
``NNN`` ensemble directories or an ``out.toml`` golden file) are **not**
in the defaults; a directory removes those through its own configuration
so a committed input is never deleted by accident. Anything below a
``results`` directory is always preserved.

Per-directory configuration
---------------------------

Drop a ``clean.toml`` next to the files to extend (or replace) the
defaults:

.. code-block:: toml

   [clean]
   use_defaults = true        # apply the built-in defaults (default: true)
   find_files = ["out.toml*", "*.log"]   # extra file-name globs (recursive)
   find_dirs  = ["report"]               # extra directory names (recursive)
   rm_paths   = ["0*", "lammps/system.data"]  # root-relative rm -rf globs
   keep       = ["load/0", "load/1"]     # never delete these (or ancestors)

* ``find_files`` -- file-name globs deleted wherever they occur in the
  tree (like ``find . -name PATTERN -delete``).
* ``find_dirs`` -- directory names deleted recursively wherever they
  occur.
* ``rm_paths`` -- root-relative paths or globs removed with ``rm -rf``
  semantics.
* ``keep`` -- paths that must survive; a kept path, anything inside it,
  and its ancestor directories are never removed. Use this to protect
  committed inputs that would otherwise match (for example the committed
  ``load/0`` .. ``load/7`` initial paths of the validation suite).
* ``use_defaults = false`` disables the built-in defaults so the file is
  the complete, explicit recipe.

This replaces the per-example ``Makefile`` ``clean`` targets used in
earlier |pyretis| versions.