Upgrading ========== .. Page contents are rendered by furo's right-hand sidebar; an explicit .. `.. contents::` directive collides with it (furo TOC JS error), so it is omitted. Three things can be upgraded, and they upgrade differently: **protonfs itself** (pip), the **proton-drive CLI binary** it drives (``protonfs upgrade``), and a repo's **on-disk state** under ``.protonfs/`` (repo-state migrations, also run by ``protonfs upgrade``). Upgrading protonfs itself -------------------------- protonfs is a normal PyPI package:: pip install --upgrade protonfs Release history and per-version upgrade notes live in the repository's `CHANGELOG.md `_. Versioning follows the policy in :doc:`stability`: within ``1.x``, everything documented on that page keeps working; a breaking change to any of it requires a major-version bump. From 1.x to 2.0 ~~~~~~~~~~~~~~~ 2.0 renames the sync-state vocabulary so no state claims something about Drive that was not checked (see :doc:`stability`, *Sync states*). Nothing on disk changes and no migration runs; only output and filters do: - ``synced`` is now ``locally-indexed`` -- in ``status`` lines, ``status --format json`` keys and ``ls`` output. ``ls --state synced`` still works, with a warning, until the next major release; a script parsing the output needs the new name. - A file this machine held that is now missing locally is ``local-deleted``, not ``remote-only``, when ``status``/``ls`` run without ``--remote``. ``remote-only`` is now only reported from a Drive listing. A bare ``pull`` restores these files exactly as before; ``ls --state remote-only`` without ``--remote`` now matches nothing and says so. - ``status --remote`` is new: it walks Drive and classifies against it. - ``status --format json`` gains a ``"remote": true|false`` field. - Exit codes are unchanged: every state keeps its clean/drift/conflict class. Upgrading proton-drive ----------------------- ``protonfs upgrade`` brings the installed ``proton-drive`` binary to the **highest version this protonfs release supports** -- and deliberately never further:: protonfs upgrade --check # preview: installed / highest supported / upstream stable protonfs upgrade # do it ``--check`` changes nothing and exits ``0`` when fully current, ``1`` when an upgrade or migration is available -- script-friendly for provisioning. Why the cap? Each protonfs release ships pinned SHA-512 checksums for the proton-drive builds it was actually tested against (the support matrix in :doc:`stability`). A newer upstream release is unverified by definition: protonfs has no pin for it and no behavioral testing against it, so ``upgrade`` reports it -- ``upstream X exists but this protonfs supports at most Z; upgrade protonfs to get X`` -- and installs nothing. Upgrading protonfs itself (above) is the path to a newer proton-drive: the new release re-pins and re-tests, then its own ``upgrade`` moves the binary forward. Supported proton-drive versions ------------------------------- This protonfs release ships verified SHA-512 pins and behavioural compatibility for the proton-drive versions below. ``protonfs upgrade`` installs the highest supported version; the older ones stay installable for downgrades via :envvar:`PROTONFS_DRIVE_VERSION`. .. list-table:: :header-rows: 1 :widths: 20 32 48 * - proton-drive - Status - Notes * - ``0.8.0`` - highest supported (default) - Required for the ``pass`` credentials store (:envvar:`PROTONFS_CREDENTIALS_STORE`); older binaries ignore ``PROTON_DRIVE_CREDENTIALS_STORE``. * - ``0.7.0`` - supported (downgrade only) - No protonfs-visible behavioural change from 0.6.0. * - ``0.6.0`` - supported (downgrade only) - Required for the ``pass`` credentials store (:envvar:`PROTONFS_CREDENTIALS_STORE`); older binaries ignore ``PROTON_DRIVE_CREDENTIALS_STORE``. * - ``0.5.0`` - supported (downgrade only) - Trash restore resolves ``/trash`` entries by decrypted name (first match wins). * - ``0.4.6`` - supported (downgrade only) - Accepts original-path ``filesystem restore``. A proton-drive version outside this list is refused: an unsupported (or unpinned) version needs a protonfs release that pins and tests it. ``protonfs doctor`` reports the installed version against this matrix, and additionally **fails** when the active credentials store is ``pass`` but the installed proton-drive predates ``0.6.0`` -- directing you to upgrade proton-drive, switch to the keychain store, or use a protonfs release without the pass fallback. The binary swap is verify-first and atomic: the download is staged to a temporary file, its SHA-512 checked against the pin, and only then swapped into place. A failed download or checksum mismatch never leaves a broken ``proton-drive`` behind. The upstream check needs the network, but fails soft: offline, ``upgrade`` still installs the pinned version and just skips the "upstream is ahead" advisory. Session caveat after a binary swap ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ After replacing the binary, ``upgrade`` verifies the existing Proton session still works and tells you either way. Sessions normally survive an upgrade (the session lives in the OS keyring, not the binary), but if the check fails:: protonfs auth login is all that's needed. On headless hosts, make sure the keyring environment is in place first -- ``protonfs doctor`` diagnoses it. Repo-state migrations ---------------------- The layout of ``.protonfs/`` has evolved since 0.2.0. Old repos keep working -- every consumer migrates what it reads on the fly -- but ``protonfs upgrade`` run inside a protonfs root also brings the on-disk state itself current, in one explicit, previewable step: - **index schema**: pre-0.13 indexes (a bare ``{path: entry}`` document, or an older ``schema_version``) are re-saved at the current schema. - **device_id relocation**: 0.2.0-era repos carried ``device_id`` in the shared, committed ``config.json``; it belongs in the per-device, gitignored ``config.local.json``. - **control-file backfill**: ``.protonfs/ignore``, ``include``, and the control ``.gitattributes``/``.gitignore`` that newer releases create at setup are backfilled where missing. ``protonfs upgrade --check`` lists pending migrations without applying anything -- dry-run first on a repo you care about. Migrations are idempotent (running twice is a no-op), probe actual on-disk state rather than trusting a version marker, and never touch anything outside ``.protonfs/``. ``protonfs doctor`` also reports pending migrations, index-schema staleness, and support-matrix currency as warn-level checks. Scoping flags -------------- - ``protonfs upgrade --drive-only`` -- just the binary, skip migrations. - ``protonfs upgrade --repo-only`` -- just the migrations, skip the binary (errors when not inside a protonfs root). See also --------- * :doc:`stability` -- the support matrix, upgrade policy, and the frozen command surface (including ``upgrade``'s exact exit codes). * :doc:`reference/index` -- full ``upgrade`` command reference. * `CHANGELOG.md `_ -- per-release upgrade notes.