Restic
@magistr/resticv2026.09.29.1
01README
Drive restic backups from swamp: read repository state, initialize, back up, list snapshots, verify integrity, apply retention and report size — every run lands as versioned swamp data.
Methods:
status— reachable / initialized / snapshot count / newest snapshot age (read-only; use it as the pre-flight step of a backup workflow)init— create the repository; no-op when it already existsbackup— back up paths; restic's summary plus unreadable-file errors (exit 3 is recorded ascomplete: false, not thrown)snapshots— list snapshots, filtered by host/tag/latestcheck— integrity check, optionally reading a subset of pack data; a failed check is data (ok: false), not an exceptionforget— keep policy, dry-run by default, optional prunestats— size and compression statistics
Works with any restic backend. Secrets (password, rest-server basic-auth)
are sensitive global arguments, passed to restic only via environment
variables and redacted from all errors. Requires the restic binary
(>= 0.17) on the host running the method.
02Release Notes
2026.09.29.1
- Initial release:
status,init,backup,snapshots,check,forget,statsmethods for@magistr/restic.
03Models
@magistr/resticv2026.09.29.1extensions/models/restic.ts
Global Arguments
| Argument | Type | Description |
|---|---|---|
| repository | string | restic repository URL, e.g. rest:http://backup.example.lan:8000/laptop/ |
| password | string | Repository encryption password (RESTIC_PASSWORD) |
| restUsername? | string | rest-server HTTP basic-auth user (RESTIC_REST_USERNAME) |
| restPassword? | string | rest-server HTTP basic-auth password (RESTIC_REST_PASSWORD) |
| paths | array | Default paths to back up |
| excludes | array | Exclude patterns passed as --exclude |
| excludeCaches | boolean | Skip directories holding a CACHEDIR.TAG |
| hostname? | string | Override the host name recorded in snapshots |
| tags | array | Tags added to every backup snapshot |
| binary | string | restic executable |
| cacheDir? | string | Override --cache-dir |
fn status()
Read repository state (initialized, snapshot count, newest snapshot age) without modifying it
fn init()
Initialize the repository; no-op when it already exists
fn backup(paths?: array, tags?: array, dryRun: boolean, maxErrors: number)
Back up paths; records the restic summary and any unreadable files
| Argument | Type | Description |
|---|---|---|
| paths? | array | Paths to back up (default: globalArguments.paths) |
| tags? | array | Extra snapshot tags |
| dryRun | boolean | Pass --dry-run |
| maxErrors | number | Max file errors to record |
fn snapshots(host?: string, tag?: string, latest?: number)
List snapshots, optionally filtered by host/tag/latest
| Argument | Type | Description |
|---|---|---|
| host? | string | Only snapshots from this host |
| tag? | string | Only snapshots with this tag |
| latest? | number | Only the newest N per host/path group |
fn check(readDataSubset?: string)
Verify repository integrity, optionally reading a subset of pack data
| Argument | Type | Description |
|---|---|---|
| readDataSubset? | string | Also read and verify pack data, e.g. '5%', '1/10', '2G' |
fn forget(keepLast?: number, keepHourly?: number, keepDaily?: number, keepWeekly?: number, keepMonthly?: number, keepYearly?: number, keepWithin?: string, prune: boolean, dryRun: boolean)
Apply a keep policy (dry-run by default); optionally prune. Fails against an append-only rest-server
| Argument | Type | Description |
|---|---|---|
| keepLast? | number | |
| keepHourly? | number | |
| keepDaily? | number | |
| keepWeekly? | number | |
| keepMonthly? | number | |
| keepYearly? | number | |
| keepWithin? | string | e.g. '30d', '1y6M' |
| prune | boolean | Also prune unreferenced data |
| dryRun | boolean | Only report what would be removed (default true) |
fn stats(mode: enum)
Repository size and compression statistics
| Argument | Type | Description |
|---|---|---|
| mode | enum |
04Stats
A
100 / 100
Downloads
15
Archive size
12.9 KB
- Has README or module doc2/2earned
- README has a code example1/1earned
- README is substantive1/1earned
- Most symbols documented1/1earned
- No slow types (deprecated)1/1earned
- Dependencies pass trust audit2/2earned
- Has description1/1earned
- Platform support declared (or universal)2/2earned
- License declared1/1earned
- Verified public repository2/2earned
Repository
https://github.com/umag/swamp-workspace05Platforms
06Labels