borgmatic/docs/how-to/develop-on-borgmatic.md

---
title: 🏗️ How to develop on borgmatic
eleventyNavigation:
  key: 🏗️ Develop on borgmatic
  parent: How-to guides
  order: 15
---
<span data-pagefind-weight="0.25">

To get set up to develop on borgmatic, first [`install
uv`](https://docs.astral.sh/uv/) to make managing your borgmatic environment
easier without impacting other Python applications on your system.

Then, clone borgmatic via HTTPS or SSH:

```bash
git clone https://projects.torsion.org/borgmatic-collective/borgmatic.git
```

Or:

```bash
git clone ssh://git@projects.torsion.org:3022/borgmatic-collective/borgmatic.git
```

Finally, install borgmatic
"[editable](https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs)"
so that you can run borgmatic actions during development to make sure your
changes work:

```bash
cd borgmatic
uv tool update-shell
uv tool install --editable .
```

Or to work on the [Apprise
hook](https://torsion.org/borgmatic/reference/configuration/monitoring/apprise/),
change that last line to:

```bash
uv tool install --editable .[Apprise]
```

To get oriented with the borgmatic source code, have a look at the [source
code reference](https://torsion.org/borgmatic/reference/source-code/).


### Source packages

Each [borgmatic
release](https://projects.torsion.org/borgmatic-collective/borgmatic/releases)
also has source packages available. These include automated tests and serve as
a good starting point for creating third-party borgmatic packages.


## Automated tests

Assuming you've cloned the borgmatic source code as described above and you're
in the `borgmatic/` working copy, install [tox](https://tox.wiki/) and
[tox-uv](https://github.com/tox-dev/tox-uv) using uv, which are used for setting
up testing environments:

```bash
uv tool install tox --with tox-uv
```

Also install [Ruff](https://docs.astral.sh/ruff/), which borgmatic uses for code
linting and formatting:

```bash
uv tool install ruff
```

Finally, to actually run tests, run tox from inside the borgmatic source
directory:

```bash
tox
```

That runs tests against all supported versions of Python, which takes a while.
So if you'd only like to run tests against a single version of Python, e.g.
Python 3.13:

```bash
tox -e py313
```


### Code style

If when running tests, you get an error from Ruff's linter about files that
don't meet linting requirements, you can ask Ruff to attempt to fix them for you
via the following:

```bash
tox -e lint-fix
```

And if you get an error from the Ruff's code formatter about files that would be
reformatted, you can ask Ruff to format them for you:

```bash
tox -e format
```

Similarly, if you get errors about spelling mistakes in source code, you can
ask [codespell](https://github.com/codespell-project/codespell) to correct
them:

```bash
tox -e spell
```

See the [code style
documentation](https://torsion.org/borgmatic/reference/source-code/#code-style)
for more specifics about borgmatic's own code style.


### 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](https://docs.docker.com/compose/install/). Then run:

```bash
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

borgmatic's end-to-end tests optionally support using
[rootless](https://github.com/containers/podman/blob/main/docs/tutorials/rootless_tutorial.md)
[Podman](https://podman.io/) 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:
   ```bash
   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.


## Continuous integration

Each commit to
[main](https://projects.torsion.org/borgmatic-collective/borgmatic/branches)
triggers [a continuous integration
build](https://projects.torsion.org/borgmatic-collective/borgmatic/actions)
which runs the test suite and updates
[documentation](https://torsion.org/borgmatic/). These builds are also linked
from the [commits for the main
branch](https://projects.torsion.org/borgmatic-collective/borgmatic/commits/branch/main).


## 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:

```bash
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`.

### How to choose a different port

You can choose a different listening port in two ways:

#### 1. Modify the `.env` file

1.  Open `docs/.env`.
2.  Change `PORT=8080` to your desired port number (e.g., `PORT=3000`).
3.  Run the development script: `scripts/dev-docs`.

#### 2. Use an environment variable

Alternatively, you can override the port directly from your terminal without
modifying any files:

```bash
PORT=3000 ./scripts/dev-docs
```

After you run the script, you can point your web browser at
http://localhost:8080/borgmatic/ (or your chosen port) 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

borgmatic's developer build for documentation optionally supports using
[rootless](https://github.com/containers/podman/blob/main/docs/tutorials/rootless_tutorial.md)
[Podman](https://podman.io/) instead of Docker.

Setting up Podman is outside the scope of this documentation. But once you
install and configure Podman, then `scripts/dev-docs` automatically uses Podman
instead of Docker and [Podman
Compose](https://github.com/containers/podman-compose) (if present) instead of
Docker Compose. However Podman works fine with either Podman Compose or Docker
Compose.


## Use of generative AI

Please do not use AI agents to modify this codebase. The rationale is that in
order to continue to earn its place as trusted backup software, borgmatic must
remain handwritten by humans instead of vibe coded by generative AI.

Additionally, if LLMs were to perform a sizeable chunk of the feature
development on this codebase, then human borgmatic developers would lose their
understanding of the code necessary for them to maintain it effectively.

Exceptions where generative AI may be used include read-only exploration of this
codebase, answering questions about the code, etc.

</span>