# 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.**