165 lines
2.9 KiB
Markdown
165 lines
2.9 KiB
Markdown
# locutus
|
||
|
||
*A simple, opinionated wrapper for the venerable **[BorgBackup](https://www.borgbackup.org/)**.*
|
||
|
||
## Features
|
||
|
||
* **Friendlier CLI:** No need to remember archive names or full repo paths.
|
||
* **Index-based archive access:** Refer to backups by index (most recent is 0), or by name.
|
||
* **Scriptable:** All commands are suitable for cron or other automation.
|
||
* **Transparent:** Directly uses Borg; never hides or obfuscates underlying repo. Backups can be fully managed by borg directly, made easier by sourcing locutus.rc in your shell.
|
||
|
||
---
|
||
|
||
## Installation
|
||
|
||
Requires Python 3.11+, [BorgBackup](https://www.borgbackup.org/) (CLI), and a UNIX-like OS.
|
||
|
||
### From source
|
||
|
||
Clone the repo and install with [uv](https://github.com/astral-sh/uv) or pip:
|
||
|
||
```sh
|
||
git clone https://github.com/figtree-dev/locutus.git
|
||
cd locutus
|
||
uv tool install .
|
||
```
|
||
|
||
For development/testing:
|
||
|
||
```sh
|
||
uv venv
|
||
uv source .venv/bin/activate
|
||
uv sync --extra dev
|
||
```
|
||
|
||
(See `pyproject.toml` for dev dependencies.)
|
||
|
||
---
|
||
|
||
## Quick Start
|
||
|
||
### 1. **Setup your backup environment**
|
||
|
||
```sh
|
||
locutus init
|
||
```
|
||
|
||
* Prompts for your repo and passphrase, creates the rc file.
|
||
* Edit `~/.config/locutus/locutus.toml` to set your include/exclude/prune rules.
|
||
|
||
### 2. **Create a backup**
|
||
|
||
```sh
|
||
locutus backup
|
||
```
|
||
|
||
### 3. **List archives**
|
||
|
||
```sh
|
||
locutus list
|
||
```
|
||
|
||
* Archives are in chronological order with reverse indexing, such as `1: ...`, `0: ...`.
|
||
|
||
### 4. **Mount an archive or the entire repo**
|
||
|
||
```sh
|
||
locutus mount 0 ~/mnt/backup # mount most recent archive
|
||
locutus mount ~/mnt/backup # mount all archives
|
||
```
|
||
|
||
### 5. **Restore files from an archive**
|
||
|
||
```sh
|
||
locutus restore 0 ~/restore-dir
|
||
```
|
||
|
||
### 6. **Unmount a mountpoint**
|
||
|
||
```sh
|
||
locutus umount ~/mnt/backup
|
||
```
|
||
|
||
---
|
||
|
||
## Configuration
|
||
|
||
* Main config: `~/.config/locutus/locutus.toml` (edit by hand, see sample below)
|
||
* Profile/RC: `~/.config/locutus/locutus.rc` (holds BORG\_REPO and BORG\_PASSPHRASE)
|
||
|
||
**Sample **`locutus.toml`**:**
|
||
|
||
```toml
|
||
[includes]
|
||
paths = [
|
||
"/etc",
|
||
"/home",
|
||
"/var/www"
|
||
]
|
||
|
||
[excludes]
|
||
paths = [
|
||
"*.cache",
|
||
"/tmp",
|
||
"/home/*/Downloads"
|
||
]
|
||
|
||
[prune]
|
||
keep_last = 7
|
||
keep_daily = 7
|
||
keep_weekly = 4
|
||
keep_monthly = 6
|
||
|
||
[compact]
|
||
enabled = true
|
||
```
|
||
|
||
**Sample **`locutus.rc`**:**
|
||
|
||
```sh
|
||
export BORG_REPO="user@host:/path/to/repo"
|
||
export BORG_PASSPHRASE="your-strong-password"
|
||
```
|
||
|
||
---
|
||
|
||
## Development
|
||
|
||
* Source code: [`src/locutus/`](src/locutus/)
|
||
* Tests: [`test/`](test/)
|
||
* Run tests:
|
||
|
||
```sh
|
||
uv venv
|
||
source .venv/bin/activate
|
||
uv sync --extra dev
|
||
pytest
|
||
```
|
||
* All CLI entry points are in `main.py` with subcommands for each workflow.
|
||
|
||
---
|
||
|
||
## Limitations / Roadmap
|
||
|
||
* Linux/UNIX only (uses Borg and fusermount).
|
||
* No built-in scheduling (use cron/systemd).
|
||
* One config/profile at a time.
|
||
|
||
---
|
||
|
||
## License
|
||
|
||
GPLv3 (see `LICENSE`)
|
||
|
||
---
|
||
|
||
## Author
|
||
|
||
Alexander Wainwright ([code@figtree.dev](mailto:code@figtree.dev))
|
||
|
||
---
|
||
|
||
**Pull requests welcome.**
|
||
|