From 36d92740140702abc05a103b610e0f576ff9aafb Mon Sep 17 00:00:00 2001 From: Nathan Heskew Date: Wed, 6 May 2026 15:02:45 -0700 Subject: [PATCH] Document harper-config.yaml backup behavior Adds a "Configuration File Backups" section to the configuration overview describing when Harper writes timestamped copies of harper-config.yaml to {rootPath}/backup/, so the behavior is discoverable via doc search. Co-Authored-By: Claude Opus 4.7 (1M context) --- reference/configuration/overview.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/reference/configuration/overview.md b/reference/configuration/overview.md index 27737986..095953d9 100644 --- a/reference/configuration/overview.md +++ b/reference/configuration/overview.md @@ -78,6 +78,25 @@ See [Configuration Operations](./operations.md) for the full `set_configuration` --- +## Configuration File Backups + +When `harper-config.yaml` is updated through the [Operations API](#4-operations-api) (`set_configuration`) or by passing CLI arguments / environment variables to Harper at startup, Harper writes a timestamped copy of the previous file to `{rootPath}/backup/` before applying the change. + +Backup files are named `-harper-config.yaml.bak`, for example: + +``` +hdb/backup/2026-05-06T14-22-08.123Z-harper-config.yaml.bak +``` + +Notes: + +- Backups are not produced when you edit `harper-config.yaml` directly — Harper only sees that change on its next start. +- The `HARPER_DEFAULT_CONFIG` and `HARPER_SET_CONFIG` mechanisms do not produce timestamped backups; their provenance is tracked separately in `{rootPath}/backup/.harper-config-state.json` (see [State Tracking](#state-tracking)). +- Backups are not rotated. Old `.bak` files accumulate in `{rootPath}/backup/` until you remove them. +- A failure to write the backup is logged at `error` level and does not block the configuration update. + +--- + ## Custom Config File Path To specify a custom config file location at install time, use the `HDB_CONFIG` variable: