Stability Promise (M4.1)¶
This page is the protonfs contract for 3.x, as of 3.0.0: every command,
option/argument name, exit code, summary-line key, --format json key, sync-state
name, config file location, config key and environment variable listed here is a
stable public contract. A caller (human or script) that depends only on what is
documented on this page keeps working across 3.x releases; breaking any of it
requires 4.0.0. tests/test_cli_surface.py checks the frozen sets in CI.
1.0.0 set the first contract. 2.0.0 broke it deliberately (the sync-state vocabulary, #150; see Changes since the 1.0 contract). 3.0.0 is a major release by accident: a withdrawn breaking change’s commit message reached the release tooling. Nothing in 3.0.0 breaks anything relative to 2.6.0.
Not part of the contract: the Python API (the protonfs.* modules), console output
at -v and above, the phase/done progress lines, the event log
(.protonfs/events.log), and the formats of the index, hash cache and other files
under .protonfs/ that protonfs writes for itself.
Versioning policy¶
protonfs releases are cut by the shared ghtools pipeline (configured in
.github/ghtools.toml), which computes the next version from Conventional Commits: a
feat commit bumps minor, a
fix, perf or revert bumps patch, and a breaking commit (type!: or a
BREAKING CHANGE: footer) bumps major – once the project is at 1.0 or later. Before 1.0, that
same breaking-change signal is demoted to a minor bump instead, so day-to-day 0.x
development never jumps to 1.0.0 by accident. v1.0.0 itself is therefore always a
deliberate, manually-created tag, not something the automated release pipeline produces
on its own.
From v1.0.0 onward, any change that breaks something documented on this page –
removing or renaming a command/option, changing an exit code’s meaning, moving a config
file, dropping an environment variable – is a breaking change and requires that manual
major-version bump. Additive changes (a new command, a new optional flag, a new config
key with a backward-compatible default) remain minor/patch as normal.
Only the first line of a commit is read for its type (and !), but a
BREAKING CHANGE: footer line counts anywhere in the message. A squash merge’s message
carries the bodies of every commit it squashed, so a BREAKING CHANGE: footer from a
sub-commit whose break was later withdrawn still cuts a major. Delete such lines from
the squash message before merging. (This is how 3.0.0 happened.)
Release-override directives (from 1.0.0)¶
A +:<spec> token standing alone on its own line of a commit message
(footer-style) overrides the Conventional Commit classification for that release
entirely, where <spec> is major | minor | patch | pre |
prepre | rc. Prose mentions and quoted examples (like the ones on this page)
never actuate a release. The pre-release forms follow SemVer 2.0.0 precedence with
channels alpha < beta < rc:
From a final release
X.Y.Z:+:pre->X.(Y+1).0-alpha,+:prepre->X.(Y+1).0-alpha.0,+:rc->X.(Y+1).0-rc– a pre-release always belongs to the next minor, so it sorts after the released base.Within a pre-release:
+:prepreincrements the number (-alpha->-alpha.1);+:preadvances the channel (alpha->beta->rc-> the final release);+:rcjumps any earlier channel to-rcand increments when already there (-rc->-rc.1);+:patch/+:minorfinalize.Plain Conventional Commits landing during a pre-release only increment the pre-release number – leaving the channel always requires a directive.
Directives are imperative: they are not subject to the pre-1.0 breaking-change
demotion, and the highest-impact directive wins when several land in one release
batch. Pre-release tags are marked as GitHub pre-releases and publish to PyPI as
PEP 440 pre-releases (1.1.0-alpha.1 -> 1.1.0a1), which pip skips unless
--pre is passed.
Release notes¶
Each release’s CHANGELOG entry is any hand-written [Unreleased] content followed
by notes generated from the release’s Conventional Commits: grouped by type
(Features, Bug fixes, Performance, Reverts, Refactors, Documentation, Tests, Build,
CI, Style), chronological within each group (earliest first). chore commits and
[skip ci] housekeeping are excluded from release notes.
Exit-code contract¶
Every protonfs command follows the same top-level convention:
0– success.2– usage error: bad/missing arguments, unknown option, invalid choice value. This is Click’s own default behaviour and is not overridden anywhere.1– everything else: an operational failure (a Proton Drive error, a lock conflict, a config problem) or a command-specific non-zero outcome documented below. A user declining a confirmation prompt (no--yes/--force) also exits1.
du adds 3 (partial results; see its row under Command surface): the output is
printed in full, but a row failed to measure, or the trash total of du / (the /
row’s in_trash) is incomplete.
status and auth status layer additional meaning onto exit code 1/2 for
unattended callers, documented in the table below.
Output contract¶
Summary lines. Each transfer command prints one summary line on stdout:
[<label>: ]key=value key=value ..., space-separated, every value a non-negative
integer. Any failures follow it, one `` FAILED <name>: <error>`` line each. Required
keys always print; optional keys print only when non-zero.
Line |
Required keys |
Optional keys |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
push’s keys, plus |
push’s optional keys |
|
|
|
What each key counts:
transferred– files actually uploaded (push) or downloaded (pull).skipped– files proton-drive skipped: already in sync, or excluded.failed– files that failed; each has aFAILEDline.adopted– files already on Drive that push verified match the local copy and indexed without uploading.moved– files moved or renamed on Drive to follow a local move.trashed– Drive copies of files deleted locally, moved to the Drive trash (--deletions trash; with--dry-run, the ones that would be).local-deleted– files this machine held that are gone locally and were left alone on Drive.unsettled– files held back because they were modified within--min-age.untracked– filesimportstopped git tracking (added in 3.1.0).tracked– filesexportstaged for git to track (added in 3.1.0). Forexport,transferredcounts offloaded files downloaded,skippedfiles already on disk, andtrashedDrive copies moved to the Drive trash.offloaded/would offload– local copies removed (or that would be);bytes_reclaimed– their total size in bytes;skipped_unverified,skipped_modified,skipped_unsettled– files offload refused, by reason.
Rules: within 3.x a key is never renamed, removed or given a different meaning. New keys may appear in a minor release, so a caller must ignore keys it does not know. Key order is not part of the contract.
The counting rule. An exit code of 0, or a progress bar at 100%, is not proof
that every file was transferred. A run delivered everything a caller asked for only when
failed=0 and transferred, skipped and adopted together account for every
file the caller expected.
``–format json``. status --format json prints one object with the keys
counts ({<state>: n} over every state in Sync states), exit_code and
remote. ls --format json prints a list of row objects, whose keys depend on the
view:
files (the default):
path,state;--dirs:path,files,local_bytes,indexed_bytes,apparent_bytes,states;--trash:name,type.
The same rules apply: no key is renamed, removed or redefined within 3.x, and new keys may appear.
``du –format json`` (added in 3.4.0) prints one object per target (a list of objects
when several PATHs are given) with the keys target, generated_at (Unix time),
used_total (bytes or null), plan_size (bytes or null), trash and
rows. trash is null when no trash pass has run, else (whatever the target)
the stored pass, an object with at,
known (bytes measured, a lower bound unless complete), complete, partial
(reason text or null), unresolved_folders and unattributed (the groups of
trashed folders whose size could not be measured, each {parent, folders, reason}).
Each row has the keys depth,
path, name, kind (file, folder, section or gap), size,
descendants, pct_parent, pct_used, pct_plan (percent 0 to 100, or
null), in_trash (the trash pass, replaced folder by folder by any listing made
since), in_trash_complete, unchecked_bytes, checked_at
(Unix time), age_seconds, state (listed, sized, excluded,
unmeasured, error, partial (/ or /devices total leaves out a
section or device) or gap), exclusion (none, freeze, hide),
gap_kind (none, in_trash, unattributed, unreconciled), error
(failure text when state is error, else null), trash_at (Unix time of the
oldest measurement behind in_trash, which can be older than checked_at, or
null) and trash_unresolved (on the / row, the trashed folders whose size is
unknown; 0 elsewhere). --format
plain prints the row values tab-separated in that order, null as an empty string.
A figure is never shown without checked_at/age_seconds unless it is unknown.
Changes since the 1.0 contract¶
What a caller written against 1.0 needs to know. Only contract changes are listed; see the CHANGELOG for everything else.
Broken in 2.0.0 (#150):
The
syncedstate is nowlocally-indexedinstatus,status --format jsonkeys andls. Read the new name;ls --state syncedis accepted, with a warning, until 4.0.0.2.0.0 also reported a file this machine held that is now gone locally as
local-deletedwithout--remote; 2.2.1 restoredremote-onlyfor that case, as in 1.0, so only thesyncedrename remains a difference from 1.0.
Added:
Commands:
completions(1.5.0),schedule(1.8.0),verify(2.1.0),prune(2.2.0),import,export(3.1.0),du(3.4.0).Global options:
-v/--verbose,--progress-inline/--progress-lines,--event-log/--no-event-log(1.3.0).PATH...: every command that takes aPATHaccepts several, e.g. from a shell glob (1.1.0). Store discovery from a subdirectory andPATHrelative to the current directory (3.4.0); see Store discovery and PATH arguments.ls:--dirs,--format,--state(1.1.0);--visual(1.2.0).status:--format(1.1.0);--remote(2.0.0).push/pull:--strict(1.11.0).push:--min-age(2.4.0);--deletions,--allow-mass-delete(3.0.0).pull:--no-restore(3.0.0).offload:--min-age(2.2.0).verify:--repair(2.1.0),--index(2.4.0).schedule:--strict(1.11.0);--keep,--min-age(2.2.0);--deletions,--no-restore(3.0.0).Sync states: the full table in Sync states (2.0.0), including
lfs-pointerand the remote-view states.Config keys:
defaults.event_log,defaults.progress_style(1.3.0);defaults.manifest(2.1.0);defaults.batch_size,defaults.skip_thumbnails(2.5.0);defaults.deletions(3.0.0);defaults.clock_skew(3.3.0);du.refresh,du.plan_size(3.4.0, global only).Environment variables:
PROTONFS_EVENT_LOG,PROTONFS_PROGRESS_STYLE(1.3.0);PROTONFS_MANIFEST,PROTONFS_NO_MANIFEST(2.1.0);PROTONFS_BATCH_SIZE,PROTONFS_SKIP_THUMBNAILS,PROTONFS_TRANSFER_MIN_RATE(2.5.0);PROTONFS_DRIVE_CACHE_HOME(2.6.0);PROTONFS_CLOCK_SKEW,PROTONFS_CLOCK_AHEAD_LIMIT(3.3.0);PROTONFS_DU_REFRESH,PROTONFS_PLAN_SIZE,PROTONFS_DU_CACHE(3.4.0).The Output contract above (summary keys and
--format jsonkeys) is new in the 3.x contract; the keys themselves shipped with the options that print them.
Deprecated: ls --state synced, until 4.0.0.
Removed: nothing.
Store discovery and PATH arguments¶
Added in 3.4.0 (#232). A command that works on a store finds it the way git finds a
repository: the nearest ancestor of the current directory (itself included) that holds
.protonfs/config.json; with nested stores, the innermost one. Run from the store root
every command behaves as it did before 3.4.0; run from a subdirectory, which failed before
3.4.0, it now works.
PATHarguments are relative to the current directory as typed, and are mapped to store-relative paths, as git pathspecs are:protonfs push mload005insim/means whatprotonfs push sim/mload005means at the root..is the current directory and..works. An absolute local path is accepted.No PATH from a subdirectory acts on that subdirectory only, as
dudoes: protonfs push insim/isprotonfs push sim, and likewise forpull,status,ls,refresh,offload,prune,import,exportandschedule --add(whose job is stored with that path). Pass/(or..up to the root) to cover the whole store. From the store root, no PATH means the whole store, exactly as before. A note on stderr names the directory, andnothing to push,nothing to importandnothing to exportsayunder '<dir>', so a summary is never read as covering the whole store. Commands without a PATH (verify,trash,doctor,config,upgrade) are unaffected.A bare
/still means the whole store, from the store root and from any subdirectory (it is not a path outside the store).rmandrestorerefuse the store root itself (.,..up to it, its absolute path or/) with a usage error (exit2), because that would act on the whole remote root. Before 3.4.0,rm -r .at the store root was accepted: it trashed the whole remote root and left the index unchanged.A
PATHthat resolves outside the discovered store is a usage error (exit2) naming it; nothing is run.A quoted glob pattern expands relative to the current directory, with the matching rules it already had (
pushagainst the local tree,pullagainst the index). A*,?or[in the name of the directory you are standing in is taken literally.Human-readable messages print paths as you would type them from the current directory (
../sibling/xfrom a sibling directory). From the store root they are the store-relative paths they always were. That includes thelstable (including--dirs) and-vnarration; the machine formats (--format jsonandplain) always carry store-relative paths, wherever they are run. The event log (.protonfs/events.log, warnings included) and the remote manifest always record store-relative paths.setupkeeps creating a store in the directory it is run from.deinitrun from a subdirectory is a usage error (exit2) naming the store root to run it from.config get/config set(without--global),schedule,doctorandupgradeact on the discovered store;schedule --pathis read relative to the current directory and stored relative to the store, because a job runs from the root.dualready resolved its targets this way (3.4.0) and is unchanged.The per-store files (
.protonfs/, the index, the lock, the event log) always belong to the discovered store, never to the subdirectory. With no store above the current directory the error isprotonfs is not set up in this directory or any parent directory.
Global options (before the subcommand)¶
These flags are given before the subcommand (e.g. protonfs -vv --event-log pull) and apply to every command. A flag, when given, overrides its config key; when unset, the resolved config value is used, falling back to the built-in default.
-v/--verbose– repeatable,-v..``-vvvv``; raises console detail.--progress-inline/--progress-lines– progress render style (default:defaults.progress_style, else inline on a TTY).--event-log/--no-event-log– write.protonfs/events.log(default:defaults.event_log, else off).
Command surface¶
One-line contract and exit codes for every registered command. “Options” lists every flag/argument name; these names, not just their presence, are frozen.
Command |
Contract |
Exit codes |
|---|---|---|
|
Install/verify the proton-drive CLI, init |
|
|
Remove |
|
|
Summarize sync state as a count per state (see Sync states).
Argument: |
|
|
List tracked files with their sync state. Argument: |
|
|
Upload local-only/changed files to Drive. Argument: |
|
|
Move files git tracks in this store out of git and into the store (added in
3.1.0). Argument: |
|
|
Move files this store holds back into git (added in 3.1.0). Argument:
|
|
|
Download remote-only/changed files from Drive. Argument: |
|
|
Delete local bytes of protonfs-tracked files confirmed present on Drive.
Argument: |
|
|
Push, then offload by a retention policy: per directory keep the newest
|
|
|
Remove a file/directory from Drive (trash by default, |
|
|
Restore a trashed file/directory on Drive. Argument: |
|
|
List every item in |
|
|
Permanently empty |
|
|
Discover remote files and seed the local index (metadata-only). Argument:
|
|
|
Check the remote manifest ( |
|
|
Download and verify the official proton-drive CLI binary. Options:
|
|
|
Upgrade proton-drive to this release’s highest supported version (verify-first,
atomic swap; never past |
|
|
Check this host can run proton-drive (binary, session bus, OS keyring) and
version/state currency (support matrix, upstream advisory, index schema,
pending migrations, config layering). Warn-level findings suggest
protonfs upgrade without failing the exit code. Option: |
|
|
Print shell exports so |
|
|
Print, |
|
|
Install/list/remove cron jobs running protonfs on a schedule. |
|
|
Passthrough to |
Exit code is whatever |
|
Check for a valid session without invoking |
|
|
Print the resolved value of |
|
|
Set |
|
|
Read-only storage analysis of Proton Drive paths, trash included (added in
3.4.0). Argument: |
With |
Sync states¶
The state names printed by status, emitted as status --format json keys,
shown by ls and accepted by ls --state are part of this contract, and so is
the exit-code class each one maps to. Without --remote no state says anything
checked on Drive; the states marked remote view are only produced by
status --remote/ls --remote.
State |
Meaning |
|
|---|---|---|
|
Local matches the index (and, with a remote view, the remote agrees).
Renamed from |
clean ( |
|
Indexed but deliberately not materialised on this machine. |
clean ( |
|
An un-smudged git-LFS pointer stub; deliberately left alone. |
clean ( |
|
Present locally, not in the index. |
drift ( |
|
Remote view. Held by this machine, now gone locally, still listed on Drive. |
drift ( |
|
Absent locally, with the copy on Drive: listed on Drive and absent from the index (remote view), or held by this machine and now gone locally, as the index records (no remote view). |
drift ( |
|
Remote view. One side diverged from the index; the other did not. |
drift ( |
|
Remote view. A file not held locally whose remote copy moved or vanished. |
drift ( |
|
Local diverged from the index with no remote view to attribute a direction. |
conflict ( |
|
Remote view. Local and remote both diverged from the index. |
conflict ( |
Known keys for config get/config set: remote_root,
device_id, defaults.on_conflict, defaults.low_io,
defaults.event_log, defaults.progress_style,
defaults.manifest (added in 2.1.0), defaults.skip_thumbnails (added
in 2.5.0), defaults.deletions (added in 3.0.0), defaults.clock_skew
(added in 3.3.0). Global-config-only keys (config set needs --global; config
get works outside a store): du.refresh and du.plan_size (both
added in 3.4.0). Each is defined in the
Configuration
section of Command Reference.
Config files and precedence¶
Layered configuration, highest precedence first:
Environment variables (see below) – always win, per-key.
.protonfs/config.local.json– per-device, gitignored..protonfs/config.json– per-repo shared, committed (the sync contract).~/.config/protonfs/config.json– global user defaults.$XDG_CONFIG_HOMErelocates the~/.configbase;$PROTONFS_CONFIGoverrides the full path outright.Built-in defaults (
defaults.on_conflict=skip,defaults.low_io=false,defaults.manifest=true,defaults.skip_thumbnails=false,defaults.deletions=keep,defaults.clock_skew=off,defaults.event_log=false,defaults.progress_style=inline).
config get always reports the fully resolved value across all four layers.
config set writes to exactly one layer: the shared repo file by default, or the
global/local file with --global/--local (mutually exclusive).
Environment variables¶
Variable |
Purpose |
|---|---|
Overrides the global config file path outright (points directly at the file). |
|
Per-key override for the resolved |
|
Per-key override for the resolved |
|
Per-key override for the resolved |
|
Per-key override for the resolved |
|
Per-key override for the resolved |
|
Per-key override for the resolved |
|
Per-key override for the resolved |
|
Per-key override for the resolved |
|
Set (to any truthy value) to switch every remote-manifest read and write off on
this host, whatever |
|
Path/name of the |
|
Directory proton-drive’s cache is kept under (passed to it as |
|
Overrides the |
|
Explicit SHA-512 to verify a |
|
Timeout in seconds for a Drive listing call (default |
|
Max retries for a Drive listing call (default |
|
Base backoff in seconds between Drive listing retries (default |
|
Cap in seconds on the Drive listing retry backoff (default |
|
Per-key override for the resolved |
|
Minimum timeout in seconds for a Drive upload/download call (default |
|
Slowest transfer rate in bytes per second that still counts as progress; scales
each upload/download call’s timeout with its data (default |
|
Max retries for a Drive upload/download call (default |
|
Base backoff in seconds between Drive upload/download retries (default |
|
Cap in seconds on the Drive upload/download retry backoff (default |
|
Per-key override for the resolved |
|
Seconds this host’s clock may run ahead of Proton’s before uploads are refused
(default |
|
Per-key override for |
|
Per-key override for |
|
Path of the SQLite file |
|
Supplies the password for the protonfs-owned keyring bootstrap, instead of generating one. |
|
Set (to any truthy value) to disable protonfs’s Secret Service/keyring bootstrap entirely; the caller is responsible for providing one. |
Proton Drive support matrix¶
protonfs states, as a checkable contract, which proton-drive CLI versions
each of its own releases supports. src/protonfs/install.py exposes this as
SUPPORTED_DRIVE_VERSIONS (an explicit set of supported versions),
highest_supported() (the version install-drive/the upgrade command installs
– always equal to DEFAULT_VERSION), and is_supported(version). The
installed CLI’s own version is available via DriveClient.drive_version(), which
parses proton-drive version output (e.g. Proton Drive CLI
cli-drive@0.5.0+73e40d90) down to the comparable semver "0.5.0".
protonfs release |
Supported proton-drive versions |
Notes |
|---|---|---|
3.0.x |
|
|
1.0.x |
|
The first contracted matrix. |
Upgrade policy¶
A given protonfs release only ever upgrades proton-drive up to its own
highest_supported() – it will never install a proton-drive version newer
than that, even if one exists upstream. Picking up a newer upstream
proton-drive release requires upgrading protonfs itself: a maintainer runs
python .github/scripts/repin_proton_drive.py to independently verify and pin the
new version’s checksums for every supported platform, adds it to
SUPPORTED_DRIVE_VERSIONS, and cuts a new protonfs release with that as its
highest_supported(). This keeps the installed proton-drive version always
within the range a given protonfs release was built and tested against.
protonfs upgrade is the user-facing voice of this policy: it upgrades an
outdated binary to highest_supported() (SHA-512-verified before an atomic
swap), reports – without installing – when upstream’s Stable release is ahead,
and runs pending repo-state migrations. protonfs upgrade --check previews all
of it, exiting 0 when fully current and 1 when an upgrade is available.
See also¶
Getting Started for installation and first-run setup.
Upgrading for the upgrade story built on this support matrix.
Syncing across machines for the push/pull/status workflow this contract supports.