Upgrading

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 Stability Promise (M4.1): 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 Stability Promise (M4.1), 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 Stability Promise (M4.1)). 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 PROTONFS_DRIVE_VERSION.

proton-drive

Status

Notes

0.8.0

highest supported (default)

Required for the pass credentials store (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 (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