From 248204fe410ce542eadd6430368900f4ec44103c Mon Sep 17 00:00:00 2001 From: Maksim Shulga Date: Tue, 4 Aug 2026 04:49:00 +0000 Subject: [PATCH] Add immediate safety warning to README (#12) * Add immediate safety warning to README - Remove the production-use claim from Project Status. - Mark the project experimental until the P0 data-safety checklist passes, with a prominent warning banner up top. - Add a Limitations section: warn against modifying hardlinked snapshots in place, document the lack of a restore command, and note special-entry exclusion and symlink-preservation behavior. - Check off the corresponding IMPROVEMENTS.md acceptance criteria. * Qualify special-entry exclusion limitation to the Python implementation --external-rsync uses rsync's --archive flag, which copies/recreates FIFOs, sockets, and device nodes instead of excluding them - the exclusion behavior only applies to the default Python implementation. * Qualify device-node recreation reliability under --external-rsync rsync -a implies -D (devices/specials), but creating device nodes typically requires root on the destination - without it rsync may skip or fail on them rather than reliably recreating them. --------- Co-authored-by: Maxim Shulga --- IMPROVEMENTS.md | 8 ++++---- README.md | 33 +++++++++++++++++++++++++++++++-- 2 files changed, 35 insertions(+), 6 deletions(-) diff --git a/IMPROVEMENTS.md b/IMPROVEMENTS.md index 369629e..638428f 100644 --- a/IMPROVEMENTS.md +++ b/IMPROVEMENTS.md @@ -120,10 +120,10 @@ Acceptance criteria: ### Add an immediate safety warning -- [ ] Remove the current production-use claim from `README.md`. -- [ ] State that the software is experimental until the P0 release gate passes. -- [ ] Warn users not to modify hardlinked snapshots in place. -- [ ] Document current recovery and metadata limitations honestly. +- [x] Remove the current production-use claim from `README.md`. +- [x] State that the software is experimental until the P0 release gate passes. +- [x] Warn users not to modify hardlinked snapshots in place. +- [x] Document current recovery and metadata limitations honestly. ## P1 - Recovery and release readiness diff --git a/README.md b/README.md index 3251592..a89d250 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,10 @@ # cura-te-ipsum +> **⚠️ Experimental — not yet safe for production use.** This project is +> still working through its data-safety checklist (see +> [IMPROVEMENTS.md](IMPROVEMENTS.md)). Do not rely on it as your only +> backup, and see [Limitations](#limitations) before using it. + **cura-te-ipsum** is a space-efficient incremental backup utility for Linux and macOS that uses hardlinks to minimize storage usage while maintaining complete directory snapshots. Similar to Time Machine or rsnapshot, cura-te-ipsum creates backups that appear as complete directory trees but intelligently share unchanged files between snapshots, dramatically reducing storage requirements. @@ -127,6 +132,28 @@ backups/ .backups_lock # lock file (only during backup) ``` +## Limitations + +- **Never modify files inside a backup snapshot in place.** Unchanged + files are hardlinked between snapshots to save space, so editing or + truncating a file in one snapshot changes that same file's content + in every other snapshot sharing its inode. Treat every snapshot + directory as read-only; copy files out before editing them. +- **No dedicated restore command.** Recovering data means manually + copying files out of a snapshot directory - there is no restore + workflow with dry-run, partial restore, or overwrite-policy support + yet. +- **Special filesystem entries (FIFOs, sockets, device nodes) are + excluded, not backed up** - but only with the default Python + implementation, which records them in the snapshot manifest as + exclusions rather than copying them. With `--external-rsync`, + `rsync`'s `--archive` flag attempts to recreate these entries + instead, though device nodes typically require root privileges on + the destination and may be skipped or fail without them. +- **Symlinks are preserved as symlinks**, including ones pointing + outside the source tree - their targets are never followed or + copied. + ## Development ### Running Tests @@ -146,6 +173,8 @@ Maks Snegov () ## Project Status -Development Status: Pre-Alpha +Development Status: Pre-Alpha, experimental -This project is actively maintained and used in production for personal backups, but the API and configuration options may change in future releases. +This project is under active development and has not yet completed +its data-safety checklist (see [IMPROVEMENTS.md](IMPROVEMENTS.md)). +The API and configuration options may change in future releases.