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 3.x, everything
documented on that page keeps working; a breaking change to any of it requires 4.0.0.
From 3.1 to 3.2¶
Nothing to do unless a script sets up new stores. protonfs setup takes a new
store’s Drive path as --remote-root PATH. Without a terminal it no longer reads the
path from standard input: a script that piped it in (echo /my-files/x | protonfs
setup) now stops with exit 1 and must pass --remote-root /my-files/x instead.
From 3.0 to 3.1¶
Nothing to do for most stores. A store at a git repository’s root no longer syncs .git: protonfs never uploads, downloads or indexes a path with a .git segment unless .protonfs/include names .git. If an earlier version already pushed
.git, that copy stays on Drive and in the index but is never pulled back or
trashed by push; protonfs rm -r .git moves it to the Drive trash without
touching the local repository.
The .protonfs/ignore and .protonfs/include rules now apply to downloads as well
as uploads: pull no longer brings down a file they exclude (it reports how many it
left on Drive), refresh no longer indexes one, and status and ls leave them
out, so an excluded file on Drive no longer makes status exit 1. Nothing already
on disk or on Drive is removed.
From 2.x to 3.0¶
Nothing to do. 3.0.0 is a major release by accident (a withdrawn breaking change’s commit message reached the release tooling) and breaks nothing relative to 2.6.0. Features documented as “added in 2.7.0” before 3.0.0 was released shipped in 3.0.0; there is no 2.7.0. Stability Promise (M4.1) now states the 3.x contract, including what changed since 1.0.
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:
syncedis nowlocally-indexed– instatuslines,status --format jsonkeys andlsoutput.ls --state syncedstill works, with a warning, until 4.0.0; a script parsing the output needs the new name.status --remoteis new: it walks Drive and classifies against it.status --format jsongains a"remote": true|falsefield.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 |
|---|---|---|
|
highest supported (default) |
No protonfs-visible behavioural change from 0.8.0: the commands, options and
|
|
supported (downgrade only) |
Renamed the conflict strategies ( |
|
supported (downgrade only) |
No protonfs-visible behavioural change from 0.6.0. |
|
supported (downgrade only) |
Required for the |
|
supported (downgrade only) |
Trash restore resolves |
|
supported (downgrade only) |
Accepts original-path |
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 olderschema_version) are re-saved at the current schema.device_id relocation: 0.2.0-era repos carried
device_idin the shared, committedconfig.json; it belongs in the per-device, gitignoredconfig.local.json.control-file backfill:
.protonfs/ignore,include, and the control.gitattributes/.gitignorethat 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¶
Stability Promise (M4.1) – the support matrix, upgrade policy, and the frozen command surface (including
upgrade’s exact exit codes).Command Reference – full
upgradecommand reference.CHANGELOG.md – per-release upgrade notes.