Skip to content

doc: update readme #149

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rmanibus merged 1 commit into from
Mar 18, 2026
Merged

doc: update readme #149

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 10 additions & 4 deletions docs/user-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -585,9 +585,8 @@ Prefer `*_secret` fields and secret refs in `profiles.yaml`. Supported schemes:

- `env://VAR_NAME`
- `keychain://service/account` (macOS)

`wincred://...` (Windows) and `secret-service://...` (Linux) are planned but not
yet available in the default CLI resolver.
- `wincred://target` (Windows)
- `secret-service://collection/item` (Linux)

Legacy `*_env` fields are still read for backward compatibility, but new writes
should use `*_secret`.
Expand Down Expand Up @@ -668,6 +667,13 @@ directory (`-format dir`). By default, the format is inferred from `-output`.
If `-output` ends with `.zip`, Cloudstic uses ZIP format; otherwise it restores
to a directory.

In directory mode, Cloudstic creates parent directories automatically and, on
macOS and Linux, replays captured metadata on a best-effort basis (for example
mode bits, ownership, modification times, xattrs, and file flags where the
destination filesystem supports them). Existing files are skipped with warnings
instead of being overwritten, so rerunning the same restore into the same output
directory is safe.

```bash
# Restore the latest snapshot
cloudstic restore
Expand Down Expand Up @@ -1167,7 +1173,7 @@ cloudstic backup -source local:~/project -exclude-file .backupignore

Cloudstic walks the directory recursively. Symbolic links are not followed.

**Extended file attributes:** By default, Cloudstic captures POSIX permissions (mode bits), numeric ownership (uid/gid), file creation time (btime, where supported), per-file flags, and extended attributes (xattrs). These are stored in each snapshot and will be used by future restore modes to faithfully recreate file metadata. To control what is captured:
**Extended file attributes:** By default, Cloudstic captures POSIX permissions (mode bits), numeric ownership (uid/gid), file creation time (btime, where supported), per-file flags, and extended attributes (xattrs). Directory restores on macOS and Linux replay this metadata on a best-effort basis where supported by the destination filesystem. Known OS-managed xattrs that are not meaningfully restorable, such as `com.apple.provenance`, are excluded automatically. To control what is captured:

```bash
# Skip all POSIX metadata (mode, uid, gid, btime, flags)
Expand Down
Loading