sbackup-cli 1.0.0__tar.gz → 2.0.0__tar.gz

sbackup_cli-2.0.0/PKG-INFO

@@ -0,0 +1,692 @@
+Metadata-Version: 2.4
+Name: sbackup-cli
+Version: 2.0.0
+Summary: 智能文件夹备份工具，支持增量备份和自定义配置
+Author-email: xiatianxuan <xiatianxuan2025@163.com>
+License: GPL-3.0
+Project-URL: Homepage, https://github.com/xiatianxuan/sbackup
+Project-URL: Repository, https://github.com/xiatianxuan/sbackup
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Archiving :: Backup
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: minio>=7.2.20
+Requires-Dist: paramiko>=4.0.0
+Requires-Dist: py7zr>=1.1.0
+Requires-Dist: reedsolo>=1.7.0
+Requires-Dist: tqdm>=4.67.3
+Requires-Dist: watchdog>=6.0.0
+Requires-Dist: zstandard>=0.25.0
+Dynamic: license-file
+
+# Sbackup
+
+[![Python](https://img.shields.io/badge/Python-3.10+-3776AB?logo=python&logoColor=white)](https://www.python.org/)
+[![License](https://img.shields.io/badge/License-GPL--3.0-green)](LICENSE)
+[![PyPI](https://img.shields.io/pypi/v/sbackup-cli?color=blue)](https://pypi.org/project/sbackup-cli/)
+[![Tests](https://img.shields.io/badge/tests-940%20passed-brightgreen)](.github/workflows/ci.yml)
+[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey)]()
+
+> A lightweight, efficient folder backup tool with CLI support for managing backup strategies.
+
+[English](README.md) | [Deutsch](docs/readme/README_de.md) | [Espanol](docs/readme/README_es.md) | [Francais](docs/readme/README_fr.md) | [Portugues](docs/readme/README_pt.md) | [Pycckuu](docs/readme/README_ru.md) | [日本語](docs/readme/README_ja.md) | [한국어](docs/readme/README_ko.md) | [中文](docs/readme/README_zh.md)
+
+- [Introduction](#introduction)
+- [Features](#features)
+- [Getting Started](#getting-started)
+  - [Installation](#installation)
+  - [Usage](#usage)
+- [Configuration](#configuration)
+  - [Example Configuration](#example-configuration)
+- [SFTP Remote Backup](#sftp-remote-backup)
+- [WebDAV Remote Backup](#webdav-remote-backup)
+- [How It Works](#how-it-works)
+- [Development Guide](#development-guide)
+  - [Running Tests](#running-tests)
+  - [Code Structure](#code-structure)
+- [FAQ](#faq)
+- [Contributing](#contributing)
+- [License](#license)
+- [Author](#author)
+
+---
+
+## Introduction
+
+Sbackup is a lightweight folder backup tool that lets you add, remove, and manage backup strategies from the command line. It uses each folder's last-modified timestamp to determine whether a backup is needed, keeping your data up to date.
+
+## Features
+
+- **Incremental backup** -- only folders that have changed are backed up, saving time and storage
+- **Multi-format support** -- ZIP, tar, tar.gz, tar.bz2, tar.xz, tar.zst, 7z; both global and per-entry format overrides
+- **SFTP remote backup** -- built on paramiko with password/SSH key authentication and auto-detection of default keys
+- **WebDAV remote backup** -- uses Python's standard library urllib with zero extra dependencies; works with Jianguoyun, NextCloud, and Synology
+- **S3 cloud storage** -- powered by minio, supports all S3-compatible backends (AWS, MinIO, Alibaba Cloud OSS, etc.)
+- **Multi-destination parallel backup** -- back up to local and multiple remote targets simultaneously
+- **Restore** -- extract backups to a target directory with optional selective recovery
+- **Backup cleanup** -- automatically delete old backups by count, age, or daily retention policy
+- **Encrypted backup** -- 7z password encryption plus PBKDF2 encryption for all formats
+- **Scheduled backup** -- run backups on a fixed interval or monitor the filesystem in real time with watchdog
+- **Backup history** -- timestamps, file sizes, and SHA256 checksums recorded for every backup
+- **Audit log** -- audit events for all backup and restore operations
+- **Pre/Post hooks** -- run custom commands before or after backups
+- **Configuration profiles** -- save, switch, import, and export multiple configuration profiles
+- **Cross-archive search** -- search for matching filenames across multiple backup archives
+- **Data integrity** -- SHA256 checksum generation and verification, Reed-Solomon error correction codes
+- **Config validation** -- automatic validation of configuration parameters with tamper detection
+- **Task queue** -- manage backup tasks with add, execute, and cancel operations
+- **Compression benchmark** -- compare compression performance across formats and levels
+- **Disk space estimation** -- estimate backup size by file type and check destination space
+- **Internationalization** -- nine languages: Chinese, English, French, Spanish, Russian, German, Japanese, Portuguese, Korean
+- **Shell completion** -- auto-completion for bash, zsh, fish, and PowerShell
+- **Lightweight and efficient** -- small footprint, fast startup, low resource usage
+- **Cross-platform** -- Windows, macOS, and Linux
+
+## Getting Started
+
+### Installation
+
+#### Install with pip
+
+```bash
+pip install sbackup-cli
+```
+
+After installation, use the `sbackup` command (PyPI package name is `sbackup-cli`, CLI command is `sbackup`).
+
+#### Install from source
+
+```bash
+git clone https://github.com/xiatianxuan/sbackup.git
+cd sbackup
+uv sync
+```
+
+### Usage
+
+#### Basic syntax
+
+```bash
+uv run python main.py <command> [options]
+```
+
+#### Available commands
+
+| Command | Description |
+|---------|-------------|
+| `add` | Add a backup strategy |
+| `rm` / `remove` | Remove a backup strategy |
+| `edit` | Edit an existing backup strategy |
+| `all` | List all backup strategies |
+| `save` | Run backup |
+| `watch` | Run backup on a schedule |
+| `restore` | Restore from a backup file |
+| `info` | View backup file details |
+| `diff` | Compare source directory against backup |
+| `verify` | Verify backup file integrity |
+| `search` | Search for files inside a backup |
+| `xsearch` | Search across multiple backup archives |
+| `versions` | View backup version history |
+| `sftp` | SFTP remote backup management |
+| `webdav` | WebDAV remote backup management |
+| `remote` | Remote file management (list/rm) |
+| `task` | Backup task queue management |
+| `audit` | Audit log queries |
+| `hooks` | Manually run Pre/Post hooks |
+| `profile` | Configuration profile management |
+| `rotate` | Backup rotation cleanup |
+| `clean` | Clean old backups |
+| `diskcheck` | Disk space estimation |
+| `benchmark` | Compression format benchmark |
+| `integrity` | Backup directory integrity check |
+| `dry-run` | Preview backup file selection |
+| `export` / `import` | Export/import backup strategies |
+| `ignore` | Generate .sbackupignore file |
+| `schedule` | Export scheduled task configuration |
+| `webhook` | Configure webhook presets |
+| `config` | Configuration encryption/validation |
+| `report` | Generate backup report |
+| `completion` | Generate shell completion scripts |
+| `wizard` | Interactive configuration wizard |
+| `status` | Backup status dashboard |
+| `version` | Show version information |
+| `help` | Show help information |
+
+#### Global options
+
+| Option | Description |
+|--------|-------------|
+| `--lang zh_CN` / `en_US` / `fr_FR` / `es_ES` / `ru_RU` / `de_DE` / `ja_JP` / `pt_BR` / `ko_KR` | Set UI language (persisted in config.json) |
+| `--format zip` / `tar` / `tar.gz` / `tar.bz2` / `tar.xz` / `tar.zst` / `7z` | Set archive format (persisted in config.json) |
+| `--debug` | Enable debug logging |
+
+#### Adding a backup strategy
+
+```bash
+uv run python main.py add <source> <dest> [-i ignore_patterns]
+```
+
+Parameters:
+- **source** -- path to the folder to back up
+- **dest** -- path where backup files are stored
+- **-i, --ignore** -- comma-separated names of files or folders to skip (default: `.git,__pycache__`)
+- **--format** -- per-entry archive format (overrides the global default for this strategy only): `zip` / `tar` / `tar.gz` / `tar.bz2` / `tar.xz` / `tar.zst` / `7z`
+
+Examples:
+```bash
+# Add strategy using the global default format
+uv run python main.py add F:/my_folder F:/backup -i node_modules,.git
+
+# Specify tar.gz for this strategy (every backup of this folder uses tar.gz)
+uv run python main.py add F:/my_folder F:/backup --format tar.gz
+
+# Specify 7z for this folder only
+uv run python main.py add F:/my_folder F:/backup --format 7z
+```
+
+#### Removing a backup strategy
+
+```bash
+uv run python main.py rm <path>
+```
+
+Parameters:
+- **path** -- source folder path of the strategy to remove
+
+Example:
+```bash
+uv run python main.py rm F:/my_folder
+```
+
+#### Listing all backup strategies
+
+```bash
+uv run python main.py all
+```
+
+Displays all currently configured backup strategies.
+
+#### Running a backup
+
+```bash
+# Use default format (ZIP)
+uv run python main.py save
+
+# Use tar.gz format
+uv run python main.py --format tar.gz save
+
+# Keep only the 5 most recent backups, auto-clean old ones
+uv run python main.py save --keep 5
+
+# Use 7z format with encryption
+uv run python main.py --format 7z save --password mysecret
+
+# English UI + tar.xz format
+uv run python main.py --lang en_US --format tar.xz save
+```
+
+**save options:**
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--keep N` | `0` | Keep the N most recent backup files; 0 means no cleanup |
+| `--password PASSWORD` | `""` | Encryption password (7z format only) |
+| `--sftp` | `false` | Upload to SFTP server after backup |
+| `--webdav` | `false` | Upload to WebDAV server after backup |
+
+Backs up changed folders automatically according to the configured strategies.
+
+#### Scheduled backup
+
+```bash
+# Back up every 60 minutes
+uv run python main.py watch --interval 60
+
+# Back up every 2 hours, keep the 10 most recent files
+uv run python main.py watch --interval 120 --keep 10
+
+# Scheduled backup + 7z encryption
+uv run python main.py --format 7z watch --interval 60 --password mysecret
+```
+
+**watch options:**
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--interval MINUTES` | `60` | Backup interval in minutes |
+| `--keep N` | `0` | Keep the N most recent backup files |
+| `--password PASSWORD` | `""` | Encryption password (7z format only) |
+| `--sftp` | `false` | Upload to SFTP server after each backup |
+| `--webdav` | `false` | Upload to WebDAV server after each backup |
+
+Press `Ctrl+C` to stop scheduled backup.
+
+#### Restoring a backup
+
+```bash
+uv run python main.py restore <backup_file> <target_dir>
+```
+
+Parameters:
+- **backup_file** -- path to the backup file (supports .zip / .tar / .tar.gz / .tar.bz2 / .tar.xz / .tar.zst / .7z)
+- **target_dir** -- directory to restore into
+
+Examples:
+```bash
+uv run python main.py restore F:/backup/my_folder.tar.gz F:/restored
+uv run python main.py restore F:/backup/my_folder.7z F:/restored
+uv run python main.py restore F:/backup/my_folder.tar.zst F:/restored
+```
+
+#### SFTP remote backup
+
+```bash
+# ============ Quick start (recommended) ============
+# 1. Configure SFTP (auto-detects SSH private key, no manual setup needed)
+sbackup sftp config --host 192.168.1.100 --user admin --remote-path /backups
+
+# 2. Test connection
+sbackup sftp test
+
+# 3. Run backup and upload
+sbackup save --sftp
+
+# ============ Authentication methods ============
+
+# Method 1: Auto-detect private key (recommended)
+# Automatically tries ~/.ssh/id_ed25519 -> id_rsa -> id_ecdsa
+sbackup sftp config --host 192.168.1.100 --user admin
+
+# Method 2: Password authentication
+sbackup sftp config --host 192.168.1.100 --user admin --password secret
+
+# Method 3: Specify private key
+sbackup sftp config --host 192.168.1.100 --user admin --key-file ~/.ssh/id_rsa
+
+# Method 4: Private key + passphrase (interactive input)
+sbackup sftp config --host 192.168.1.100 --user admin --key-file ~/.ssh/id_rsa
+
+# Method 5: Private key + passphrase (command line)
+sbackup sftp config --host 192.168.1.100 --user admin --key-file ~/.ssh/id_rsa --key-passphrase mykeypass
+
+# ============ Use cases ============
+
+# One-time backup with upload
+sbackup save --sftp
+
+# Scheduled backup with auto-upload (every 60 minutes)
+sbackup watch --interval 60 --sftp
+
+# Specify format + upload
+sbackup --format tar.gz save --sftp
+
+# Encrypted backup + upload
+sbackup --format 7z save --password mysecret --sftp
+
+# Keep 5 most recent backups + upload
+sbackup save --keep 5 --sftp
+
+# ============ Advanced usage ============
+
+# Interactive configuration (step-by-step input)
+sbackup sftp config
+
+# Non-interactive configuration (all parameters on command line)
+sbackup sftp config --host 192.168.1.100 --port 22 --user admin --password secret --remote-path /backups
+
+# Test connection with verbose logging
+sbackup --debug sftp test
+```
+
+**sftp subcommands:**
+
+| Subcommand | Description | Example |
+|------------|-------------|---------|
+| `sftp config` | Configure SFTP connection (host/port/user/password/key_file/key_passphrase/remote_path) | `sbackup sftp config --host 192.168.1.100 --user admin` |
+| `sftp test` | Test whether the SFTP connection works | `sbackup sftp test` |
+
+**Authentication methods:**
+
+| Method | Parameters | Description | Example |
+|--------|-----------|-------------|---------|
+| **Auto-detect** | (none) | Automatically tries `~/.ssh/id_ed25519` -> `id_rsa` -> `id_ecdsa` (recommended) | `sbackup sftp config --host ... --user ...` |
+| Password | `--password` | Log in with a password | `sbackup sftp config --host ... --user ... --password secret` |
+| Private key | `--key-file` | Log in with a specific SSH private key | `sbackup sftp config --host ... --user ... --key-file ~/.ssh/id_rsa` |
+| Private key + passphrase | `--key-file` + `--key-passphrase` | When the private key requires a passphrase | `sbackup sftp config --host ... --user ... --key-file ~/.ssh/id_rsa --key-passphrase mypass` |
+
+Supported key formats: RSA, Ed25519, ECDSA.
+
+**Cross-platform path support:**
+
+| Platform | Key path example | Description |
+|----------|-----------------|-------------|
+| Linux/macOS | `~/.ssh/id_rsa` | Expands to `/home/user/.ssh/id_rsa` |
+| Windows | `~/.ssh/id_rsa` | Expands to `C:\Users\username\.ssh\id_rsa` |
+| All platforms | Absolute path | Use the full path directly |
+
+SFTP configuration is stored in the `sftp` field of `config.json` and can be set via command line or interactive input.
+
+#### Viewing version information
+
+```bash
+sbackup version
+```
+
+## Configuration
+
+Sbackup supports customization through a `config.json` file placed in the project root directory.
+
+### Configuration options
+
+```json
+{
+  "compression_format": "ZIP",
+  "compression": {
+    "algorithm": "ZIP_DEFLATED",
+    "level": 6
+  },
+  "skip_patterns": [".git", "__pycache__"],
+  "data_file": "sbackup.json",
+  "lang": "zh_CN",
+  "password": "",
+  "sftp": {
+    "host": "",
+    "port": 22,
+    "user": "",
+    "password": "",
+    "key_file": "",
+    "key_passphrase": "",
+    "remote_path": "/",
+    "enabled": false
+  }
+}
+```
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `compression_format` | string | `"ZIP"` | Archive format: `ZIP`, `TAR`, `TAR_GZ`, `TAR_BZ2`, `TAR_XZ`, `TAR_ZST`, `7Z` |
+| `compression.algorithm` | string | `"ZIP_DEFLATED"` | ZIP compression algorithm: `ZIP_DEFLATED`, `ZIP_STORED`, `ZIP_BZIP2`, `ZIP_LZMA` |
+| `compression.level` | int | `6` | Compression level 0-9 (0 = no compression, 9 = maximum) |
+| `skip_patterns` | list | `[".git", "__pycache__"]` | File/folder patterns to skip (supports fnmatch wildcards and path matching) |
+| `data_file` | string | Platform default | Path to the backup strategy data file |
+| `lang` | string | `"zh_CN"` | UI language: `zh_CN`, `en_US`, `fr_FR`, `es_ES`, `ru_RU`, `de_DE`, `ja_JP`, `pt_BR`, `ko_KR` |
+| `password` | string | `""` | 7z encryption password |
+| `sftp.host` | string | `""` | SFTP server address |
+| `sftp.port` | int | `22` | SFTP port |
+| `sftp.user` | string | `""` | SFTP username |
+| `sftp.password` | string | `""` | SFTP password (for password authentication) |
+| `sftp.key_file` | string | `""` | SSH private key file path (for key-based authentication) |
+| `sftp.key_passphrase` | string | `""` | Private key passphrase (if required) |
+| `sftp.remote_path` | string | `"/"` | Remote destination path |
+| `sftp.enabled` | bool | `false` | Whether SFTP is enabled |
+
+### Example configuration
+
+Using tar.bz2 format for high-compression backups:
+
+```json
+{
+  "compression_format": "TAR_BZ2",
+  "compression_level": 9,
+  "skip_patterns": [".git", "__pycache__", "node_modules", "*.log"],
+  "data_file": "backup_strategies.json",
+  "lang": "en_US"
+}
+```
+
+### Archive format comparison
+
+| Format | Extension | Compression | Speed | Dependencies | Best for |
+|--------|-----------|-------------|-------|--------------|----------|
+| ZIP | .zip | Medium | Fast | stdlib | General purpose, best Windows compatibility |
+| tar | .tar | None | Very fast | stdlib | Archive only, pair with external compression |
+| tar.gz | .tar.gz | Medium | Fast | stdlib | General Linux/macOS use |
+| tar.bz2 | .tar.bz2 | High | Medium | stdlib | High-compression archives |
+| tar.xz | .tar.xz | Highest | Slow | stdlib | Long-term archiving, space-sensitive |
+| tar.zst | .tar.zst | Medium-high | Very fast | zstandard | Modern workloads, speed/size balance |
+| 7z | .7z | Very high | Slow | py7zr | Maximum compression, encryption support |
+
+#### WebDAV remote backup
+
+WebDAV is an HTTP-based file protocol supported by Jianguoyun, NextCloud, Synology, and other popular cloud drives. Uses Python's standard library `urllib` with **zero extra dependencies**.
+
+```bash
+# ============ Quick start ============
+# 1. Configure WebDAV
+sbackup webdav config --url https://dav.jianguoyun.com/dav/ --user user@example.com --password secret
+
+# 2. Test connection
+sbackup webdav test
+
+# 3. Run backup and upload
+sbackup save --webdav
+
+# ============ Use cases ============
+
+# One-time backup with upload
+sbackup save --webdav
+
+# Scheduled backup with auto-upload (every 60 minutes)
+sbackup watch --interval 60 --webdav
+
+# Specify remote subdirectory
+sbackup webdav config --url https://dav.jianguoyun.com/dav/ --user user@example.com --remote-path /backups/sbackup
+
+# Upload to SFTP and WebDAV simultaneously
+sbackup save --sftp --webdav
+
+# ============ Common WebDAV service URLs ============
+# Jianguoyun: https://dav.jianguoyun.com/dav/
+# NextCloud: https://your-server/remote.php/dav/files/username/
+# Synology: https://your-synology:5006/webdav/
+```
+
+**webdav subcommands:**
+
+| Subcommand | Description | Example |
+|------------|-------------|---------|
+| `webdav config` | Configure WebDAV connection (url/user/password/remote_path) | `sbackup webdav config --url ... --user ...` |
+| `webdav test` | Test whether the WebDAV connection works | `sbackup webdav test` |
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--url URL` | `""` | WebDAV server URL (e.g. `https://dav.jianguoyun.com/dav/`) |
+| `--user USER` | `""` | WebDAV username (usually an email address) |
+| `--password PASS` | `""` | WebDAV password (Jianguoyun requires generating an app password in settings) |
+| `--remote-path PATH` | `/` | Remote destination path |
+
+## How It Works
+
+Sbackup implements backup through the following mechanisms:
+
+1. **Strategy storage** -- backup strategies are stored in a JSON file containing folder paths, last-modified timestamps, target paths, ignore patterns, and per-entry archive formats.
+2. **Incremental backup** -- by comparing each folder's last-modified timestamp, only changed folders are backed up.
+3. **Multi-format compression** -- uses Python's built-in `zipfile` and `tarfile` modules, plus `zstandard` and `py7zr` third-party libraries, supporting seven archive formats.
+4. **Per-entry format** -- each strategy can specify its own archive format (`add --format`), which takes priority over the global `--format` setting; when not specified, the global default is used.
+5. **Backup cleanup** -- after a successful backup, the target directory is scanned, sorted by modification time, and older files exceeding the retention count are deleted.
+6. **Encrypted backup** -- the 7z format supports LZMA2 encryption via the `--password` parameter or the `password` field in `config.json`.
+7. **Scheduled backup** -- the `watch` command runs backups in a loop at the specified interval; `Ctrl+C` exits safely.
+8. **Backup history** -- each backup records a timestamp, file size, and file count, keeping the 100 most recent entries.
+9. **SFTP remote backup** -- an SFTP client built on paramiko with connection testing, automatic remote directory creation, and progress-bar file uploads.
+
+### Data file format
+
+```json
+{
+  "/path/to/source/folder": [
+    1719235200.0,
+    "/path/to/target/folder",
+    [".git", "__pycache__"],
+    ""
+  ],
+  "/path/to/another/folder": [
+    1719235200.0,
+    "/path/to/another/target",
+    [".git"],
+    "TAR_GZ"
+  ],
+  "_history": [
+    {
+      "time": "2026-05-01T12:00:00",
+      "source": "/path/to/source/folder",
+      "size_mb": 12.5,
+      "files_count": 150
+    }
+  ]
+}
+```
+
+Each backup strategy entry is a 4-element list: `[mtime, target, skip_patterns, compression_format]`
+
+| Field | Description |
+|-------|-------------|
+| `mtime` | Last-modified timestamp of the source folder (used for incremental backup decisions) |
+| `target` | Target path where backup files are stored |
+| `skip_patterns` | List of file/folder patterns to skip |
+| `compression_format` | Per-entry archive format (empty string means use the global default) |
+
+## Development Guide
+
+### Running tests
+
+```bash
+uv run coverage run -m unittest discover -s tests -t . && uv run coverage report -m
+```
+
+### Code structure
+
+```
+sbackup/
+├── main.py              # Entry point
+├── sbackup/
+│   ├── __init__.py      # Core function exports
+│   ├── __main__.py      # python -m sbackup entry point
+│   ├── cli.py           # CLI argument parsing and command dispatch (30+ commands)
+│   ├── config.py        # Configuration loading, encryption, webhook/SMTP config
+│   ├── auto_save.py     # BackupManager core engine
+│   ├── compression.py   # 7-format compression/decompression engine
+│   ├── i18n.py          # Internationalization (9 languages)
+│   ├── sftp.py          # SFTP remote backup client (paramiko)
+│   ├── webdav.py        # WebDAV remote backup client (zero dependencies)
+│   ├── cloud_storage.py # S3 cloud storage client (minio)
+│   ├── multi_dest.py    # Multi-destination parallel backup
+│   ├── handlers.py      # SFTP/WebDAV/Remote/Schedule command handlers
+│   ├── hooks.py         # Pre/Post hook execution
+│   ├── audit.py         # Audit log system
+│   ├── profile.py       # Configuration profile management
+│   ├── selective.py     # Selective restore
+│   ├── cross_search.py  # Cross-archive search
+│   ├── integrity.py     # SHA256 checksums
+│   ├── rotation.py      # Backup rotation policies
+│   ├── dryrun.py        # Dry-run preview
+│   ├── diskcheck.py     # Disk space estimation
+│   ├── task_queue.py    # Task queue system
+│   ├── schema.py        # Configuration validator
+│   ├── benchmark.py     # Compression benchmarks
+│   ├── chunked_backup.py# Block-level incremental backup
+│   ├── dedup.py         # File-level SHA256 deduplication
+│   ├── export.py        # Metadata export (CSV/JSON)
+│   ├── monitor.py       # watchdog filesystem monitor
+│   ├── lock.py          # Cross-platform process lock
+│   ├── retry.py         # Exponential backoff retry
+│   ├── ratelimiter.py   # Token bucket rate limiter
+│   ├── keychain.py      # System keychain integration
+│   ├── parity.py        # Reed-Solomon error correction
+│   ├── completion.py    # Shell auto-completion
+│   ├── wizard.py        # Interactive configuration wizard
+│   └── locales/         # Translation files for 9 languages
+└── tests/
+    └── sbackup/
+        └── test_*.py    # 30 test files covering all modules
+```
+
+### Adding new features
+
+1. Create a new module file under `sbackup/`
+2. Import the new functions in `sbackup/__init__.py`
+3. Add command-line command handling in the `run()` function
+4. Add corresponding test files under `tests/`
+
+## FAQ
+
+### Q: What if the backup strategy file is accidentally deleted?
+
+A: Backup strategies are stored in the data file. If accidentally deleted, you can re-add them by running the `add` command again.
+
+### Q: How do I modify an existing backup strategy?
+
+A: Use the `sbackup edit` command: `sbackup edit <source> --dest <new_dest> --ignore <patterns> --format <fmt>`.
+
+### Q: Is remote backup supported?
+
+A: Yes! Three remote backup methods are available:
+- **SFTP**: configure with `sbackup sftp config`, upload with `sbackup save --sftp`
+- **WebDAV**: configure with `sbackup webdav config`, upload with `sbackup save --webdav` (supports Jianguoyun, NextCloud, Synology)
+- **S3 cloud storage**: configure the `cloud` field in `config.json`, upload with `sbackup save --cloud`
+- Multiple can be combined: `sbackup save --sftp --webdav --cloud`
+
+### Q: What is the difference between tar.gz and ZIP?
+
+A: tar.gz is more common on Linux/macOS with slightly better compression; ZIP is more universal on Windows with the best compatibility. tar.bz2 and tar.xz offer higher compression but are slower. tar.zst is a modern algorithm that is extremely fast with good compression. 7z has the highest compression and supports encryption.
+
+### Q: How do I encrypt a backup?
+
+A: Use the 7z format with a password: `uv run python main.py --format 7z save --password yourpassword`. The password can also be set in the `password` field of `config.json`.
+
+### Q: How do I automatically clean old backups?
+
+A: Use the `--keep` parameter: `uv run python main.py save --keep 5` keeps only the 5 most recent backup files. This also works with scheduled backups: `uv run python main.py watch --interval 60 --keep 10`.
+
+### Q: How do I set up scheduled backups?
+
+A: Use the `watch` command: `uv run python main.py watch --interval 60` backs up every 60 minutes. Press `Ctrl+C` to stop.
+
+### Q: Is password storage secure?
+
+A: SFTP passwords and 7z encryption passwords in `config.json` are stored in **plain text**. Ensure that the `config.json` file is accessible only to trusted users (e.g. `chmod 600 config.json`). Do not commit `config.json` containing passwords to version control.
+
+## Contributing
+
+Issues and Pull Requests are welcome!
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request
+
+### Code style
+
+This project follows PEP 8 and the Google Python Style Guide. Please ensure your code:
+- Uses type annotations
+- Follows Google-style docstrings
+- Passes all unit tests
+
+## License
+
+This project is licensed under the GNU GPL v3.0 License. See the [LICENSE](LICENSE) file for details.
+
+## Author
+
+**xiatianxuan** (CodeSeed)
+
+- [Gitee](https://gitee.com/xiatianxuan)
+- [Homepage](https://xnors-codeseed.pages.dev/)
+
+## Special Thanks
+
+- [Xnors Studio](https://xnors.github.io/)
+
+## Contact
+
+For questions or suggestions, please email: xiatianxuan2025@163.com
+
+---
+
+*Last updated: June 19, 2026*