.. currentmodule:: emborg

.. _emborg_accessories:

Accessories
===========

.. _borg space:

Borg-Space
----------

`Borg-Space <https://github.com/KenKundert/borg-space>`_ is a utility that 
reports and tracks the space required by your *Borg* repositories.
It also allows you to graph the space used over time.

The following is an example of a graph generated by *borg-space* that allowed me 
to catch a problem that resulted in excessive growth in in the space required to 
hold my repository: in the switch from *Borg 1.1* to *Borg 1.2*, I had neglected 
to implement a compaction strategy.  The problem was resolved on April 5th.

.. image:: cache.svg
    :height: 300px
    :align: center


.. _ntlog accessory:

Logging with ntLog
------------------

`ntLog <https://github.com/KenKundert/ntlog>`_ is a log file aggregation 
utility.

When run *Emborg* writes over a previously generated logfile.  This becomes 
problematic if you have one  cron script that runs *create* frequently and 
another that runs a command like *prune* less frequently. If there is trouble 
with the *prune* command it will be difficult to see and resolve because its 
logfile will be overwritten by subsequent *create* commands.

*ntlog* can be run after each *Emborg* run to aggregate the individual logfile 
from each run into a single accumulating log file.  To arrange this you can use 
:ref:`run_after_borg <run_after_borg>`::

    run_after_borg = 'ntlog --keep-for 7d ~/.local/share/emborg/{config_name}.log'

This accumulates the log files as they are created to 
~/.local/share/emborg/{config_name}.log.nt.

If your text editor is configured to use fold markers, you can configure *ntlog* 
to add headers to the composite logfile that contain fold markers.  In doing so 
you can collapse large log entries into a single line folds until they are 
needed, at which point you can easily open the fold and examine the contents of 
the log file.  Here is an example that adds headers with Vim fold markers to the 
composite log file::

    run_after_borg = [
        [
            'ntlog',
            '--keep-for', '1w',
            '--day', 'D MMMM YYYY  {{{{{{1',
            '--entry', 'h:mm A  {{{{{{2',
            '--description', '{cmd_name}',
            '--fold-marker', '{{{{{{ ❬❬❬',
            '/home/me/.local/share/emborg/{config_name}.log',
        ],
    ]

If you use Vim, you can figure it to fold the composite log file with ``:set 
foldmethod=marker``.  You can then open a fold using ``zo`` and close it with 
``zc``.