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 <maxim.shulga@alludo.com>
This commit is contained in:
snegovandMaxim Shulga authored and GitHub committed 2026-08-04 04:49:00 +00:00
1 parent a29517e2fc
commit 248204fe41
2 files changed
+35 -6

No files matched your search

+4 -4
View File
@@ -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
+31 -2
View File
@@ -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 (<snegov@spqr.link>)
## 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.