-
How-to guides
- π₯ Set up backups
- π Make per-application backups
- π Provide your passwords
- βοΈ Make backups redundant
- π Deal with very large backups
- π Inspect your backups
- π¨ Monitor your backups
- π€ Extract a backup
- ποΈ Backup your databases
- πΈ Snapshot your filesystems
- π§Ή Add preparation and cleanup steps
- πΎ Backup to a removable drive/server
- π§ Run arbitrary Borg commands
- π₯ Customize warnings/errors
- π¦ Upgrade borgmatic/Borg
- ποΈ Develop on borgmatic
- Reference guides
Source code
To get set up to develop on borgmatic, first install pipx
to make managing your borgmatic environment easier without impacting other
Python applications on your system.
Then, clone borgmatic via HTTPS or SSH:
git clone https://projects.torsion.org/borgmatic-collective/borgmatic.git
Or:
git clone ssh://git@projects.torsion.org:3022/borgmatic-collective/borgmatic.git
Finally, install borgmatic "editable" so that you can run borgmatic actions during development to make sure your changes work:
cd borgmatic
pipx ensurepath
pipx install --editable .
Or to work on the Apprise hook, change that last line to:
pipx install --editable .[Apprise]
To get oriented with the borgmatic source code, have a look at the source code reference.
Automated tests
Assuming you've cloned the borgmatic source code as described above and you're
in the borgmatic/
working copy, install tox, which is used for setting up
testing environments. You can either install a system package of tox (likely
called tox
or python-tox
) or you can install tox with pipx:
pipx install tox
Finally, to actually run tests, run tox from inside the borgmatic sourcedirectory:
tox
Code formatting
If when running tests, you get an error from the Black code formatter about files that would be reformatted, you can ask Black to format them for you via the following:
tox -e black
And if you get a complaint from the isort Python import orderer, you can ask isort to order your imports for you:
tox -e isort
Similarly, if you get errors about spelling mistakes in source code, you can ask codespell to correct them:
tox -e codespell
End-to-end tests
borgmatic additionally includes some end-to-end tests that integration test
with Borg and supported databases for a few representative scenarios. These
tests don't run by default when running tox
, because they're relatively slow
and depend on containers for runtime dependencies. These tests do run on the
continuous integration (CI) server, and running them on your developer machine
is the closest thing to dev-CI parity.
If you would like to run the end-to-end tests, first install Docker (or Podman; see below) and Docker Compose. Then run:
scripts/run-end-to-end-tests
This script assumes you have permission to run docker
. If you don't, then
you may need to run with sudo
.
Podman
New in version 1.7.12 borgmatic's end-to-end tests optionally support using rootless Podman instead of Docker.
Setting up Podman is outside the scope of this documentation, but here are some key points to double-check:
- Install Podman and your desired networking support.
- Configure
/etc/subuid
and/etc/subgid
to map users/groups for the non-root user who will run tests. - Create a non-root Podman socket for that user:
systemctl --user enable --now podman.socket systemctl --user start --now podman.socket
Then you'll be able to run end-to-end tests as per normal, and the test script will automatically use your non-root Podman socket instead of a Docker socket.
Code style
Start with PEP 8. But then, apply the following deviations from it:
- For strings, prefer single quotes over double quotes.
- Limit all lines to a maximum of 100 characters.
- Use trailing commas within multiline values or argument lists.
- For multiline constructs, put opening and closing delimiters on lines separate from their contents.
- Within multiline constructs, use standard four-space indentation. Don't align indentation with an opening delimiter.
- In general, spell out words in variable names instead of shortening them.
So, think
index
instead ofidx
. There are some notable exceptions to this though (likeconfig
). - Favor blank lines around logical code groupings,
if
statements,return
s, etc. Readability is more important than packing code tightly. - Import fully qualified Python modules instead of importing individual
functions, classes, or constants. E.g., do
import os.path
instead offrom os import path
. (Some exceptions to this are made in tests.) - Only use classes and OOP as a last resort, such as when integrating with Python libraries that require it.
- Prefer functional code where it makes sense, e.g. when constructing a command (to subsequently execute imperatively).
borgmatic uses the Black code formatter, the Flake8 code checker, and the isort import orderer, so certain code style requirements are enforced when running automated tests. See the Black, Flake8, and isort documentation for more information.
Continuous integration
Each commit to main triggers a continuous integration build which runs the test suite and updates documentation. These builds are also linked from the commits for the main branch.
Documentation development
Updates to borgmatic's documentation are welcome. It's formatted in Markdown
and located in the docs/
directory in borgmatic's source, plus the
README.md
file at the root.
To build and view a copy of the documentation with your local changes, run the following from the root of borgmatic's source code:
scripts/dev-docs
This requires Docker (or Podman; see below) to be installed on your system.
This script assumes you have permission to run docker
. If you don't, then
you may need to run with sudo
.
After you run the script, you can point your web browser at http://localhost:8080 to view the documentation with your changes.
To close the documentation server, ctrl-C the script. Note that it does not currently auto-reload, so you'll need to stop it and re-run it for any additional documentation changes to take effect.
Podman
New in version 1.7.12 borgmatic's developer build for documentation optionally supports using rootless Podman instead of Docker.
Setting up Podman is outside the scope of this documentation. But once you
install and configure Podman, then scripts/dev-docs
should automatically use
Podman instead of Docker.
Improve this documentation
Have an idea on how to make this documentation even better? Use our issue tracker to send your feedback!