diff --git a/NEWS b/NEWS index fe7a74a3..078d25de 100644 --- a/NEWS +++ b/NEWS @@ -10,6 +10,9 @@ * #1303: For the MariaDB hook, include only a subset of system data when dumping the "mysql" system database (or "all" databases), so the dump is actually restorable. See the documentation for more information: https://torsion.org/borgmatic/reference/configuration/data-sources/mariadb/ + * Add an experimental "borgmatic browse" action, a console UI for browsing your backups. See the + documentation for more information: + https://torsion.org/borgmatic/how-to/inspect-your-backups/#browsing-backups * Update the KeePassXC credential hook to support KeePassXC's secret service integration. See the documentation for more information: https://torsion.org/borgmatic/reference/configuration/credentials/keepassxc/ diff --git a/docs/Dockerfile b/docs/Dockerfile index 2f2f0e40..389be793 100644 --- a/docs/Dockerfile +++ b/docs/Dockerfile @@ -5,7 +5,7 @@ RUN apk add --no-cache py3-pip py3-ruamel.yaml py3-ruamel.yaml.clib RUN pip install --break-system-packages --no-cache /app && borgmatic config generate && borgmatic config generate --destination /etc/borgmatic --split && chmod +r /etc/borgmatic/*.yaml RUN mkdir /command-line \ && borgmatic --help > /command-line/global.txt \ - && for action in repo-create transfer create prune compact check delete extract config "config bootstrap" "config generate" "config validate" "config show" export-tar mount umount repo-delete restore repo-list list repo-info info break-lock "key export" "key import" "key change-passphrase" recreate diff borg; do \ + && for action in repo-create transfer create prune compact check delete extract config "config bootstrap" "config generate" "config validate" "config show" export-tar mount umount repo-delete restore repo-list list repo-info info break-lock "key export" "key import" "key change-passphrase" recreate diff browse borg; do \ borgmatic $action --help > /command-line/${action/ /-}.txt; done RUN /app/docs/fetch-contributors >> /contributors.html diff --git a/docs/_includes/snippet/command-line/sample.md b/docs/_includes/snippet/command-line/sample.md index 91013a84..8250a378 100644 --- a/docs/_includes/snippet/command-line/sample.md +++ b/docs/_includes/snippet/command-line/sample.md @@ -1,5 +1,5 @@ Here's the command-line help for this action in the [most recent version of borgmatic](https://projects.torsion.org/borgmatic-collective/borgmatic/releases). -If you're using an older version, some of these flags may not work, and you -should instead run the action with `--help` to see the flags specific to your -borgmatic version. +If you're using an older version, some of these flags may not work (or the action +may be missing entirely). You should instead run the action with `--help` to see +the flags and actions specific to your borgmatic version. diff --git a/docs/how-to/inspect-your-backups.md b/docs/how-to/inspect-your-backups.md index 02997c9f..3f1517f6 100644 --- a/docs/how-to/inspect-your-backups.md +++ b/docs/how-to/inspect-your-backups.md @@ -135,3 +135,42 @@ is, patterns are _not_ taken into consideration. If you require this, supply the See the [Borg](https://borgbackup.readthedocs.io/en/stable/usage/diff.html) documentation for information on output format, what is compared, and more. + + +## Browsing backups + +New in version 2.1.6 Experimental feature borgmatic has an +experimental console UI for browsing your repositories, archives, and files. +This is handy if you want to quickly look at the contents of your backups—but +without messing with borgmatic's command-line. + +Depending on how you installed borgmatic, it may not have come with the +necessary Python libraries to support the browse action. For instance, if you +originally [installed borgmatic with +uv](https://torsion.org/borgmatic/how-to/install-borgmatic/), run the following +to install the libraries needed for the browse action: + +```bash +sudo uv tool install borgmatic[browse] +``` + +Omit `sudo` if borgmatic is installed as a non-root user. + +Once the libraries are installed, run the following to access the browse action: + +```bash +borgmatic browse +``` + +This launches a console UI where you can select a borgmatic configuration file, +select a Borg repository from it, select an archive in that repository, and even +browse the backed up files in that archive. + +Use the keyboard or the mouse to navigate the UI. The footer at the bottom of +the screen shows some of the available keys. Logs shows up directly in the UI, +although hidden by default. + +Please [provide +feedback](https://torsion.org/borgmatic/#support-and-contributing) if you find +this feature useful—or even if you don't, but would like it to become useful. diff --git a/docs/reference/command-line/actions/browse.md b/docs/reference/command-line/actions/browse.md new file mode 100644 index 00000000..c9fee5d7 --- /dev/null +++ b/docs/reference/command-line/actions/browse.md @@ -0,0 +1,17 @@ +--- +title: browse +eleventyNavigation: + key: browse + parent: 🎬 Actions +--- + +Experimental feature {% include snippet/command-line/sample.md %} + +``` +{% include borgmatic/command-line/browse.txt %} +``` + + +## Related documentation + + * [Inspect your backups](https://torsion.org/borgmatic/how-to/inspect-your-backups/)