``catkin clean`` -- Clean Build Products
========================================

The ``clean`` verb makes it easier and safer to clean various products of a catkin workspace.
In addition to removing entire **build**, **devel**, and **install spaces**, it also gives you more fine-grained control over removing just parts of these directories.

The ``clean`` verb is context-aware, but in order to work, it must be given the path to an initialized catkin workspace, or called from a path contained in an initialized catkin workspace.

Space Cleaning
^^^^^^^^^^^^^^

For any configuration, any of the active profile's spaces can be cleaned entirely.
This includes any of the top-level directories which are configured for a given profile.
See the full command line interface for specifying specific spaces to clean.

To clean all of the spaces for a given profile, you can call the ``clean`` verb without arguments:

.. code-block:: bash

    catkin clean

When running this command, ``catkin`` will prompt you to confirm that you want to delete the entire directories:

.. code-block:: bash

    $ catkin clean
    [clean] Warning: This will completely remove the following directories. (Use `--yes` to skip this check)
    [clean] Log Space:     /tmp/quickstart_ws/logs
    [clean] Build Space:   /tmp/quickstart_ws/build
    [clean] Devel Space:   /tmp/quickstart_ws/devel

    [clean] Are you sure you want to completely remove the directories listed above? [yN]:

If you want to skip this check, you can use the ``--yes`` or ``-y`` options:

.. code-block:: bash

    $ catkin clean -y
    [clean] Removing develspace: /tmp/quickstart_ws/devel
    [clean] Removing buildspace: /tmp/quickstart_ws/build
    [clean] Removing log space: /tmp/quickstart_ws/logs

.. note::

    The ``clean`` verb will also ask for additional confirmation if any of the directories to be removed are outside of your workspace root.
    To skip this additional check, you can use the ``--force`` option.

Partial Cleaning
^^^^^^^^^^^^^^^^

If a workspace is built with a ``linked`` **devel space**, the ``clean`` verb can be used to clean the products from individual packages.
This is possible since the ``catkin`` program will symbolically link the build products into the **devel space**, and stores a list of these links.

Cleaning a Single Package
-------------------------

Cleaning a single package (or several packages) is as simple as naming them:

.. code-block:: bash

    catkin clean PKGNAME

This will remove products from this package from the devel space, and remove its build space.

Cleaning Products from Missing Packages
---------------------------------------

Sometimes, you may disable or remove source packages from your workspace's **source  space**.
After packages have been removed from your **source space**, you can automatically clean the "orphaned" products with the following command:

.. code-block:: bash

    catkin clean --orphans

Cleaning Dependent Packages
---------------------------

When cleaning one package, it's sometimes useful to also clean all of the packages which depend on it.
This can prevent leftover elements from affecting the dependents.
To clean a package and only the packages which depend on it, you can run the following:

.. code-block:: bash

    catkin clean --dependents PKGNAME


Cleaning Products from All Profiles
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

By default, the ``clean`` operating is applied only to the active or specified profile.
To apply it to *all* profiles, use the ``--all-profiles`` option.

Cleaning Everything
^^^^^^^^^^^^^^^^^^^

If you want to clean **everything** except the source space (i.e. all files and folders generated by the ``catkin`` command, you can use ``--deinit`` to "deinitialize" the workspace.
This will clean all products from all packages for all profiles, as well as the profile metadata, itself.
After running this, a ``catkin_tools`` workspace will need to be reinitialized to be used.

.. code-block:: bash

    catkin clean --deinit

Full Command-Line Interface
^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. literalinclude:: cli/catkin_clean.txt
   :language: text