Metadata-Version: 2.1
Name: borg_space
Version: 0.4.0
Summary: Accessory for Emborg used to report and track the size of your Borg repositories
Keywords: emborg,borg,backups
Author-email: Ken Kundert <emborg@nurdletech.com>
Requires-Python: >=3.6
Description-Content-Type: text/x-rst
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Natural Language :: English
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Utilities
Requires-Dist: appdirs
Requires-Dist: arrow>=0.15
Requires-Dist: docopt
Requires-Dist: emborg>=1.31
Requires-Dist: inform>=1.26
Requires-Dist: matplotlib
Requires-Dist: nestedtext
Requires-Dist: quantiphy
Project-URL: homepage, https://emborg.readthedocs.io
Project-URL: repository, https://github.com/kenkundert/borg-space

Borg-Space — Report and track the size of your Borg repositories
================================================================

.. image:: https://pepy.tech/badge/borg-space/month
    :target: https://pepy.tech/project/borg-space

.. image:: https://img.shields.io/pypi/v/borg-space.svg
    :target: https://pypi.python.org/pypi/borg-space

.. image:: https://img.shields.io/pypi/pyversions/borg-space.svg
    :target: https://pypi.python.org/pypi/borg-space/

:Author: Ken Kundert
:Version: 0.4.0
:Released: 2022-10-22

*Borg-Space* is an accessory for `Emborg <https://emborg.readthedocs.io>`_.  It
reports on the space consumed by your *BorgBackup* repositories.  You can get
this information using the ``emborg info`` command, but there are several
reasons to prefer *Borg-Space*.  First, the *info* command gives a great deal of
information, whereas *Borg-Space* only reports the space consumed by the
repository, so is much more compact.  Second, the output message is user
customizable. Third, *Borg-Space* can record the size of your repositories each
time it is run so you can track the space requirements over time.  Finally,
*Borg-Space* can graph the recorded values.

To show the size of one or more *Emborg* configurations, simply run::

    # borg-space root
    root: 2.81 GB

If you do not specify a config, you get *Emborg*'s default config.

You can specify any number of configurations, and they can be composite
configs::

    > borg-space home cache
    rsync: 2.81 GB
    borgbase: 2.44 GB
    cache: 801 MB

You can change the message by giving a template::

    > borg-space -m 'Repository for {config} is now {size}." home
    Repository for rsync is now 2.81 GB.
    Repository for borgbase is now 2.44 GB.

The *config* key takes Python string format codes and the *size* key takes
`QuantiPhy
<https://quantiphy.readthedocs.io/en/stable/user.html#string-formatting>`_
format codes::

    > borg-space -m '{config>12}: {size:b}." home
           rsync: 2.62 GiB
        borgbase: 2.26 GiB

You can record the sizes with::

    > borg-space -r home

The sizes are added to the file ``~/.local/share/emborg/{config}-size.nt``.

Typically you do not manually run *Borg-Space* to record the sizes of your
repositories.  Instead, you can record sizes automatically in two different
ways.  In the first, you simply use crontab to automatically record the sizes at
fixed times::

    00 12 * * *  borg-space -q -r home

In this case the command runs at noon every day and uses the ``-q`` option to
suppress the output to stdout.  This approach can be problematic if *Emborg*
needs access to SSH or GPG keys to run.

The other approach is to add *Borg-Space* to the *run_after_backup* setting in
your *Emborg* configs.  That way it is run every time you run backup::

    run_after_backup = [
        'borg-space -r -m "Repository is now {{size}}." {config_name}'
    ]

*Emborg* also uses braces to interpolate values, so they are doubled-up in the
*Borg-Space* command to escape them (except for removing the second brace,
*Emborg* ignores double braces).

Once you have recorded some values, you can graph them using::

    > borg-space -g home

This displays the graph on the screen. Alternately, you can save the graph to 
a file in SVG format using::

    > borg-space -s home.svg home

I routinely monitor the repositories for over a dozen hosts, and to make it 
convenient I create a composite *Emborg* configuration containing all the hosts, 
and then use the ``--log-y`` option so that I can easily see all the results 
scaled nicely on the same graph::

    > borg-space -l all


Installation
------------

Install with::

    > pip3 install --user borg-space


Releases
--------

Latest development release
..........................
| Version: 0.4.0
| Released: 2022-10-22


0.4.0 (2022-10-22)
..................
- Tweak graph axes labels.


0.3.0 (2022-03-21)
..................
- Upgrade required to support *Emborg* version 1.31.


0.2.0 (2021-10-01)
..................
- Fixed incompatibility with *Emborg* version 1.26.


0.1.0 (2021-09-30)
..................
- Added ability to save graph as SVG file.


0.0.0 (2021-09-25)
..................
- Initial release

