.. _debugging:

Debugging Facilities
--------------------

There is a ``borg debug`` command that has some subcommands which are all
**not intended for normal use** and **potentially very dangerous** if used incorrectly.

For example, ``borg debug put-obj`` and ``borg debug delete-obj`` will only do
what their name suggests: put objects into the repository / delete objects from the repository.

Please note:

- they will not update the chunks index about the object
- they will not update the manifest (so no automatic chunks index resync is triggered)
- they will not check whether the object is in use (e.g. before delete-obj)
- they will not update any metadata which may point to the object

They exist to improve debugging capabilities without direct system access, e.g.
in case you ever run into some severe malfunction. Use them only if you know
what you are doing or if a trusted Borg developer tells you what to do.

Borg has a ``--debug-topic TOPIC`` option to enable specific debugging messages. Topics
are generally not documented.

Setting the ``BORG_DEBUG_PROFILE`` environment variable to a filename writes a profile of
the main program's execution to that file. Note that this applies to every borg invocation
as long as the variable is set. The format of these files is not directly compatible with the
Python profiling tools, since these use the "marshal" format, which is not intended
to be secure (quoting the Python docs: "Never unmarshal data received from an untrusted
or unauthenticated source.").

The ``borg debug convert-profile`` command can be used to take a Borg profile and convert
it to a profile file that is compatible with the Python tools.

Additionally, if the filename given via ``BORG_DEBUG_PROFILE`` ends with ".pyprof", a
Python-compatible profile is generated. This is only intended for local use by developers.
