pix-cli 0.1.3__tar.gz → 0.1.4__tar.gz

{pix_cli-0.1.3 → pix_cli-0.1.4}/AGENTS.md

@@ -32,9 +32,10 @@ uv build
 - 不通过 shell 调用 `vips` 或 `rclone`。
 - `-q` 是 quality，`--quiet` 是静默。
 - 退出码 0/1/2，日志走 stderr；`mirror` / `publish` 透传 rclone 退出码。
-- `mirror` / `publish` 使用 `rclone bisync`；首次运行必须显式 `--resync`，不要自动加。它们是双向镜像，不是单向备份。
+- `mirror` / `publish` 使用 `rclone bisync`；调用前先 `rclone mkdir` 目标并用 `rclone lsjson --max-depth 1` 判空。目标为空时自动加 `--resync`，目标非空时必须显式 `--resync`。用户不需要手动运行 rclone。它们是双向镜像，不是单向备份。
 - `--max-delete` 默认 10（删除百分比，rclone bisync 语义）；`mirror` / `publish` 源为空时默认拒绝，`--allow-empty` 加 `--resync` 才放行。
-- 修改排除项后必须提示用户先 `--resync`；`--exclude` 是配置在前、命令行追加并去重。
+- `mirror` 默认只同步 `[mirror].include` 中的图片扩展名，`include = []` 关闭白名单；`publish` 固定只同步 `.avif`。两者用 rclone filters 文件（bisync `--filters-file`、判空 `--filter-from`）并加 `--ignore-case`。
+- 修改 include/exclude 后必须提示用户先 `--resync`；升级到带过滤的版本后首次运行也需要 `--resync`。`--exclude` 是配置在前、命令行追加并去重。
 - 增量状态固定在 `OUT/.pix/state.json`，每 200 个成功文件刷新并在 `finally` 落盘；`publish` 必须排除 `.pix/**`。
 - `shrink` 必须拒绝目标冲突，`--prune` 必须拒绝空源，非 dry-run 必须持有 `OUT/.pix/lock`。
 - `publish` 源必须至少有一个 `.avif`；`base_url` 必须以 `http://` 或 `https://` 开头。

{pix_cli-0.1.3 → pix_cli-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pix-cli
-Version: 0.1.3
+Version: 0.1.4
 Summary: Batch AVIF shrink and image-host sync CLI
 Project-URL: Homepage, https://github.com/uzvg/pix
 Project-URL: Repository, https://github.com/uzvg/pix
@@ -43,7 +43,7 @@ Description-Content-Type: text/markdown
 | `pix shrink` | Recursively compress images to AVIF, re-encoding only changed files |
 | `pix mirror` | Bidirectionally mirror an original photo directory to a cloud drive |
 | `pix publish` | Bidirectionally mirror AVIF output to an image host; optionally emit public URLs |
-| `pix doctor` | Check Python, libvips, rclone and configuration |
+| `pix doctor` | Report Python, libvips and rclone versions, plus the config path |
 | `pix config init` | Write a commented default configuration file |
 
 `pix` is deliberately narrow:
@@ -66,7 +66,7 @@ photos/ ── mirror (rclone bisync) ──────────────
 | `shrink` | pyvips thumbnail + AVIF encode | pix |
 | `mirror` | `rclone bisync SRC REMOTE` | pix composes arguments, rclone executes |
 | `publish` | `rclone bisync OUT REMOTE`, excluding `.pix/**` | pix + rclone |
-| `doctor` / `config init` | Dependency checks / config scaffold | pix |
+| `doctor` / `config init` | Runtime report / config scaffold | pix |
 
 **Sync is rclone.** `mirror` and `publish` only compose `rclone bisync` arguments; rclone handles authentication, transfers and conflict handling. Configure remotes with `rclone config` before using them. `pix` never reads or writes `rclone.conf`.
 
@@ -76,14 +76,23 @@ photos/ ── mirror (rclone bisync) ──────────────
 
 - Python 3.11+
 - [uv](https://docs.astral.sh/uv/)
-- rclone >= 1.66 for `mirror` / `publish`
+- rclone >= 1.66 for `mirror` / `publish` (and for `pix doctor` to report a clean environment)
 - At least one remote already configured in rclone
 
 `pyvips[binary]` bundles libvips, so no separate vips installation is required.
 
 ## Install
 
-Not yet published on PyPI; install from source:
+Install from PyPI:
+
+```bash
+uv tool install pix-cli
+pix --version
+```
+
+Upgrade with `uv tool upgrade pix-cli`; remove with `uv tool uninstall pix-cli`. Linux installs `~/.local/bin/pix`; Windows installs `%USERPROFILE%\.local\bin\pix.exe`.
+
+To work on pix itself, install the checkout in editable mode:
 
 ```bash
 git clone https://github.com/uzvg/pix.git
@@ -92,7 +101,7 @@ uv tool install --editable .
 pix --version
 ```
 
-Linux installs `~/.local/bin/pix`; Windows installs `%USERPROFILE%\.local\bin\pix.exe`. An editable install picks up source changes immediately. Reinstall with `uv tool install --force --editable .`, or remove it with `uv tool uninstall pix-cli`.
+An editable install picks up source changes immediately. Reinstall with `uv tool install --force --editable .`.
 
 ## Configure rclone
 
@@ -118,7 +127,7 @@ If the file is missing, built-in defaults are used. Generate a commented file wi
 pix config init
 ```
 
-Existing files are not overwritten; pass `--force` to replace one. Use `--config PATH` before the subcommand to point at another file.
+Existing files are not overwritten; pass `--force` to replace one. Use `--config PATH` before the subcommand to point at another file; an explicit path must exist, while a missing default path is fine.
 
 Common keys:
 
@@ -129,15 +138,18 @@ Common keys:
 | | `effort` | `5` | libvips effort, 0–9 |
 | | `min_size` | `0` | Skip sources smaller than this; accepts `500K`, `1M`, `2G` |
 | | `include` | `jpg`, `jpeg`, `png`, `webp` | Extensions to scan, without dots |
-| `[mirror]` | `exclude` | `[]` | rclone exclude globs; command-line values are appended |
+| `[mirror]` | `include` | common image extensions | Extensions to mirror, without dots; `[]` disables the whitelist |
+| | `exclude` | `[]` | rclone exclude globs; command-line values are appended |
 | | `max_delete` | `10` | Delete limit as a percentage; `-1` disables, `0` forbids |
 | `[publish]` | `base_url` | `""` | Public URL prefix; must start with `http://` or `https://` |
 | | `urls` | `false` | Emit a JSON URL manifest |
-| | `exclude` | `[]` | Same as mirror |
+| | `exclude` | `[]` | Same as mirror; `.pix/**` is always excluded first |
 | | `max_delete` | `10` | Same as mirror |
 | `[rclone]` | `binary` | `rclone` | rclone executable name or path |
 
-Precedence is **command line > pix config > built-in defaults**. `--exclude` is appended to config excludes rather than replacing them. `-q` means quality; silence is `--quiet` (no short form).
+Precedence is **command line > pix config > built-in defaults**. `--exclude` is appended to config excludes rather than replacing them. `-q` means quality; `--quiet` is errors-only; `-v` / `--verbose` adds per-file detail and rclone progress. `--no-urls` overrides `[publish].urls = true` for one run.
+
+The default `[mirror].include` is `jpg`, `jpeg`, `png`, `webp`, `gif`, `bmp`, `tif`, `tiff`, `heic`, `heif`, `avif`, `jxl`, `svg`, `ico`, `cr2`, `cr3`, `nef`, `arw`, `dng`, `orf`, `raf`, `rw2`. Set it to `[]` to mirror every file.
 
 ## Quick start
 
@@ -154,16 +166,16 @@ Precedence is **command line > pix config > built-in defaults**. `--exclude` is
    pix shrink -s ~/Pictures -d ~/Pictures-avif -w 1920 -q 85
    ```
 
-   The first run encodes everything; later runs skip unchanged files. State lives in `OUT/.pix/state.json`. Changing `width`, `quality` or `effort` triggers a full re-encode. `--dry-run` only prints the plan.
+   The first run encodes everything; later runs skip unchanged files. State lives in `OUT/.pix/state.json`. `-w` is a maximum long edge, so smaller images are not upscaled; relative directories are preserved under OUT. Change detection uses source size/mtime and output size, not content hashes. Changing `width`, `quality` or `effort` triggers a full re-encode. `--dry-run` only prints the plan. `--prune` removes only outputs recorded in state; extra files in OUT are left alone.
 
 3. Mirror originals:
 
    ```bash
    pix mirror -s ~/Pictures -d onedrive:photos --dry-run
-   pix mirror -s ~/Pictures -d onedrive:photos --resync
+   pix mirror -s ~/Pictures -d onedrive:photos
    ```
 
-   `--resync` is required on the first run. Always preview with `--dry-run` first.
+   The destination is created automatically. Only files matching `[mirror].include` are mirrored; other source files are ignored, and non-matching files already on the destination are left untouched. If no source file matches the filter, the source counts as empty and is refused unless you pass `--allow-empty --resync`. An empty destination initializes its own baseline, so no `--resync` is needed on the first run. Use `--resync` to rebuild the baseline when the destination already has matching content, or after changing `include`/`exclude`; `--dry-run` may create an empty destination but does not transfer or delete. After upgrading from a version without include filtering, the first run also needs `--resync`; preview with `--dry-run --resync` first (the preview does not write the baseline).
 
 4. Publish the AVIF output:
 
@@ -172,17 +184,18 @@ Precedence is **command line > pix config > built-in defaults**. `--exclude` is
      --base-url https://img.example.com --urls > urls.json
    ```
 
-   `publish` requires at least one `.avif` in the source and always excludes `.pix/**`. The URL manifest is printed to stdout as JSON only after a successful, non-dry-run sync.
+   `publish` requires at least one `.avif` in the source unless you pass `--allow-empty --resync`; it syncs only `.avif` files and always excludes `.pix/**`. The URL manifest is printed to stdout as JSON only after a successful, non-dry-run sync. It lists every `.avif` under OUT, not just files changed in this run, and is not filtered by `[publish].exclude` or `--exclude`; excluded files can still appear in it. If you rely on excludes to hide files, do not publish the manifest until this behavior is fixed.
 
 5. Re-run later:
 
    ```bash
    pix shrink -s ~/Pictures -d ~/Pictures-avif
    pix mirror -s ~/Pictures -d onedrive:photos
-   pix publish -s ~/Pictures-avif -d r2:images --urls
+   pix publish -s ~/Pictures-avif -d r2:images \
+     --base-url https://img.example.com --urls
    ```
 
-   Only changes are encoded and transferred.
+   Only changes are encoded and transferred. `--base-url` is not persisted between runs; set `[publish].base_url` in config to avoid repeating it.
 
 ## Command cheat sheet
 
@@ -190,9 +203,10 @@ Precedence is **command line > pix config > built-in defaults**. `--exclude` is
 |---|---|
 | Preview compression | `pix shrink -s SRC -d OUT --dry-run` |
 | Re-encode everything | `pix shrink -s SRC -d OUT --force` |
-| Remove outputs whose source is gone | `pix shrink -s SRC -d OUT --prune` |
+| Remove tracked outputs whose source is gone | `pix shrink -s SRC -d OUT --prune` |
 | Preview a sync | `pix mirror -s SRC -d REMOTE --dry-run` |
-| First run, or after changing excludes | `pix mirror -s SRC -d REMOTE --resync` |
+| First sync (new or empty destination) | `pix mirror -s SRC -d REMOTE` |
+| Rebuild the baseline (non-empty destination, or after changing include/exclude) | `pix mirror -s SRC -d REMOTE --resync` |
 | Emit a URL manifest | `pix publish -s OUT -d REMOTE --base-url https://img.example.com --urls` |
 | Diagnose the environment | `pix doctor` |
 | Generate a config file | `pix config init` |
@@ -202,19 +216,21 @@ Precedence is **command line > pix config > built-in defaults**. `--exclude` is
 | Situation | What happens | Protection |
 |---|---|---|
 | Deletions on either side | Propagated in both directions; accidental deletion is irreversible | Preview with `--dry-run`; default `--max-delete 10` (percentage) |
-| First sync | rclone has no baseline and errors | Add `--resync` explicitly |
-| Excludes changed | The old baseline may treat excluded files as deletions | Run with `--resync` again after changing excludes |
-| Empty source | `mirror` / `publish` refuse; `shrink --prune` also refuses | Use `--allow-empty` (plus `--resync` for sync) only when intentional |
+| First sync (destination empty) | `pix` creates the destination and initializes the baseline | Preview with `--dry-run`; it may create an empty destination but does not transfer or delete. No manual rclone needed |
+| Destination has matching content but no baseline | `pix` does not auto-resync; bisync fails instead of overwriting | Confirm which side is authoritative, then add `--resync` |
+| Include/exclude filters changed | When filters are active, rclone detects the changed filters file and exits 7 | Run with `--resync` after changing `include` or `exclude`; `--dry-run --resync` previews but does not write the baseline |
+| Non-image files in the source | `mirror` ignores them by default; `publish` ignores anything that is not `.avif`. If no file matches, the source counts as empty and is refused | Add extensions to `[mirror].include` if they should be mirrored; use `--allow-empty --resync` only for an intentional empty sync |
+| Empty source | `mirror` / `publish` refuse. `shrink --prune` refuses only while state still has entries; empty state is a no-op | Use `--allow-empty` (plus `--resync` for sync) only when intentional |
 | `a.jpg` and `a.jpeg` both exist | Both map to the same output | Detected before encoding; exits 2 |
 | Two concurrent shrinks | They would write the same state and outputs | `OUT/.pix/lock` blocks the second process |
-| State lost or corrupt | Warning, then a full rebuild | Only causes re-encoding; outputs stay valid |
+| State missing or corrupt | Full rebuild; corrupt state logs a warning | Only causes re-encoding; outputs stay valid |
 
 ## Output and exit codes
 
 - Logs and progress go to stderr.
-- stdout carries `doctor` reports, `--dry-run` plans and `--urls` JSON.
+- stdout carries `doctor` reports, `shrink --dry-run` plans, `config init`'s `wrote <path>`, and `--urls` JSON. `mirror` / `publish --dry-run` output comes from rclone.
 - Exit codes: `0` success, `1` runtime failure, `2` argument or configuration error.
-- `mirror` / `publish` return rclone's exit code unchanged.
+- `mirror` / `publish` return rclone's bisync exit code unchanged; destination preflight failures return 1.
 
 URL manifest example:
 
@@ -230,9 +246,9 @@ URL manifest example:
 |---|---|
 | `pyvips/libvips unavailable` | Reinstall to bring libvips: `uv tool install --force --editable /path/to/pix`; or install libvips manually (Linux: `apt install libvips42`, Windows: libvips release zip on `PATH`) |
 | rclone is older than 1.66 | Upgrade rclone |
-| bisync reports a missing baseline | Add `--resync` on the first run |
+| bisync reports a missing baseline or changed filters file | The destination has matching content, or the include/exclude rules changed (including the first run after upgrading). Confirm local should win, then add `--resync`; an empty destination initializes automatically. `--dry-run --resync` previews but does not write the baseline. |
 | `OUT/.pix/lock` already exists | Check for another `shrink`, then remove a stale lock |
-| Configuration fails to parse | Run `pix doctor` to locate the file; fix the TOML or remove the file to fall back to defaults |
+| Configuration fails to parse | The error names the file and location; fix the TOML or remove the file to fall back to defaults. `pix doctor` cannot run until the config parses |
 | `publish` says the source has no `.avif` | Run `pix shrink` first |
 | URL-related error | `base_url` must start with `http://` or `https://`, and `--urls` requires it |
 

{pix_cli-0.1.3 → pix_cli-0.1.4}/README.md

@@ -15,7 +15,7 @@
 | `pix shrink` | Recursively compress images to AVIF, re-encoding only changed files |
 | `pix mirror` | Bidirectionally mirror an original photo directory to a cloud drive |
 | `pix publish` | Bidirectionally mirror AVIF output to an image host; optionally emit public URLs |
-| `pix doctor` | Check Python, libvips, rclone and configuration |
+| `pix doctor` | Report Python, libvips and rclone versions, plus the config path |
 | `pix config init` | Write a commented default configuration file |
 
 `pix` is deliberately narrow:
@@ -38,7 +38,7 @@ photos/ ── mirror (rclone bisync) ──────────────
 | `shrink` | pyvips thumbnail + AVIF encode | pix |
 | `mirror` | `rclone bisync SRC REMOTE` | pix composes arguments, rclone executes |
 | `publish` | `rclone bisync OUT REMOTE`, excluding `.pix/**` | pix + rclone |
-| `doctor` / `config init` | Dependency checks / config scaffold | pix |
+| `doctor` / `config init` | Runtime report / config scaffold | pix |
 
 **Sync is rclone.** `mirror` and `publish` only compose `rclone bisync` arguments; rclone handles authentication, transfers and conflict handling. Configure remotes with `rclone config` before using them. `pix` never reads or writes `rclone.conf`.
 
@@ -48,14 +48,23 @@ photos/ ── mirror (rclone bisync) ──────────────
 
 - Python 3.11+
 - [uv](https://docs.astral.sh/uv/)
-- rclone >= 1.66 for `mirror` / `publish`
+- rclone >= 1.66 for `mirror` / `publish` (and for `pix doctor` to report a clean environment)
 - At least one remote already configured in rclone
 
 `pyvips[binary]` bundles libvips, so no separate vips installation is required.
 
 ## Install
 
-Not yet published on PyPI; install from source:
+Install from PyPI:
+
+```bash
+uv tool install pix-cli
+pix --version
+```
+
+Upgrade with `uv tool upgrade pix-cli`; remove with `uv tool uninstall pix-cli`. Linux installs `~/.local/bin/pix`; Windows installs `%USERPROFILE%\.local\bin\pix.exe`.
+
+To work on pix itself, install the checkout in editable mode:
 
 ```bash
 git clone https://github.com/uzvg/pix.git
@@ -64,7 +73,7 @@ uv tool install --editable .
 pix --version
 ```
 
-Linux installs `~/.local/bin/pix`; Windows installs `%USERPROFILE%\.local\bin\pix.exe`. An editable install picks up source changes immediately. Reinstall with `uv tool install --force --editable .`, or remove it with `uv tool uninstall pix-cli`.
+An editable install picks up source changes immediately. Reinstall with `uv tool install --force --editable .`.
 
 ## Configure rclone
 
@@ -90,7 +99,7 @@ If the file is missing, built-in defaults are used. Generate a commented file wi
 pix config init
 ```
 
-Existing files are not overwritten; pass `--force` to replace one. Use `--config PATH` before the subcommand to point at another file.
+Existing files are not overwritten; pass `--force` to replace one. Use `--config PATH` before the subcommand to point at another file; an explicit path must exist, while a missing default path is fine.
 
 Common keys:
 
@@ -101,15 +110,18 @@ Common keys:
 | | `effort` | `5` | libvips effort, 0–9 |
 | | `min_size` | `0` | Skip sources smaller than this; accepts `500K`, `1M`, `2G` |
 | | `include` | `jpg`, `jpeg`, `png`, `webp` | Extensions to scan, without dots |
-| `[mirror]` | `exclude` | `[]` | rclone exclude globs; command-line values are appended |
+| `[mirror]` | `include` | common image extensions | Extensions to mirror, without dots; `[]` disables the whitelist |
+| | `exclude` | `[]` | rclone exclude globs; command-line values are appended |
 | | `max_delete` | `10` | Delete limit as a percentage; `-1` disables, `0` forbids |
 | `[publish]` | `base_url` | `""` | Public URL prefix; must start with `http://` or `https://` |
 | | `urls` | `false` | Emit a JSON URL manifest |
-| | `exclude` | `[]` | Same as mirror |
+| | `exclude` | `[]` | Same as mirror; `.pix/**` is always excluded first |
 | | `max_delete` | `10` | Same as mirror |
 | `[rclone]` | `binary` | `rclone` | rclone executable name or path |
 
-Precedence is **command line > pix config > built-in defaults**. `--exclude` is appended to config excludes rather than replacing them. `-q` means quality; silence is `--quiet` (no short form).
+Precedence is **command line > pix config > built-in defaults**. `--exclude` is appended to config excludes rather than replacing them. `-q` means quality; `--quiet` is errors-only; `-v` / `--verbose` adds per-file detail and rclone progress. `--no-urls` overrides `[publish].urls = true` for one run.
+
+The default `[mirror].include` is `jpg`, `jpeg`, `png`, `webp`, `gif`, `bmp`, `tif`, `tiff`, `heic`, `heif`, `avif`, `jxl`, `svg`, `ico`, `cr2`, `cr3`, `nef`, `arw`, `dng`, `orf`, `raf`, `rw2`. Set it to `[]` to mirror every file.
 
 ## Quick start
 
@@ -126,16 +138,16 @@ Precedence is **command line > pix config > built-in defaults**. `--exclude` is
    pix shrink -s ~/Pictures -d ~/Pictures-avif -w 1920 -q 85
    ```
 
-   The first run encodes everything; later runs skip unchanged files. State lives in `OUT/.pix/state.json`. Changing `width`, `quality` or `effort` triggers a full re-encode. `--dry-run` only prints the plan.
+   The first run encodes everything; later runs skip unchanged files. State lives in `OUT/.pix/state.json`. `-w` is a maximum long edge, so smaller images are not upscaled; relative directories are preserved under OUT. Change detection uses source size/mtime and output size, not content hashes. Changing `width`, `quality` or `effort` triggers a full re-encode. `--dry-run` only prints the plan. `--prune` removes only outputs recorded in state; extra files in OUT are left alone.
 
 3. Mirror originals:
 
    ```bash
    pix mirror -s ~/Pictures -d onedrive:photos --dry-run
-   pix mirror -s ~/Pictures -d onedrive:photos --resync
+   pix mirror -s ~/Pictures -d onedrive:photos
    ```
 
-   `--resync` is required on the first run. Always preview with `--dry-run` first.
+   The destination is created automatically. Only files matching `[mirror].include` are mirrored; other source files are ignored, and non-matching files already on the destination are left untouched. If no source file matches the filter, the source counts as empty and is refused unless you pass `--allow-empty --resync`. An empty destination initializes its own baseline, so no `--resync` is needed on the first run. Use `--resync` to rebuild the baseline when the destination already has matching content, or after changing `include`/`exclude`; `--dry-run` may create an empty destination but does not transfer or delete. After upgrading from a version without include filtering, the first run also needs `--resync`; preview with `--dry-run --resync` first (the preview does not write the baseline).
 
 4. Publish the AVIF output:
 
@@ -144,17 +156,18 @@ Precedence is **command line > pix config > built-in defaults**. `--exclude` is
      --base-url https://img.example.com --urls > urls.json
    ```
 
-   `publish` requires at least one `.avif` in the source and always excludes `.pix/**`. The URL manifest is printed to stdout as JSON only after a successful, non-dry-run sync.
+   `publish` requires at least one `.avif` in the source unless you pass `--allow-empty --resync`; it syncs only `.avif` files and always excludes `.pix/**`. The URL manifest is printed to stdout as JSON only after a successful, non-dry-run sync. It lists every `.avif` under OUT, not just files changed in this run, and is not filtered by `[publish].exclude` or `--exclude`; excluded files can still appear in it. If you rely on excludes to hide files, do not publish the manifest until this behavior is fixed.
 
 5. Re-run later:
 
    ```bash
    pix shrink -s ~/Pictures -d ~/Pictures-avif
    pix mirror -s ~/Pictures -d onedrive:photos
-   pix publish -s ~/Pictures-avif -d r2:images --urls
+   pix publish -s ~/Pictures-avif -d r2:images \
+     --base-url https://img.example.com --urls
    ```
 
-   Only changes are encoded and transferred.
+   Only changes are encoded and transferred. `--base-url` is not persisted between runs; set `[publish].base_url` in config to avoid repeating it.
 
 ## Command cheat sheet
 
@@ -162,9 +175,10 @@ Precedence is **command line > pix config > built-in defaults**. `--exclude` is
 |---|---|
 | Preview compression | `pix shrink -s SRC -d OUT --dry-run` |
 | Re-encode everything | `pix shrink -s SRC -d OUT --force` |
-| Remove outputs whose source is gone | `pix shrink -s SRC -d OUT --prune` |
+| Remove tracked outputs whose source is gone | `pix shrink -s SRC -d OUT --prune` |
 | Preview a sync | `pix mirror -s SRC -d REMOTE --dry-run` |
-| First run, or after changing excludes | `pix mirror -s SRC -d REMOTE --resync` |
+| First sync (new or empty destination) | `pix mirror -s SRC -d REMOTE` |
+| Rebuild the baseline (non-empty destination, or after changing include/exclude) | `pix mirror -s SRC -d REMOTE --resync` |
 | Emit a URL manifest | `pix publish -s OUT -d REMOTE --base-url https://img.example.com --urls` |
 | Diagnose the environment | `pix doctor` |
 | Generate a config file | `pix config init` |
@@ -174,19 +188,21 @@ Precedence is **command line > pix config > built-in defaults**. `--exclude` is
 | Situation | What happens | Protection |
 |---|---|---|
 | Deletions on either side | Propagated in both directions; accidental deletion is irreversible | Preview with `--dry-run`; default `--max-delete 10` (percentage) |
-| First sync | rclone has no baseline and errors | Add `--resync` explicitly |
-| Excludes changed | The old baseline may treat excluded files as deletions | Run with `--resync` again after changing excludes |
-| Empty source | `mirror` / `publish` refuse; `shrink --prune` also refuses | Use `--allow-empty` (plus `--resync` for sync) only when intentional |
+| First sync (destination empty) | `pix` creates the destination and initializes the baseline | Preview with `--dry-run`; it may create an empty destination but does not transfer or delete. No manual rclone needed |
+| Destination has matching content but no baseline | `pix` does not auto-resync; bisync fails instead of overwriting | Confirm which side is authoritative, then add `--resync` |
+| Include/exclude filters changed | When filters are active, rclone detects the changed filters file and exits 7 | Run with `--resync` after changing `include` or `exclude`; `--dry-run --resync` previews but does not write the baseline |
+| Non-image files in the source | `mirror` ignores them by default; `publish` ignores anything that is not `.avif`. If no file matches, the source counts as empty and is refused | Add extensions to `[mirror].include` if they should be mirrored; use `--allow-empty --resync` only for an intentional empty sync |
+| Empty source | `mirror` / `publish` refuse. `shrink --prune` refuses only while state still has entries; empty state is a no-op | Use `--allow-empty` (plus `--resync` for sync) only when intentional |
 | `a.jpg` and `a.jpeg` both exist | Both map to the same output | Detected before encoding; exits 2 |
 | Two concurrent shrinks | They would write the same state and outputs | `OUT/.pix/lock` blocks the second process |
-| State lost or corrupt | Warning, then a full rebuild | Only causes re-encoding; outputs stay valid |
+| State missing or corrupt | Full rebuild; corrupt state logs a warning | Only causes re-encoding; outputs stay valid |
 
 ## Output and exit codes
 
 - Logs and progress go to stderr.
-- stdout carries `doctor` reports, `--dry-run` plans and `--urls` JSON.
+- stdout carries `doctor` reports, `shrink --dry-run` plans, `config init`'s `wrote <path>`, and `--urls` JSON. `mirror` / `publish --dry-run` output comes from rclone.
 - Exit codes: `0` success, `1` runtime failure, `2` argument or configuration error.
-- `mirror` / `publish` return rclone's exit code unchanged.
+- `mirror` / `publish` return rclone's bisync exit code unchanged; destination preflight failures return 1.
 
 URL manifest example:
 
@@ -202,9 +218,9 @@ URL manifest example:
 |---|---|
 | `pyvips/libvips unavailable` | Reinstall to bring libvips: `uv tool install --force --editable /path/to/pix`; or install libvips manually (Linux: `apt install libvips42`, Windows: libvips release zip on `PATH`) |
 | rclone is older than 1.66 | Upgrade rclone |
-| bisync reports a missing baseline | Add `--resync` on the first run |
+| bisync reports a missing baseline or changed filters file | The destination has matching content, or the include/exclude rules changed (including the first run after upgrading). Confirm local should win, then add `--resync`; an empty destination initializes automatically. `--dry-run --resync` previews but does not write the baseline. |
 | `OUT/.pix/lock` already exists | Check for another `shrink`, then remove a stale lock |
-| Configuration fails to parse | Run `pix doctor` to locate the file; fix the TOML or remove the file to fall back to defaults |
+| Configuration fails to parse | The error names the file and location; fix the TOML or remove the file to fall back to defaults. `pix doctor` cannot run until the config parses |
 | `publish` says the source has no `.avif` | Run `pix shrink` first |
 | URL-related error | `base_url` must start with `http://` or `https://`, and `--urls` requires it |
 

{pix_cli-0.1.3 → pix_cli-0.1.4}/README.zh-CN.md

@@ -15,7 +15,7 @@
 | `pix shrink` | 递归压缩图片为 AVIF，只重新编码变化的文件 |
 | `pix mirror` | 把原图目录与云盘做双向镜像 |
 | `pix publish` | 把 AVIF 输出目录与图床做双向镜像，可选输出公开 URL |
-| `pix doctor` | 检查 Python、libvips、rclone 与配置 |
+| `pix doctor` | 报告 Python、libvips、rclone 版本与配置文件路径 |
 | `pix config init` | 生成带注释的默认配置文件 |
 
 `pix` 刻意保持边界清晰：
@@ -38,7 +38,7 @@ photos/ ── mirror (rclone bisync) ──────────────
 | `shrink` | pyvips 缩放并编码 AVIF | pix |
 | `mirror` | `rclone bisync SRC REMOTE` | pix 拼参数，rclone 执行 |
 | `publish` | `rclone bisync OUT REMOTE`，排除 `.pix/**` | pix + rclone |
-| `doctor` / `config init` | 依赖检查 / 配置脚手架 | pix |
+| `doctor` / `config init` | 运行时报告 / 配置脚手架 | pix |
 
 **同步由 rclone 执行。** `mirror` / `publish` 只负责拼装 `rclone bisync` 参数；认证、传输和冲突处理都由 rclone 完成。使用前请先用 `rclone config` 配好 remote。`pix` 不读取也不写入 `rclone.conf`。
 
@@ -48,14 +48,23 @@ photos/ ── mirror (rclone bisync) ──────────────
 
 - Python 3.11+
 - [uv](https://docs.astral.sh/uv/)
-- `mirror` / `publish` 需要 rclone >= 1.66
+- `mirror` / `publish` 需要 rclone >= 1.66；`pix doctor` 也要有 rclone 才会报告环境正常
 - 已在 rclone 中配置好至少一个 remote
 
 `pyvips[binary]` 自带 libvips，不需要单独安装 vips。
 
 ## 安装
 
-尚未发布到 PyPI，从源码安装：
+从 PyPI 安装：
+
+```bash
+uv tool install pix-cli
+pix --version
+```
+
+升级用 `uv tool upgrade pix-cli`，卸载用 `uv tool uninstall pix-cli`。Linux 安装到 `~/.local/bin/pix`，Windows 为 `%USERPROFILE%\.local\bin\pix.exe`。
+
+如果要开发 pix 本身，用 editable 模式安装源码：
 
 ```bash
 git clone https://github.com/uzvg/pix.git
@@ -64,7 +73,7 @@ uv tool install --editable .
 pix --version
 ```
 
-Linux 安装到 `~/.local/bin/pix`，Windows 为 `%USERPROFILE%\.local\bin\pix.exe`。editable 安装修改源码后立即生效。重装用 `uv tool install --force --editable .`，卸载用 `uv tool uninstall pix-cli`。
+editable 安装修改源码后立即生效。重装用 `uv tool install --force --editable .`。
 
 ## 配置 rclone
 
@@ -90,7 +99,7 @@ rclone 把凭据保存在 `~/.config/rclone/rclone.conf`（Windows：`%APPDATA%\
 pix config init
 ```
 
-已有文件不会被覆盖；需要替换时加 `--force`。用 `--config PATH`（写在子命令之前）指向其他文件。
+已有文件不会被覆盖；需要替换时加 `--force`。用 `--config PATH`（写在子命令之前）指向其他文件；显式路径必须存在，默认路径缺失则会使用内置默认值。
 
 常用配置项：
 
@@ -101,15 +110,18 @@ pix config init
 | | `effort` | `5` | libvips effort，0–9 |
 | | `min_size` | `0` | 小于该值的源文件跳过；支持 `500K`、`1M`、`2G` |
 | | `include` | `jpg`、`jpeg`、`png`、`webp` | 扫描扩展名，不带点 |
-| `[mirror]` | `exclude` | `[]` | rclone 排除 glob；命令行项会追加 |
+| `[mirror]` | `include` | 常见图片扩展名 | 需要镜像的扩展名，不带点；`[]` 关闭白名单 |
+| | `exclude` | `[]` | rclone 排除 glob；命令行项会追加 |
 | | `max_delete` | `10` | 删除百分比上限；`-1` 不限制，`0` 禁止删除 |
 | `[publish]` | `base_url` | `""` | 公开 URL 前缀，必须以 `http://` 或 `https://` 开头 |
 | | `urls` | `false` | 是否输出 JSON URL 清单 |
-| | `exclude` | `[]` | 同 `mirror` |
+| | `exclude` | `[]` | 同 `mirror`；`.pix/**` 总是先被排除 |
 | | `max_delete` | `10` | 同 `mirror` |
 | `[rclone]` | `binary` | `rclone` | rclone 可执行文件名或路径 |
 
-优先级为**命令行 > pix 配置 > 内置默认**。`--exclude` 是追加而非覆盖配置项。`-q` 表示 quality，静默模式用 `--quiet`（无短选项）。
+优先级为**命令行 > pix 配置 > 内置默认**。`--exclude` 是追加而非覆盖配置项。`-q` 表示 quality；`--quiet` 只输出错误；`-v` / `--verbose` 输出每文件详情和 rclone 进度。`--no-urls` 可单次覆盖 `[publish].urls = true`。
+
+`[mirror].include` 默认为 `jpg`、`jpeg`、`png`、`webp`、`gif`、`bmp`、`tif`、`tiff`、`heic`、`heif`、`avif`、`jxl`、`svg`、`ico`、`cr2`、`cr3`、`nef`、`arw`、`dng`、`orf`、`raf`、`rw2`。设为 `[]` 可镜像所有文件。
 
 ## 快速上手
 
@@ -126,16 +138,16 @@ pix config init
    pix shrink -s ~/Pictures -d ~/Pictures-avif -w 1920 -q 85
    ```
 
-   首次全量编码，之后跳过未变化的文件。状态保存在 `OUT/.pix/state.json`。修改 `width`、`quality` 或 `effort` 会触发全量重编码。`--dry-run` 只打印计划。
+   首次全量编码，之后跳过未变化的文件。状态保存在 `OUT/.pix/state.json`。`-w` 是长边上限，小图不会被放大；输出会保留相对目录结构。变更检测基于源文件 size/mtime 和输出 size，不做内容哈希。修改 `width`、`quality` 或 `effort` 会触发全量重编码。`--dry-run` 只打印计划。`--prune` 只删除 state 中记录的输出，OUT 里的额外文件不会被清理。
 
 3. 镜像原图：
 
    ```bash
    pix mirror -s ~/Pictures -d onedrive:photos --dry-run
-   pix mirror -s ~/Pictures -d onedrive:photos --resync
+   pix mirror -s ~/Pictures -d onedrive:photos
    ```
 
-   首次运行必须显式加 `--resync`。建议先跑 `--dry-run` 预览。
+   目标目录会自动创建。只有匹配 `[mirror].include` 的文件会被镜像；源目录里的其他文件会被忽略，目标上不匹配的文件也不会被删除。如果没有任何源文件匹配过滤规则，源会被视为空并拒绝同步，除非显式传入 `--allow-empty --resync`。目标为空时会自动初始化基线，首次运行不需要 `--resync`；目标已有匹配内容需要重建基线，或修改 `include` / `exclude` 后，才需要显式加 `--resync`。`--dry-run` 可能创建一个空目标目录，但不传输、不删除文件。从没有 include 过滤的旧版本升级后，首次运行也需要 `--resync`；建议先跑 `--dry-run --resync` 预览（预览不会写入基线）。
 
 4. 发布 AVIF 输出：
 
@@ -144,17 +156,18 @@ pix config init
      --base-url https://img.example.com --urls > urls.json
    ```
 
-   `publish` 要求源目录至少有一个 `.avif`，并固定排除 `.pix/**`。URL 清单只在同步成功且不是 `--dry-run` 时输出到 stdout。
+   `publish` 要求源目录至少有一个 `.avif`，除非显式传入 `--allow-empty --resync`；只同步 `.avif` 文件，并固定排除 `.pix/**`。URL 清单只在同步成功且不是 `--dry-run` 时输出到 stdout。清单列出 OUT 下所有 `.avif`，不只是本次变化的文件，也不按 `[publish].exclude` 或 `--exclude` 过滤；被排除的文件仍可能出现在清单里。如果依赖 exclude 隐藏文件，目前不要发布清单，直到该行为修复。
 
 5. 之后重复运行：
 
    ```bash
    pix shrink -s ~/Pictures -d ~/Pictures-avif
    pix mirror -s ~/Pictures -d onedrive:photos
-   pix publish -s ~/Pictures-avif -d r2:images --urls
+   pix publish -s ~/Pictures-avif -d r2:images \
+     --base-url https://img.example.com --urls
    ```
 
-   只处理变化的部分。
+   只处理变化的部分。`--base-url` 不会在两次运行之间保留；不想重复传就写进配置的 `[publish].base_url`。
 
 ## 常用命令
 
@@ -162,9 +175,10 @@ pix config init
 |---|---|
 | 预览压缩 | `pix shrink -s SRC -d OUT --dry-run` |
 | 强制全部重压 | `pix shrink -s SRC -d OUT --force` |
-| 删除源已消失的输出 | `pix shrink -s SRC -d OUT --prune` |
+| 删除 state 中记录、且源已消失的输出 | `pix shrink -s SRC -d OUT --prune` |
 | 预览同步 | `pix mirror -s SRC -d REMOTE --dry-run` |
-| 首次运行或修改排除项后 | `pix mirror -s SRC -d REMOTE --resync` |
+| 首次同步（目标不存在或为空） | `pix mirror -s SRC -d REMOTE` |
+| 重建基线（目标非空，或修改 include/exclude 后） | `pix mirror -s SRC -d REMOTE --resync` |
 | 输出 URL 清单 | `pix publish -s OUT -d REMOTE --base-url https://img.example.com --urls` |
 | 诊断环境 | `pix doctor` |
 | 生成配置文件 | `pix config init` |
@@ -174,19 +188,21 @@ pix config init
 | 情况 | 会发生什么 | 如何防护 |
 |---|---|---|
 | 任意一侧删除文件 | 删除双向传播，误删不可逆 | 先 `--dry-run`；默认 `--max-delete 10`（百分比） |
-| 首次同步 | rclone 没有基线，直接报错 | 显式加 `--resync` |
-| 修改排除项 | 旧基线可能把被排除的文件当成删除传播 | 修改后必须重新 `--resync` |
-| 源目录为空 | `mirror` / `publish` 默认拒绝；`shrink --prune` 同样拒绝 | 仅在确认要清空时用 `--allow-empty`（同步还需 `--resync`） |
+| 首次同步（目标为空） | `pix` 自动创建目标并初始化基线 | 先 `--dry-run` 预览；它可能创建空目标目录，但不传输、不删除。不需要手动运行 rclone |
+| 目标已有匹配内容但没有基线 | `pix` 不自动 resync，bisync 失败而不是覆盖 | 确认以哪边为准后显式加 `--resync` |
+| 修改 include/exclude | 启用过滤时，rclone 会检测到 filters 文件变化并以 7 退出 | 修改后必须重新 `--resync`；`--dry-run --resync` 只预览，不写基线 |
+| 源目录含非图片文件 | `mirror` 默认忽略；`publish` 只同步 `.avif`。如果没有任何文件匹配，源会被视为空并拒绝 | 需要镜像时把扩展名加入 `[mirror].include`；只有确认要空同步时才用 `--allow-empty --resync` |
+| 源目录为空 | `mirror` / `publish` 默认拒绝；`shrink --prune` 仅在 state 仍有记录时拒绝，state 为空时是 no-op | 仅在确认要清空时用 `--allow-empty`（同步还需 `--resync`） |
 | `a.jpg` 与 `a.jpeg` 同时存在 | 映射到同一输出 | 编码前检测并以 2 退出 |
 | 同时运行两个 shrink | 会写同一份状态和输出 | `OUT/.pix/lock` 阻止第二个进程 |
-| 状态文件丢失或损坏 | 告警后全量重建 | 只会重新编码，不会产生错误结果 |
+| 状态文件缺失或损坏 | 全量重建；损坏时会告警 | 只会重新编码，不会产生错误结果 |
 
 ## 输出与退出码
 
 - 日志和进度输出到 stderr。
-- stdout 用于 `doctor` 报告、`--dry-run` 计划和 `--urls` JSON。
+- stdout 用于 `doctor` 报告、`shrink --dry-run` 计划、`config init` 的 `wrote <path>`，以及 `--urls` JSON；`mirror` / `publish --dry-run` 的输出由 rclone 产生。
 - 退出码：`0` 成功，`1` 运行失败，`2` 参数或配置错误。
-- `mirror` / `publish` 原样返回 rclone 的退出码。
+- `mirror` / `publish` 原样返回 rclone bisync 的退出码；目标预检失败返回 1。
 
 URL 清单示例：
 
@@ -202,9 +218,9 @@ URL 清单示例：
 |---|---|
 | 提示 `pyvips/libvips unavailable` | 重装以带入 libvips：`uv tool install --force --editable /path/to/pix`；或手动安装 libvips（Linux：`apt install libvips42`；Windows：下载 libvips release 压缩包并把 `bin` 加入 PATH） |
 | rclone 版本低于 1.66 | 升级 rclone |
-| bisync 报缺少基线 | 首次运行加 `--resync` |
+| bisync 报缺少基线或 filters 文件变化 | 目标已有匹配内容，或 include/exclude 规则变化（含升级后首次运行）。确认本地为准后加 `--resync`；目标是空的会自动初始化。`--dry-run --resync` 只预览，不写基线 |
 | `OUT/.pix/lock` 已存在 | 确认没有其他 `shrink` 在运行，再删除陈旧锁 |
-| 配置解析失败 | 运行 `pix doctor` 定位文件；修复 TOML，或删除配置改用默认值 |
+| 配置解析失败 | 错误信息会指出文件和位置；修复 TOML，或删除配置改用默认值。配置解析失败时 `pix doctor` 也会在加载配置阶段退出 2 |
 | `publish` 提示源目录没有 `.avif` | 先运行 `pix shrink` |
 | URL 相关报错 | `base_url` 必须以 `http://` 或 `https://` 开头，且 `--urls` 依赖它 |