# Difference Scanner for Borg Backup

Given a [Borg](https://borgbackup.readthedocs.io/) repo, and a list of excluded paths, this script tells you what's new on your filesystem since the most recent backup.

You can then investigate the files and choose to either keep them, delete them entirely, or add them to your excludes file so they don't go in the backup.

Re-run to see the new report and repeat until you're happy.

## Get started

1. You need [node.js](https://nodejs.org/en) version 22 or later.
1. Clone this repo
1. `npm install`
1. `node src/scan.js <path to borg repo> <path to excludes file>`

## Information about repo unlocking

Interactive password prompts from Borg are not supported, so you'll need to set your `BORG_PASSPHRASE` or whichever environment variable before running the script.

## Information about excludes

Only `--exclude` style is supported, `--pattern` isn't. Only `pp:` and `sh:` patterns are supported from the excludes file, not `fm:`, `re:`, or `pf:` (Patches welcome!)

The excludes file is scanned using this regular expression: `/(?:^|['"])pp:([^'"\n]+)/gm`

That means this file format - one exclude pattern per line (like `--exclude-from`) - IS supported:

```
pp:/var/home/cadence/.cache
pp:/var/home/cadence/.config/vivaldi/Default/Service Worker/CacheStorage
sh:/var/home/cadence/.config/*/Cache
sh:/var/home/cadence/.config/*/CachedData
pp:/var/home/cadence/.local/share/NuGet/http-cache
```

And this file format - patterns embedded into a shell script - IS supported too:

```
set backup_exclude \
	# Cache
	'pp:/var/home/cadence/.cache' \
	'pp:/var/home/cadence/.config/vivaldi/Default/Service Worker/CacheStorage' \
	'sh:/var/home/cadence/.config/*/Cache' \
	'sh:/var/home/cadence/.config/*/CachedData' \
	'pp:/var/home/cadence/.local/share/NuGet/http-cache' \
```

If your excludes file is formatted differently, you'll have to figure it out from the regular expression.

## Dependency justification

* (8) glob: This was the fastest and most efficient filesystem crawler out of the ones I tried on npm (including fdir)
* (0) minimatch: Happens to be required by glob.
* (0) path-scurry: Required by glob.