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:
1 parent
a29517e2fc
commit
248204fe41
2 files changed
+35
-6
No files matched your search
+4
-4
@@ -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
|
||||
|
||||
|
||||
@@ -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.
|
||||
Reference in new issue
Block a user