* Document Python/external-rsync backend differences
- Note that mixing --external-rsync (which can recreate device/socket
entries via --archive's -D) with the default Python hardlink-forward
step is unsafe: _recursive_hardlink() only understands files,
symlinks, and directories and errors on anything else.
- Note that --dry-run is I/O-free with --external-rsync but still
fully copies into a throwaway staging directory with the Python
backend, though neither leaves a lasting change.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* Clarify external-rsync dry-run description
Copilot review feedback on PR #20: rsync's --dry-run still reads and
stats source files to compute what would change, it just avoids
writing to the destination - "performs no I/O" overstated that.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---------
Co-authored-by: Maxim Shulga <maxim.shulga@alludo.com>
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
* Document ACL, xattr, sparse-file, and hardlink backup behavior
Extend the README Limitations section with the filesystem-feature
behaviors that weren't documented: ACLs/xattrs/flags are never
preserved by either backend, sparse files are materialized as full
allocated copies, source-side hardlinks are not preserved as
hardlinks in the backup, and ownership is only preserved when
running as root.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
* Soften README timestamp/ownership claims for external-rsync backend
Nanosecond mtime precision and 'silently logged chown failures' are
Python-backend specifics that don't hold for --external-rsync: rsync's
own timestamp precision depends on the build/filesystem, and it skips
disallowed ownership changes itself rather than going through our
logging path.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---------
Co-authored-by: Maxim Shulga <maxim.shulga@alludo.com>
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
* Implement restore command
Add a restore subcommand alongside the existing backup command:
- curateipsum/restore.py: restore_snapshot() and verify_restored(),
reusing fs.scantree/copy_direntry/rm_direntry so metadata handling
(mode, ownership, timestamps, symlinks) matches backup exactly.
- backup.find_backup(): resolve a snapshot by name or latest.
- cli.py: argparse subcommands (backup/restore), with backup implied
when no subcommand is given so existing invocations keep working.
Restore supports dry-run (creates nothing), partial restore by
snapshot-relative path, an overwrite policy (never/always), a
destination-inside-snapshot boundary check, and manifest-checksum
verification of restored content. It takes the same backups_lock a
backup does, since retention could otherwise delete the snapshot
being restored out from under it.
Closes P1 'Provide a safe restoration workflow' in IMPROVEMENTS.md.
* Address Copilot review: symlink-escape boundary check, docstring fix
- restore_snapshot() and verify_restored() now canonicalize each
destination path and refuse to operate on it if it resolves outside
dest_dir - a symlink planted under dest_dir (by another process, or
left over from a prior run) could otherwise redirect a write, delete,
or read outside the intended destination.
- Fixed restore_snapshot()'s docstring: the skipped-paths list reports
what would be skipped on dry-run too, it isn't always empty.
* Address Copilot suppressed findings: stream plan_restore, restore-specific lock message
- plan_restore() is now a generator instead of building a full list in
memory, matching fs.scantree()'s streaming style everywhere else in
the codebase.
- restore CLI logs a restore-specific message on lock-acquire failure,
since set_backups_lock()'s own log line talks about a 'previous
backup', which read wrong for a restore.
* Fix PATH docs: snapshot-relative means source-basename-prefixed
README and CLI help examples for restore's PATH argument omitted the
source directory's basename, which backup.initiate_backup() always
prefixes onto snapshot-relative paths - the given examples would have
matched nothing in an actual snapshot.
---------
Co-authored-by: Maxim Shulga <maxim.shulga@alludo.com>
* 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>
- Project overview and features
- Installation and usage instructions
- Detailed explanation of how hardlink-based backups work
- Command-line options and examples
- Backup structure and retention policy details
- Development and testing information
