mirror of
https://github.com/narrrl/proton-drive-linux.git
synced 2026-11-03 16:41:26 +01:00
docs: restructure and update documentation for 2.5.0
Split the README into a short front page and task-oriented pages under docs/: installation, user guide, CLI reference, configuration and troubleshooting, with an index in docs/README.md. Rewrite RECOVERY.md around Continue This Backup Here and Restore Folders, and DEVELOPMENT.md around running, debugging and releasing from source. Bring ARCHITECTURE.md up to date with the read path, push events, the thread map, conflict copies and the machine profile, and move the feature design notes there. Collect planned work in ROADMAP.md. Link the threat model from SECURITY.md and the translation rules from CONTRIBUTING.md. Add scripts/publish-wiki.sh, which mirrors the user pages to the GitHub wiki with rewritten links and only pushes with --push.
This commit is contained in:
nvrl committed
1 parent
4b90abf3b5
commit
af869944cf
16 files changed
+1960
-873
No files matched your search
+14
-5
@@ -6,9 +6,10 @@ deliberately high — everything else is ordinary Rust review.
|
||||
|
||||
## Before you start
|
||||
|
||||
- Read [`AGENTS.md`](AGENTS.md) for repository conventions and
|
||||
[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for how the daemon, front ends, and SDK fit
|
||||
together.
|
||||
- Read [`AGENTS.md`](AGENTS.md) for repository conventions,
|
||||
[`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md) for building, running and debugging from source,
|
||||
and [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for how the daemon, front ends, and SDK fit
|
||||
together. [`docs/README.md`](docs/README.md) indexes the rest.
|
||||
- Check [`docs/BUGS.md`](docs/BUGS.md) — it is the authoritative issue ledger, and your problem may
|
||||
already be tracked there with context.
|
||||
- For anything larger than a fix, open an issue first so the design can be discussed before you
|
||||
@@ -23,8 +24,9 @@ cargo build --workspace
|
||||
```
|
||||
|
||||
GUI and FUSE targets need the GTK4, libadwaita, WebKitGTK 6, libsecret, D-Bus, and FUSE3
|
||||
development packages listed in the [README](README.md#prerequisites). Minimum supported Rust
|
||||
version is 1.96.
|
||||
development packages listed in [`docs/INSTALL.md`](docs/INSTALL.md#build-dependencies). Minimum
|
||||
supported Rust version is 1.96. [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md#running-from-source)
|
||||
explains how to run your build next to, or instead of, the installed service.
|
||||
|
||||
## Quality gates
|
||||
|
||||
@@ -51,6 +53,13 @@ use a dedicated test account, never one holding data you cannot lose.
|
||||
control-socket work stays off GTK's main thread.
|
||||
- **`staging/` and `recovery/` may hold the only copy of user data.** Nothing may clear or purge
|
||||
them opportunistically.
|
||||
- **The GUI is fully translated.** Wrap every user-visible string in the helpers from
|
||||
`crates/pdfs-gui/src/i18n.rs`, run `po/update.sh`, and translate the new entries in every
|
||||
catalog in `po/LINGUAS` in the same change. See [`docs/TRANSLATING.md`](docs/TRANSLATING.md).
|
||||
The CLI and daemon messages stay in English.
|
||||
- **Document what users see.** A new command, setting or behaviour belongs in the matching page
|
||||
under `docs/` (user guide, CLI reference or configuration) and in the `[Unreleased]` section of
|
||||
[`docs/CHANGELOG.md`](docs/CHANGELOG.md).
|
||||
|
||||
## Commits and pull requests
|
||||
|
||||
|
||||
@@ -4,513 +4,162 @@
|
||||
|
||||
# Proton Drive for Linux
|
||||
|
||||
**Files-on-demand Proton Drive for the Linux desktop** — a FUSE virtual mount with block-level
|
||||
caching, a scriptable CLI, and a native GTK4 app with tray and search launcher.
|
||||
**Proton Drive on the Linux desktop.** Your files as a folder that downloads on demand, synced
|
||||
local folders, Photos, sharing, and a native GTK4 app with tray and search launcher, plus a
|
||||
scriptable CLI.
|
||||
|
||||
[](https://github.com/narrrl/proton-drive-linux/actions/workflows/ci.yml)
|
||||
[](https://github.com/narrrl/proton-drive-linux/releases/latest)
|
||||
[](https://aur.archlinux.org/packages/proton-drive-for-linux)
|
||||
[](LICENSE)
|
||||
[](https://www.rust-lang.org)
|
||||
[](#prerequisites)
|
||||
|
||||
<img src="images/files.png" alt="The GTK4 file browser" width="820">
|
||||
<img src="images/files.png" alt="My files in the Proton Drive app" width="820">
|
||||
|
||||
</div>
|
||||
|
||||
> [!IMPORTANT]
|
||||
> This is an **unofficial**, community-built client. It is not affiliated with, endorsed by, or
|
||||
> supported by Proton AG. "Proton" and "Proton Drive" are trademarks of Proton AG, used here only
|
||||
> to describe what the software talks to. Use a test account first, and read
|
||||
> [`docs/RECOVERY.md`](docs/RECOVERY.md) before trusting it with data you cannot lose.
|
||||
|
||||
## Install
|
||||
|
||||
```bash
|
||||
# Debian / Ubuntu
|
||||
sudo apt install ./proton-drive-linux_*.deb
|
||||
|
||||
# Fedora
|
||||
sudo dnf install ./proton-drive-linux-*.rpm
|
||||
|
||||
# Arch Linux (AUR)
|
||||
paru -S proton-drive-for-linux # or -git / -bin
|
||||
```
|
||||
|
||||
Packages for each release are attached to the [latest
|
||||
release](https://github.com/narrrl/proton-drive-linux/releases/latest); see
|
||||
[Installation & Packages](#installation--packages) for details and
|
||||
[Building from Source](#building-from-source) to compile it yourself.
|
||||
|
||||
```bash
|
||||
pdfs login # sign in (SRP + 2FA, credentials go to the system keyring)
|
||||
pdfs status # mount state, queued writes, cache usage
|
||||
pdfs-app # the desktop app
|
||||
```
|
||||
|
||||
## Contents
|
||||
|
||||
- [Features](#features) · [Quick search](#quick-search-and-media-opening) · [Opening files](#choosing-how-files-open)
|
||||
- [Selective sync](#selective-sync-pdfsignore) · [Diagnostics](#diagnostics--maintenance) · [Scripting](#scripting---json)
|
||||
- [Performance](#performance--caching) · [Filesystem safety](#filesystem-safety) · [Screenshots](#screenshots)
|
||||
- [Prerequisites](#prerequisites) · [Building](#building-from-source) · [Packages](#installation--packages) · [Releases](#automated-releases-cicd)
|
||||
|
||||
**Documentation:** [Architecture](docs/ARCHITECTURE.md) · [Testing](docs/TESTING.md) ·
|
||||
[Recovery](docs/RECOVERY.md) · [Development](docs/DEVELOPMENT.md) · [Translating](docs/TRANSLATING.md) ·
|
||||
[Known issues](docs/BUGS.md) · [Changelog](docs/CHANGELOG.md) ·
|
||||
[Contributing](CONTRIBUTING.md) · [Security policy](SECURITY.md)
|
||||
> to describe what the software talks to. Try it with data you have another copy of first, and
|
||||
> read [what survives a lost machine](docs/RECOVERY.md) before you rely on it.
|
||||
|
||||
## Features
|
||||
|
||||
- **Files-on-Demand (FUSE)**: Mount your Proton Drive as a virtual filesystem where files are downloaded only when opened, utilizing smart block-level caching and disk-backed writes.
|
||||
- **Command-Line Interface (CLI)**: Manage your drive, authenticate, and monitor sync status directly from the terminal.
|
||||
- **Non-Blocking GTK4 Desktop App**: Browse files, manage pins, configure options, and monitor active transfers through a modern, native GUI with a fully non-blocking asynchronous main loop.
|
||||
- **File Thumbnails**: Browse locally cached image previews in Files, Shared, and Trash, including embedded previews from camera RAW files. Build a whole folder tree from the Files toolbar and resize the grid from the status bar.
|
||||
- **Shared Links & Invites**: Browse files shared with you by other users, and view/manage your own public shared links directly in the GUI.
|
||||
- **Local Backup (Computers)**: Sync and back up local directories (like Downloads, Documents, Pictures, etc.) directly to your Proton Drive account.
|
||||
- **Locations**: One page (and `pdfs locations`) listing every place Proton Drive occupies on this machine — the main mount plus each backed-up folder — with its mode, sync state, and whether it is read-only. Switching a folder between a full local copy and on-demand happens here.
|
||||
- **System Tray Integration**: Background indicator for status monitoring, quick actions, and fast sync controls.
|
||||
- **Unified Search Launcher (HUD)**: A resident Google Drive-style launcher (`pdfs-prompt`) that searches Proton Drive and local files together, ranks the best matches, tolerates abbreviations and typos, and is ideal for a system-wide hotkey. It can also present the same search in your own launcher (`--dmenu`) or, searching live as you type, in `fzf` (`--fzf`).
|
||||
- **Secure Credential Storage**: Integrates with the system Secret Service (GNOME Keyring, KWallet, etc.) with smart in-memory credential caching to avoid UI thread blockages.
|
||||
- **Proton Photos Support**: Access your Proton Photos timeline, view thumbnails, and download backed-up media natively (available in the GUI as a navigation tab and via the CLI).
|
||||
- **File Version History**: Every revision Proton Drive still holds for a file, from the browser's details pane (**Versions**) or `pdfs versions list|restore|save|rm`. Restoring is server-side — no re-upload — and an old version can be written out to a local file without touching the live one.
|
||||
- **Photo Favourites**: Star a photo in the lightbox, filter the gallery to favourites, or use `pdfs favorite <uid>` / `pdfs photos --favorites`.
|
||||
- **Photo Albums**: Browse your albums — including the ones shared with you — from the Albums view of the Photos page, or with `pdfs albums` / `pdfs album <uid>`. Album contents open in the same gallery as the timeline.
|
||||
- **Places**: The Places view of the Photos page groups photos by the town they were taken in, using the location stored with each photo, as cards or on a world map. Towns are looked up offline in [GeoNames](https://www.geonames.org/) data (CC BY 4.0), and the map is drawn offline from [Natural Earth](https://www.naturalearthdata.com/) land outlines and country borders (public domain). Each town is marked with one of its photos, and zoomed in, every photo sits where it was taken. A street map from [OpenFreeMap](https://openfreemap.org/) (© [OpenStreetMap](https://www.openstreetmap.org/copyright) contributors) can be turned on under Appearance; it is off by default because the tile server learns which parts of the world you look at. Install `iso-codes` for country names in your language.
|
||||
- **Human Verification (CAPTCHA) Recovery**: Detects sign-in gates (VPN/new IP challenges) and launches an embedded `WebKitWebView` dialog to safely complete the challenge, transparently retrying authentication with the earned token.
|
||||
- **Selective Sync (`.pdfsignore`)**: Keep build trees, dependency directories, and editor leftovers out of synced folders using gitignore-style rules.
|
||||
- **Data-Safe Offline Writes**: Durable scratch/staging files and a transactional pending queue preserve acknowledged writes across network failures and restarts.
|
||||
**Files**
|
||||
|
||||
## Quick Search and Media Opening
|
||||
- **Your Drive as a folder.** `~/ProtonDrive` works with every program. Files download when they
|
||||
are opened, a block at a time, so a video starts playing and a large archive can be read
|
||||
without fetching all of it.
|
||||
- **Available offline.** Keep chosen files and folders fully downloaded; everything else is
|
||||
cached within a size limit you set.
|
||||
- **Synced folders.** Back up folders such as `~/Documents` under your computer in Proton Drive,
|
||||
as a full two-way copy or online only. Gitignore-style `.pdfsignore` rules, conflict copies
|
||||
instead of overwrites, pause and bandwidth limits.
|
||||
- **Safe writes.** Changes are staged on disk and queued before they are acknowledged, so they
|
||||
survive a lost connection, a crash or a reboot and upload when they can.
|
||||
|
||||
`pdfs-prompt` searches Drive metadata and the local home-directory index in one request. Results are ranked together rather than split by source. Matching is case-insensitive and supports exact names, prefixes, parent paths, multiple terms, punctuation-separated words, ordered abbreviations, common typos, and adjacent transpositions.
|
||||
**Desktop app**
|
||||
|
||||
The prompt stays resident after its first launch, so invoking the shortcut again reuses and resets the existing window. Drive folders open from the mount. Audio and video results also open through FUSE, allowing media players to seek and request ranges without downloading the entire file first; ordinary Drive files are materialized into the local cache before opening.
|
||||
- **Browse** My files, Shared with me, Shared by me, Computers and Trash, with thumbnails
|
||||
(including camera RAW), drag and drop, details and **version history**.
|
||||
- **Photos.** Timeline with favorites, albums, and Places on a map; RAW+JPEG pairs shown as one
|
||||
photo; duplicate finder; slideshow; **import from Google Photos** (Takeout).
|
||||
- **Sharing.** Invite people as viewer, editor or admin, create public links with password and
|
||||
expiry, accept invitations.
|
||||
- **Sync overview.** What is uploading, what is waiting, what failed and why, and a history of
|
||||
what happened.
|
||||
- **Tray icon** with status, pause and quick actions, and a **search launcher** (`pdfs-prompt`)
|
||||
that searches Proton Drive and your home folder together, as its own window, through fuzzel,
|
||||
rofi or wofi, or live in `fzf`.
|
||||
- **Restore a computer.** Continue a backup on a new machine and bring its folders back in one
|
||||
step.
|
||||
- **Sign-in** with two-factor authentication and CAPTCHA; the session is kept in the system
|
||||
keyring.
|
||||
- Available in English, German, Spanish, French, Italian, Dutch, Polish and Brazilian
|
||||
Portuguese.
|
||||
|
||||
### Using your own launcher (fuzzel, rofi, wofi, …)
|
||||
**Command line**
|
||||
|
||||
`pdfs-prompt --dmenu` runs the same search through an external dmenu-style
|
||||
launcher instead of the built-in window, so the HUD matches the rest of a
|
||||
tiling-WM desktop:
|
||||
- About 55 `pdfs` commands cover files, sync, sharing, Photos, Trash, versions and diagnostics.
|
||||
Query commands print JSON with `--json`.
|
||||
|
||||
```bash
|
||||
pdfs-prompt --dmenu # fuzzel/rofi/wofi/tofi/bemenu/dmenu, whichever is installed
|
||||
pdfs-prompt --dmenu --menu 'fuzzel --dmenu --width 60'
|
||||
pdfs-prompt --dmenu --query invoice # skip straight to a search
|
||||
```
|
||||
## Install
|
||||
|
||||
A launcher filters a fixed list — it cannot ask for a new one per keystroke — so
|
||||
searching takes two steps, and the prompt says which step you are on:
|
||||
|
||||
- `Search Drive ›` lists your pinned files. Type anything that isn't one of them
|
||||
and press Enter to search for it.
|
||||
- `Drive: invoice ›` lists the results. Enter opens one; typing something else
|
||||
and pressing Enter searches again. Escape closes.
|
||||
|
||||
`--query` skips the first step. fuzzel and rofi also get file-type icons.
|
||||
|
||||
To make an existing keybinding use it without re-binding, and to pin the
|
||||
launcher command, set them in `config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"prompt": {
|
||||
"mode": "dmenu",
|
||||
"menu": ["fuzzel", "--dmenu", "--width", "60"],
|
||||
"menu_limit": 50
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`--gtk` overrides `"mode": "dmenu"` for one invocation. A `{prompt}` token
|
||||
anywhere in `menu` is replaced by the prompt text; without one, the launcher's
|
||||
own prompt flag is appended.
|
||||
|
||||
### Live launcher search (fzf)
|
||||
|
||||
The two-step above exists because no dmenu-style launcher can call back for new
|
||||
results per keystroke. `fzf` can, so `pdfs-prompt --fzf` searches as you type,
|
||||
exactly like the built-in window:
|
||||
|
||||
```bash
|
||||
pdfs-prompt --fzf # pinned files, then live results as you type
|
||||
pdfs-prompt --fzf --query invoice # start on a search
|
||||
```
|
||||
|
||||
Every keystroke re-queries the daemon (debounced, like the GTK prompt) and fzf's
|
||||
own matcher is switched off, so the ordering you see is the daemon's ranking —
|
||||
abbreviations and typos included, which a launcher filtering a fixed list cannot
|
||||
do. Enter opens; Escape closes.
|
||||
|
||||
fzf is a terminal program, so when it is started without one — from a WM
|
||||
keybinding — it spawns a terminal for itself: foot, ghostty, kitty, alacritty,
|
||||
wezterm or xterm, whichever is installed. Each is launched with the app-id/class
|
||||
`pdfs-prompt`, so one window rule floats it whichever terminal you have. In
|
||||
Hyprland:
|
||||
|
||||
```
|
||||
windowrulev2 = float, class:^(pdfs-prompt)$
|
||||
windowrulev2 = size 900 500, class:^(pdfs-prompt)$
|
||||
windowrulev2 = center, class:^(pdfs-prompt)$
|
||||
bind = SUPER, space, exec, pdfs-prompt --fzf
|
||||
```
|
||||
|
||||
Set it as the default front end, and pick the terminal explicitly, in
|
||||
`config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"prompt": {
|
||||
"mode": "fzf",
|
||||
"terminal": ["foot", "--app-id=pdfs-prompt", "--"],
|
||||
"menu_limit": 50
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
A `{cmd}` token anywhere in `terminal` is replaced by the command to run;
|
||||
without one it is appended, which is what every detected terminal expects.
|
||||
|
||||
## Choosing How Files Open
|
||||
|
||||
By default every result is handed to `xdg-open`. An `open_with` block in
|
||||
`config.json` overrides that per file type — for instance opening text in
|
||||
Neovim inside Alacritty, while everything else still goes to the desktop:
|
||||
|
||||
```json
|
||||
{
|
||||
"open_with": {
|
||||
"terminal": ["alacritty", "-e"],
|
||||
"rules": [
|
||||
{ "match": ["@text"], "command": ["nvim"], "terminal": true },
|
||||
{ "match": ["*.png", "*.jpg"], "command": ["imv"] }
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- `match` takes file-name globs (`*.md`, `notes-*.txt`) or the classes `@dir`,
|
||||
`@text`, `@document`, `@image`, `@media`, `@any`. First matching rule wins.
|
||||
- `command` is argv, not a shell line. A `{}` token is replaced by the path;
|
||||
without one the path is appended. `$VAR` tokens expand from the environment,
|
||||
so `["$EDITOR"]` follows your editor.
|
||||
- `"terminal": true` wraps the command in `terminal`. When that is unset, the
|
||||
terminal comes from `$PDFS_TERMINAL`, then `$TERMINAL`, then the first known
|
||||
emulator on `PATH`; a bare name like `TERMINAL=alacritty` gains the right
|
||||
"run this" flag automatically.
|
||||
- `"default": [...]` replaces `xdg-open` for everything unmatched.
|
||||
|
||||
The rules apply to the prompt (both front ends) and to the GTK browser, so a
|
||||
file opens the same way wherever it was picked. Patterns are matched against the
|
||||
Drive name — a downloaded file is stored in the cache under its content hash,
|
||||
which says nothing about its type, so matching that would send everything to
|
||||
`xdg-open`.
|
||||
|
||||
## Selective Sync (`.pdfsignore`)
|
||||
|
||||
Two-way synced folders skip paths matched by ignore rules, so syncing a project
|
||||
directory does not upload `node_modules/`, `target/`, or `.git/`.
|
||||
|
||||
Rules come from two places, and both apply:
|
||||
|
||||
1. **Per folder** — a `.pdfsignore` file at the root of the synced folder
|
||||
(`.protonignore` also works). Gitignore syntax, including negation:
|
||||
|
||||
```gitignore
|
||||
# everything build-related
|
||||
build/
|
||||
*.log
|
||||
|
||||
# ...except this one
|
||||
!important.log
|
||||
```
|
||||
|
||||
2. **Globally** — an `ignore_patterns` list in `config.json`, applied to every
|
||||
synced folder. When unset, sensible defaults apply: `.git/`, `.hg/`, `.svn/`,
|
||||
`node_modules/`, `target/`, `.venv/`, `__pycache__/`, `*~`, `*.swp`, `*.tmp`,
|
||||
`.DS_Store`, and `Thumbs.db`.
|
||||
|
||||
```json
|
||||
{
|
||||
"ignore_patterns": ["node_modules/", "target/", "*.iso"]
|
||||
}
|
||||
```
|
||||
|
||||
Set it to `[]` to opt out of the defaults entirely.
|
||||
|
||||
Rules are re-read at the start of every sync pass, so edits take effect on the
|
||||
next pass without restarting the daemon.
|
||||
|
||||
**Ignoring is never destructive.** If a rule starts matching a file that was
|
||||
already synced, its copy on Drive is left untouched — the file simply stops
|
||||
being tracked. Removing the rule later picks the existing remote file back up
|
||||
rather than re-uploading it.
|
||||
|
||||
## Diagnostics & Maintenance
|
||||
|
||||
When something looks wrong, `pdfs diagnose` checks the installation and prints a
|
||||
report. It runs without a daemon on purpose — the state worth diagnosing is
|
||||
usually the state where the daemon will not start:
|
||||
|
||||
```console
|
||||
$ pdfs diagnose
|
||||
Paths
|
||||
[ok ] state dir: /home/you/.local/state/proton-drive-linux
|
||||
[ok ] database: /home/you/.local/state/proton-drive-linux/cache.db (170.3 MiB)
|
||||
|
||||
Account
|
||||
[ok ] keyring session: you@proton.me
|
||||
|
||||
Daemon
|
||||
[ok ] daemon responding
|
||||
[ok ] mounted at: /home/you/ProtonDrive
|
||||
[ok ] queued writes: none
|
||||
|
||||
No problems found.
|
||||
```
|
||||
|
||||
It exits non-zero if any check fails, so it works in a health-check script.
|
||||
|
||||
For the local metadata database and content cache:
|
||||
|
||||
| Command | What it does |
|
||||
| Distribution | Package |
|
||||
|---|---|
|
||||
| `pdfs cache inspect` | Database size, reclaimable space, per-table row counts, cache usage against budget |
|
||||
| `pdfs cache inspect --deep` | Also runs SQLite's integrity check — reads every page, so it is slow on a large database |
|
||||
| `pdfs cache vacuum` | Checkpoints the write-ahead log and compacts the database |
|
||||
| `pdfs cache clear` | Deletes cached file content, keeping pinned files |
|
||||
| Debian, Ubuntu 24.04 or newer | `.deb` from the [latest release](https://github.com/narrrl/proton-drive-linux/releases/latest) |
|
||||
| Fedora 44 or newer | `.rpm` from the [latest release](https://github.com/narrrl/proton-drive-linux/releases/latest) |
|
||||
| Arch Linux | [`proton-drive-for-linux`](https://aur.archlinux.org/packages/proton-drive-for-linux) (also `-bin` and `-git`) in the AUR |
|
||||
| Anything else | [Build from source](docs/INSTALL.md#build-from-source) |
|
||||
|
||||
`vacuum` takes a write lock for its duration and needs room for a second copy of
|
||||
the database while it runs, so it is a deliberate operation rather than
|
||||
something the daemon does on a timer.
|
||||
|
||||
Before a release, run the real-kernel acceptance suite against a dedicated test
|
||||
account and mount. See [`docs/TESTING.md`](docs/TESTING.md); it includes optional
|
||||
two-mount convergence checks and confines destructive operations to a fresh
|
||||
test directory.
|
||||
|
||||
## Scripting (`--json`)
|
||||
|
||||
Query commands accept a global `--json` flag and emit machine-readable output:
|
||||
|
||||
```console
|
||||
$ pdfs --json sync list | jq '.items[] | select(.state != "idle") | .local_path'
|
||||
$ pdfs --json cache inspect | jq '.db_reclaimable_bytes'
|
||||
$ pdfs --json status | jq -r '.mount.mountpoint'
|
||||
```bash
|
||||
sudo apt install ./proton-drive-linux_*.deb # Debian, Ubuntu
|
||||
sudo dnf install ./proton-drive-linux-*.rpm # Fedora
|
||||
paru -S proton-drive-for-linux # Arch
|
||||
```
|
||||
|
||||
Supported on `status`, `ls`, `pins`, `sync list`, `devices list`, `transfers`,
|
||||
`activity`, and `cache inspect`. Commands that perform an action keep their
|
||||
human output — a script that needs to know whether one worked has the exit code.
|
||||
Then open **Proton Drive** from your applications menu and sign in. The app starts the background
|
||||
service, and your files appear in `~/ProtonDrive`.
|
||||
|
||||
Two things worth relying on:
|
||||
Signing in from a terminal instead? `pdfs login` stores the session but does not start the
|
||||
service. Enable it once:
|
||||
|
||||
- **The payload is unwrapped.** Output is `{"items": […]}`, not the daemon's
|
||||
internal `{"SyncFolders": {"items": […]}}`, so scripts never name an internal
|
||||
variant.
|
||||
- **Errors still fail.** A daemon-side error prints its JSON body (with a
|
||||
machine-readable `kind`) on stdout *and* exits non-zero, so `set -e` and
|
||||
`if pdfs …` behave as expected rather than treating a failed lookup as
|
||||
success.
|
||||
```bash
|
||||
pdfs login
|
||||
systemctl --user enable --now proton-drive.service
|
||||
pdfs status
|
||||
```
|
||||
|
||||
## Performance & Caching
|
||||
[docs/INSTALL.md](docs/INSTALL.md) has the requirements, optional extras (tray on GNOME, RAW and
|
||||
video thumbnails), headless use and uninstalling.
|
||||
|
||||
The client includes several optimizations designed for high efficiency, a low memory footprint, and a responsive user experience:
|
||||
## Documentation
|
||||
|
||||
- **On-Demand Block Cache**: Files are read in fixed 4 MiB blocks. For unpinned files, the client fetches and caches only the blocks containing the requested byte ranges. This enables fast sequential and sparse reads (e.g. media streaming or metadata scanning) without downloading entire files.
|
||||
- **Disk-Backed Writes**: Large file writes are staged on disk in temporary scratch files (rather than fully buffered in RAM) and track modified byte intervals. Only the unedited remote segments are fetched at commit time, keeping memory usage minimal.
|
||||
- **Non-Blocking GTK4 Loop**: To prevent UI freezes, all synchronous D-Bus credential checks, control socket requests, and cache usage calculations are offloaded to background worker threads or fetched asynchronously.
|
||||
- **Flicker-Free UI Rendering**: The GTK4 application performs differential rendering of the pins list, only modifying list rows when the list content changes, preserving the user's scroll position and widget focus.
|
||||
- **Durable Staging**: Scratch metadata and staged writes are synced and atomically published before an upload is acknowledged locally. Rapid revisions supersede pending work transactionally.
|
||||
|
||||
## Filesystem Safety
|
||||
|
||||
Version 1.0 strengthens the boundaries around local-only data and destructive reconciliation:
|
||||
|
||||
- Truncate composes with queued revisions, preserving the authoritative prefix and correct zero-filled growth.
|
||||
- Combined move-and-rename operations are queued durably and tolerate partially completed remote state.
|
||||
- Session tombstones prevent successfully unlinked entries from reappearing through eventually consistent listings.
|
||||
- Names are valid UTF-8 and no longer than Linux's 255-byte component limit.
|
||||
- Incomplete mirror scans are non-destructive, and total-wipe protection covers every non-empty baseline.
|
||||
- Failed conflict preservation, local deletion, or staging publication does not settle a new baseline or discard the only local copy.
|
||||
- State, cache, and config directories must be real, current-user-owned `0700` directories; control sockets are `0600`.
|
||||
| | |
|
||||
|---|---|
|
||||
| [User guide](docs/USER_GUIDE.md) | Everything the app, tray and launcher do |
|
||||
| [Command-line reference](docs/CLI.md) | Every `pdfs` command and scripting with `--json` |
|
||||
| [Configuration](docs/CONFIGURATION.md) | `config.json`, file locations, environment variables, the service |
|
||||
| [Troubleshooting](docs/TROUBLESHOOTING.md) | Diagnosing problems and fixing common ones |
|
||||
| [Recovering on a new computer](docs/RECOVERY.md) | Getting your synced folders back after a reinstall or a lost machine |
|
||||
| [Changelog](docs/CHANGELOG.md) | What changed in each release |
|
||||
|
||||
For contributors: [development guide](docs/DEVELOPMENT.md), [architecture](docs/ARCHITECTURE.md),
|
||||
[testing](docs/TESTING.md), [translating](docs/TRANSLATING.md), [roadmap](docs/ROADMAP.md) and the
|
||||
[bug ledger](docs/BUGS.md). The [documentation index](docs/README.md) lists everything.
|
||||
|
||||
## Screenshots
|
||||
|
||||
### GUI Application & Launcher
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<td align="center" width="50%"><img src="images/login.png" alt="Login Screen" width="100%"><br><sub><b>Login Screen</b></sub></td>
|
||||
<td align="center" width="50%"><img src="images/files.png" alt="Files Browser" width="100%"><br><sub><b>Files Browser</b></sub></td>
|
||||
<td align="center" width="50%"><img src="images/files.png" alt="My files" width="100%"><br><sub><b>My files</b></sub></td>
|
||||
<td align="center" width="50%"><img src="images/photos.png" alt="Photos timeline" width="100%"><br><sub><b>Photos</b></sub></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td align="center" width="50%"><img src="images/shared.png" alt="Shared Links" width="100%"><br><sub><b>Shared Links</b></sub></td>
|
||||
<td align="center" width="50%"><img src="images/shared_with_me.png" alt="Shared with me" width="100%"><br><sub><b>Shared with me</b></sub></td>
|
||||
<td align="center" width="50%"><img src="images/shared.png" alt="Shared by me" width="100%"><br><sub><b>Shared by me</b></sub></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td align="center" width="50%"><img src="images/restore_devices.png" alt="Local Backups (Computers)" width="100%"><br><sub><b>Local Backups (Computers)</b></sub></td>
|
||||
<td align="center" width="50%"><img src="images/photos.png" alt="Photos Timeline" width="100%"><br><sub><b>Photos Timeline</b></sub></td>
|
||||
<td align="center" width="50%"><img src="images/restore_devices.png" alt="Computers" width="100%"><br><sub><b>Computers</b></sub></td>
|
||||
<td align="center" width="50%"><img src="images/activity.png" alt="Sync history" width="100%"><br><sub><b>Sync</b></sub></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td align="center" width="50%"><img src="images/prompt_gtk.png" alt="Search Launcher Prompt (GTK)" width="100%"><br><sub><b>Search Launcher Prompt (GTK)</b></sub></td>
|
||||
<td align="center" width="50%"><img src="images/prompt_fzf.png" alt="Search Launcher Prompt (fzf)" width="100%"><br><sub><b>Search Launcher Prompt (fzf)</b></sub></td>
|
||||
<td align="center" width="50%"><img src="images/prompt_gtk.png" alt="Search launcher" width="100%"><br><sub><b>Search launcher</b></sub></td>
|
||||
<td align="center" width="50%"><img src="images/prompt_fzf.png" alt="Search launcher in fzf" width="100%"><br><sub><b>Search launcher in fzf</b></sub></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td align="center" width="50%"><img src="images/activity.png" alt="Activity" width="100%"><br><sub><b>Activity</b></sub></td>
|
||||
<td align="center" width="50%"><img src="images/settings.png" alt="Settings" width="100%"><br><sub><b>Settings</b></sub></td>
|
||||
<td align="center" width="50%"><img src="images/settings.png" alt="Preferences" width="100%"><br><sub><b>Preferences</b></sub></td>
|
||||
<td align="center" width="50%"><img src="images/login.png" alt="Sign in" width="100%"><br><sub><b>Sign in</b></sub></td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
---
|
||||
## How it works
|
||||
|
||||
## Prerequisites
|
||||
A background service (`proton-drive.service`, the `pdfs daemon` command) holds your session,
|
||||
mounts `~/ProtonDrive` through FUSE, runs the upload queue and the sync engine, and follows
|
||||
Proton's event stream for changes made elsewhere. The app, the tray, the launcher and the CLI are
|
||||
clients of that service over a local socket. Everything is end-to-end encrypted with your Proton
|
||||
keys before it leaves the machine, through a Rust implementation of Proton's Drive SDK.
|
||||
|
||||
To compile the application from source or run the built binaries, ensure you have the following system libraries installed on your distribution:
|
||||
|
||||
### Ubuntu / Debian (24.04+)
|
||||
```bash
|
||||
sudo apt-get update
|
||||
sudo apt-get install -y \
|
||||
pkg-config \
|
||||
libfuse3-dev \
|
||||
libgtk-4-dev \
|
||||
libadwaita-1-dev \
|
||||
libwebkitgtk-6.0-dev \
|
||||
libsecret-1-dev \
|
||||
libdbus-1-dev \
|
||||
libimage-exiftool-perl
|
||||
```
|
||||
|
||||
### Arch Linux
|
||||
```bash
|
||||
sudo pacman -S --needed pkgconf fuse3 gtk4 libadwaita libsecret dbus webkitgtk-6.0 perl-image-exiftool
|
||||
```
|
||||
|
||||
### Fedora (44+)
|
||||
```bash
|
||||
sudo dnf install -y \
|
||||
pkgconf-pkg-config fuse3-devel gtk4-devel libadwaita-devel \
|
||||
webkitgtk6.0-devel libsecret-devel dbus-devel glib2-devel \
|
||||
perl-Image-ExifTool cargo rust
|
||||
```
|
||||
|
||||
Runtime extras (pick your desktop):
|
||||
```bash
|
||||
# GNOME — keyring + tray (AppIndicator)
|
||||
sudo dnf install -y gnome-keyring gnome-shell-extension-appindicator xdg-utils
|
||||
|
||||
# KDE Plasma — KWallet (Secret Service); tray works via built-in SNI
|
||||
sudo dnf install -y kwallet xdg-utils
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Building from Source
|
||||
|
||||
Ensure you have Rust and Cargo installed (minimum supported Rust version is 1.96).
|
||||
|
||||
1. Clone the repository and navigate into the project directory:
|
||||
```bash
|
||||
git clone https://github.com/narrrl/proton-drive-linux.git
|
||||
cd proton-drive-linux
|
||||
```
|
||||
2. Build the workspace in release mode:
|
||||
```bash
|
||||
cargo build --release --locked
|
||||
```
|
||||
|
||||
The compiled binaries will be available under `target/release/`:
|
||||
- `pdfs`: The CLI utility.
|
||||
- `pdfs-app`: The GTK4 application.
|
||||
- `pdfs-tray`: The tray status notifier.
|
||||
- `pdfs-prompt`: The launcher prompt for quick HUD search.
|
||||
|
||||
---
|
||||
|
||||
## Installation & Packages
|
||||
|
||||
### 1. Debian / Ubuntu (.deb)
|
||||
Install the debian package via `dpkg` or `apt`:
|
||||
```bash
|
||||
sudo apt install ./proton-drive-linux_*.deb
|
||||
```
|
||||
|
||||
### 2. Arch Linux (AUR)
|
||||
Three AUR packages cover the usual choices; they conflict with each other, so
|
||||
install one:
|
||||
|
||||
| Package | Contents |
|
||||
| --- | --- |
|
||||
| [`proton-drive-for-linux`](https://aur.archlinux.org/packages/proton-drive-for-linux) | builds the latest tagged release from source |
|
||||
| [`proton-drive-for-linux-git`](https://aur.archlinux.org/packages/proton-drive-for-linux-git) | builds `main` from git |
|
||||
| [`proton-drive-for-linux-bin`](https://aur.archlinux.org/packages/proton-drive-for-linux-bin) | installs the release binaries, no compile |
|
||||
|
||||
```bash
|
||||
paru -S proton-drive-for-linux # or any AUR helper
|
||||
```
|
||||
|
||||
The package sources live in `packaging/aur/`; see
|
||||
[`packaging/aur/README.md`](packaging/aur/README.md) for how they are updated and
|
||||
published. A local `PKGBUILD` that compiles the working tree in place is still
|
||||
available for development builds:
|
||||
```bash
|
||||
cd packaging && makepkg -fi
|
||||
```
|
||||
|
||||
### 3. Fedora (local RPM)
|
||||
A local `.spec` is available under `packaging/`. From the repository root:
|
||||
```bash
|
||||
sudo dnf install -y rpm-build
|
||||
rpmbuild -bb packaging/proton-drive-linux.spec \
|
||||
--define "git_dir $PWD" \
|
||||
--define "_rpmdir $PWD/packaging/out" \
|
||||
--define "_builddir $PWD/packaging/build" \
|
||||
--define "_sourcedir $PWD" \
|
||||
--define "_specdir $PWD/packaging" \
|
||||
--define "_srcrpmdir $PWD/packaging/out"
|
||||
sudo dnf install packaging/out/x86_64/proton-drive-linux-*.rpm
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Automated Releases (CI/CD)
|
||||
|
||||
This project has a GitHub Actions CI workflow configured under `.github/workflows/release.yml`.
|
||||
|
||||
### How it works:
|
||||
1. **Triggers**:
|
||||
- Pushing a git tag matching `v*` (e.g. `git tag v0.1.0 && git push origin v0.1.0`).
|
||||
- Manual runs via the **Actions** tab in GitHub (**workflow_dispatch**).
|
||||
2. **Quality Gates and Build Process**:
|
||||
- For tagged builds, verifies that the tag, workspace version, and `packaging/PKGBUILD` version agree.
|
||||
- Runs `cargo fmt`, Clippy with warnings denied, the locked workspace test suite, and the account-free FUSE acceptance contract.
|
||||
- Spawns an Ubuntu runner and installs GTK4, Libadwaita, FUSE3, and Secret Service packages.
|
||||
- Sets up the Rust compiler and caches build targets to speed up runs.
|
||||
- Compiles the workspace members in release mode.
|
||||
3. **Artifact Packaging**:
|
||||
- Generates a `.tar.gz` containing the raw binaries (`pdfs`, `pdfs-app`, `pdfs-tray`, `pdfs-prompt`).
|
||||
- Packs them into Debian (`.deb`) and Fedora (`.rpm`) packages.
|
||||
- Includes the systemd user service and tray autostart entry in the Debian package.
|
||||
4. **Publishing**:
|
||||
- Creates a GitHub Release matching the pushed tag and uploads the `.deb`, `.rpm`, and `.tar.gz` packages as release assets.
|
||||
- For manual runs, compiles and exposes the packages as workflow run artifacts for testing.
|
||||
|
||||
---
|
||||
Files you open are decrypted into a local cache so programs can read them. What that means for
|
||||
the security of the machine is spelled out in the
|
||||
[threat model](docs/ARCHITECTURE.md#8-threat-model-what-this-client-writes-to-disk-in-plaintext).
|
||||
|
||||
## Contributing
|
||||
|
||||
Bug reports, packaging fixes, and patches are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for
|
||||
the workflow and the quality gates CI enforces, and [SECURITY.md](SECURITY.md) for reporting a
|
||||
vulnerability privately.
|
||||
|
||||
The app, tray and search prompt are available in English, German, Spanish, French, Italian, Dutch,
|
||||
Polish and Brazilian Portuguese. [docs/TRANSLATING.md](docs/TRANSLATING.md) explains how to improve
|
||||
a translation or add a language.
|
||||
Bug reports, translations and patches are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the
|
||||
workflow and the checks CI runs, and [SECURITY.md](SECURITY.md) to report a vulnerability
|
||||
privately.
|
||||
|
||||
## License
|
||||
|
||||
Released under the [MIT License](LICENSE).
|
||||
|
||||
The Places map uses [GeoNames](https://www.geonames.org/) data (CC BY 4.0) and
|
||||
[Natural Earth](https://www.naturalearthdata.com/) outlines (public domain). The optional street
|
||||
map comes from [OpenFreeMap](https://openfreemap.org/), © [OpenStreetMap](https://www.openstreetmap.org/copyright)
|
||||
contributors.
|
||||
|
||||
Proton Drive is a service of Proton AG. This project is an independent client and carries no
|
||||
affiliation with or endorsement from Proton AG.
|
||||
@@ -30,5 +30,10 @@ the interesting boundaries are:
|
||||
- **Cryptography.** Key derivation, signature handling, and anything that could publish plaintext
|
||||
or the wrong key material to Proton.
|
||||
|
||||
What the client deliberately keeps in plaintext on disk, and why, is documented in the
|
||||
[threat model](docs/ARCHITECTURE.md#8-threat-model-what-this-client-writes-to-disk-in-plaintext).
|
||||
Behaviour described there is known and not a vulnerability by itself; a way to make it worse
|
||||
than described is.
|
||||
|
||||
Out of scope: vulnerabilities in Proton's own service (report those to Proton AG), and issues that
|
||||
require an attacker who already has your user account on the machine.
|
||||
+216
-26
@@ -1,6 +1,13 @@
|
||||
# Proton Drive Linux Client: Architecture Specification
|
||||
# Architecture
|
||||
|
||||
This document provides a deep, comprehensive architectural description of the Proton Drive Linux Client (`pdfs`). It specifies the design patterns, data flows, thread models, and subsystem dependencies that govern the virtual filesystem (FUSE), database persistence, cache management, and two-way sync engine.
|
||||
This document describes how the Proton Drive Linux client (`pdfs`) is built: the crates, the
|
||||
filesystem and its caches, the write queue, the sync engine, the control protocol, the thread
|
||||
layout, what the client writes to disk in plaintext, and the CAPTCHA flow. It is written for
|
||||
contributors and for anyone auditing the client. User-facing documentation starts at
|
||||
[docs/README.md](README.md).
|
||||
|
||||
Numbers quoted here (thread counts, timeouts, limits) are the constants in the source at the time
|
||||
of writing; the source is authoritative when they disagree.
|
||||
|
||||
---
|
||||
|
||||
@@ -35,6 +42,11 @@ graph TD
|
||||
| [`pdfs-cli`](../crates/pdfs-cli) | Command Line Interface | Command routing, daemon launcher, IPC client wrapper. | Stateless; communicates with daemon over IPC control socket. |
|
||||
| [`pdfs-gui`](../crates/pdfs-gui) | Graphical Interface | GTK pages, tray, and the resident quick-search prompt. | Keeps UI state only; all durable state and Drive access remain behind the IPC socket. |
|
||||
|
||||
The workspace ships four binaries: `pdfs` (the CLI, and the daemon as `pdfs daemon`) from
|
||||
`pdfs-cli`, and `pdfs-app`, `pdfs-tray` and `pdfs-prompt` from `pdfs-gui`. The daemon runs as the
|
||||
systemd user unit `proton-drive.service`. Only the daemon holds the database, the caches and the
|
||||
API client; every other binary is a client of its control socket.
|
||||
|
||||
---
|
||||
|
||||
## 2. In-Memory VFS State & File Operations
|
||||
@@ -105,11 +117,29 @@ A mirror folder is a plain local directory with no FUSE session, so a row can le
|
||||
|
||||
## 3. Read Path & Block Caching Pipeline
|
||||
|
||||
Read requests are parallelized and served in blocks of size `BLOCK_SIZE` (4 MiB).
|
||||
Reads are served from the revision's content blocks. `Core::read_range` looks in three places
|
||||
before the network:
|
||||
|
||||
* **Unpinned files (Streaming):** Avoids writing full files to disk to preserve storage. Instead, blocks are kept in a fixed-size `stream_ring` (in-memory ring cache) and evicted immediately.
|
||||
* **Pinned files (Persistent):** Block downloads are saved directly to `ContentCache` on disk.
|
||||
* **Read-Ahead:** The reader thread spawns asynchronous tasks to pre-fetch upcoming blocks.
|
||||
1. **Whole-file blob.** A file kept available offline is downloaded completely into
|
||||
`ContentCache` and read from there.
|
||||
2. **Stream ring.** For every other file, a bounded in-memory ring (`RING_BYTES`, 128 MiB) of
|
||||
recently decrypted blocks is checked first, because the kernel reads in pieces far smaller
|
||||
than a block.
|
||||
3. **Block cache.** Blocks are then looked up on disk, under `content/blocks/`. They count
|
||||
against `cache_budget` and are evicted least-recently-used.
|
||||
|
||||
On a miss, only the blocks that overlap the request are fetched, through a `RevisionReader` kept
|
||||
open per revision (`MAX_OPEN_READERS = 64`, validated by `(mtime, size)`).
|
||||
|
||||
* **Block geometry.** Block boundaries come from the revision itself. The first read of a file
|
||||
assumes uniform `BLOCK_SIZE` (4 MiB) blocks; once a reader is open, the real block sizes are
|
||||
recorded (`store_block_geometry`) and later reads plan on them. Proton does not guarantee
|
||||
4 MiB blocks, and assuming it served wrong bytes (`docs/BUGS.md` B85).
|
||||
* **Read-ahead.** A read that proves sequential prefetches a window of 2 to 8 blocks
|
||||
(`PREFETCH_MIN`, `PREFETCH_MAX`). Prefetch takes a permit from a global budget of 8 and gives up
|
||||
instead of queueing, so it never delays a demand read.
|
||||
* **Large videos.** An unpinned video of 256 MiB or more (`STREAM_BYPASS_MIN`) streams without
|
||||
persisting its blocks, so watching a film does not evict the rest of the cache.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
@@ -121,21 +151,25 @@ sequenceDiagram
|
||||
participant API as Proton API Client
|
||||
|
||||
Kernel->>FUSE: read(ino, fh, offset, size)
|
||||
FUSE->>FUSE: calculate block indices [first_block..last_block]
|
||||
loop For each block index
|
||||
alt Block in disk Cache (Pinned/Cache hit)
|
||||
FUSE->>Cache: read_block(block_idx)
|
||||
Cache-->>FUSE: block bytes
|
||||
else Block in stream ring cache
|
||||
FUSE->>Ring: get(block_idx)
|
||||
Ring-->>FUSE: block bytes
|
||||
else Block Cache Miss
|
||||
FUSE->>API: download_range(offset, len)
|
||||
API-->>FUSE: decrypted block bytes
|
||||
alt caching_enabled
|
||||
FUSE->>Cache: store_block(block_idx)
|
||||
else streaming_only
|
||||
FUSE->>Ring: insert(block_idx)
|
||||
alt Whole-file blob cached (available offline)
|
||||
FUSE->>Cache: read blob range
|
||||
Cache-->>FUSE: bytes
|
||||
else
|
||||
FUSE->>FUSE: block_geometry() spans overlapping [offset, offset+size)
|
||||
loop For each span
|
||||
alt Span in stream ring
|
||||
FUSE->>Ring: get(span)
|
||||
Ring-->>FUSE: block bytes
|
||||
else Span in block cache
|
||||
FUSE->>Cache: read_block(span)
|
||||
Cache-->>FUSE: block bytes
|
||||
else Miss
|
||||
FUSE->>API: RevisionReader.read_at(span)
|
||||
API-->>FUSE: decrypted block bytes
|
||||
opt Not a large unpinned video
|
||||
FUSE->>Cache: store_block(span)
|
||||
end
|
||||
FUSE->>Ring: insert(span)
|
||||
end
|
||||
end
|
||||
end
|
||||
@@ -220,6 +254,35 @@ graph TD
|
||||
5. **Depth-Ascending Batching:** Folders are processed first to ensure hierarchies exist before files are placed. Work is executed concurrently up to a set limit.
|
||||
6. **Safety Gate and Settle:** Destructive plans are rejected when the scan is incomplete. Total-wipe protection applies to every non-empty baseline, including a single-entry folder. On success, baseline entries are upserted, timestamps updated, and any pending mode switches (e.g. going on-demand) are evaluated. Failed local deletion or conflict preservation retains the previous baseline and prevents remote content from overwriting the local source.
|
||||
|
||||
### Conflict Copies
|
||||
|
||||
A conflict keeps both versions. The local file is renamed to
|
||||
`{stem} (sync-conflict {unix_secs}).{ext}` (with `-1`, `-2`, … appended to the timestamp when the
|
||||
name is taken) and the remote version is downloaded under the original name. The conflict sweep
|
||||
(§7) later trashes copies proven byte-identical to their sibling when `conflict_sweep` is
|
||||
`enforce`.
|
||||
|
||||
### Devices and the Machine Profile
|
||||
|
||||
Synced folders live under a *device*: a per-computer root in Proton Drive. `Core::ensure_device`
|
||||
decides which device this machine is: the adopted `device_uid` from `config.json` when set,
|
||||
otherwise a Linux device whose name equals the hostname, otherwise a newly registered one. An
|
||||
adopted UID that no longer exists is reported, never silently replaced.
|
||||
|
||||
Because the local database does not survive a lost machine, the daemon backs up the machine's
|
||||
arrangement to `<device root>/.proton-drive-linux/profile.json` (`pdfs_core::profile`): each synced
|
||||
folder's remote UID, local path and mode, the pins, and the ignore patterns. It goes up the normal
|
||||
upload path and so is end-to-end encrypted like any other file. Mutating requests call
|
||||
`Core::touch_profile`, which coalesces a burst of changes into one upload. `PROFILE_VERSION`
|
||||
guards the format: a reader refuses a profile from a newer version instead of applying part of it.
|
||||
|
||||
Restore (`ListRestorableFolders`, `RestoreSyncFolders`, and the `Device` variants for another
|
||||
computer) lists the device root's folders, proposes a local path from the profile when its parent
|
||||
exists on this machine and `~/<name>` otherwise, and on confirmation adds a `sync_folder` row per
|
||||
folder bound to the remote UID. The download is an ordinary reconcile against an empty baseline;
|
||||
on-demand mode is applied through the normal mode-switch request. The user guide is
|
||||
[RECOVERY.md](RECOVERY.md).
|
||||
|
||||
---
|
||||
|
||||
## 6. IPC Socket Protocol
|
||||
@@ -232,7 +295,31 @@ The CLI and GUI front-ends do not access database files or make network calls di
|
||||
* **Control Protocol:**
|
||||
* Client sends a single JSON line (`Request`).
|
||||
* Daemon parses, handles the request, and replies with a single JSON line (`Response`).
|
||||
* Timeout durations are separated: **2 seconds** for writes (avoids hangs on defunct sockets) and **120 seconds** for reads (accommodates heavy transfers).
|
||||
* Timeout durations are separated: **2 seconds** for writes (avoids hangs on defunct sockets) and **120 seconds** for reads (accommodates heavy transfers). Status polls use a 5-second read timeout, which is what the app reports as "Not responding".
|
||||
* **Errors:** A failed request replies with `Response::Error { message, kind }`. The `kind` is machine-readable, and `pdfs --json` passes it through.
|
||||
* **Compatibility:** After an upgrade, the old daemon keeps running until the service restarts, so front ends must cope with a daemon that does not know a newer request. It answers such a request with an error instead of dropping the connection. New fields are added with `#[serde(default)]`, and new variants get a separate request rather than an optional field an old daemon would ignore.
|
||||
|
||||
### Push Events
|
||||
|
||||
Since 2.5.0 the front ends do not poll. The app and the tray each send `Request::Subscribe` once
|
||||
and keep the connection open; the daemon then streams one `Event` per line:
|
||||
|
||||
| Event | Sent when | Payload |
|
||||
|---|---|---|
|
||||
| `Status` | On subscribe, and whenever any status field changes | A full `Response::Status` |
|
||||
| `Transfers` | On subscribe, and whenever the transfer snapshot changes | Transfers and background jobs |
|
||||
| `Changed { topics }` | Something a page shows changed | `Topic`s to re-read: `files`, `photos`, `trash`, `shares`, `devices`, `locations`, `queue`, `conflicts`, `activity` |
|
||||
| `Heartbeat` | Every 10 seconds of silence | — |
|
||||
|
||||
Code that changes state publishes its topics to the `EventHub` (`crates/pdfs-fuse/src/events.rs`);
|
||||
the control handler maps each mutating request to the topics it touches. Changes within 150 ms
|
||||
of each other are coalesced into one event. A new subscription is told every topic changed, so it
|
||||
catches up on anything it missed. At most 8 subscriptions are served at once.
|
||||
|
||||
On the client side, `pdfs_core::control::follow` reconnects across daemon restarts with backoff
|
||||
and treats 25 seconds without a line as a stuck daemon. A daemon older than 2.5.0 answers
|
||||
`Subscribe` with an error; `follow` then falls back to polling status and transfers, so the front
|
||||
end sees the same events, only later.
|
||||
|
||||
### Unified Search
|
||||
|
||||
@@ -246,12 +333,18 @@ The prompt is a single-instance GTK application. It retains and hides its window
|
||||
|
||||
The background daemon relies on the following thread topology:
|
||||
|
||||
1. **Main Thread / Dispatch Loop:** Blocks on `fuser::Session` loop. Reads kernel FUSE events and hands off network-bound VFS work to the FUSE workers pool.
|
||||
1. **Main Thread / Dispatch Loop:** Blocks on `fuser::Session` loop. Reads kernel FUSE events and hands off network-bound VFS work to the FUSE workers pool. Each on-demand synced folder is a further FUSE session with its own dispatch loop and its own inode space (`State`).
|
||||
2. **FUSE Workers Pool (11 threads, two lanes):** Bounded thread pool handling network operations. Split into 3 threads reserved for metadata (`lookup`, `readdir`) and 8 general threads that serve transfers (block reads) and fall back to metadata when no transfer is waiting. Reserved threads never accept a transfer — that is what keeps a directory listing from queuing behind saturated downloads (audit A6).
|
||||
3. **IPC listener Thread:** Listens on the Unix socket and admits at most 64 concurrent, timeout-bound handlers for front-end status/configuration requests.
|
||||
4. **Sync Engine Loop Thread:** Serializes sync runs. Wakes on debounced local inotify filesystem changes, remote polling intervals, or manual user requests.
|
||||
5. **Drain Queue Worker Thread:** Processes staged writes (`PendingOp`) sequentially, uploading revisions and retrying with exponential backoff on failures.
|
||||
3. **Control Threads (`pdfs-control`):** Listen on the Unix socket and admit at most 64 concurrent, timeout-bound handlers. Long-lived subscriptions hold one handler each, up to 8 (see §6).
|
||||
4. **Sync Engine Threads (`pdfs-sync`, `pdfs-sync-poll`):** Serialize sync passes. Wake on debounced inotify changes, the periodic poll, remote events, or a user request.
|
||||
5. **Drain Workers (`pdfs-drain-0` … `pdfs-drain-2`):** `DRAIN_WORKERS = 3` threads share the queue of staged writes and changes (`PendingOp`), with per-node ordering (§4), and retry failures with exponential backoff. Worker 0 also runs the queue's idle chores.
|
||||
6. **Conflict Sweep Thread (`pdfs-conflict-sweep`, optional):** Reconciles leftover `(sync-conflict …)` copies — 30 s warmup, then one pass every 5 minutes. A copy proven identical to its live sibling (equal size **and** equal `content_sha1`) is redundant; anything it cannot prove identical is surfaced to the activity feed and left alone. Governed by `AppConfig.conflict_sweep` / `PDFS_CONFLICT_SWEEP` (`SweepMode`): **report-only by default**, `off` skips the thread entirely, and only `enforce` lets it trash. Because it deletes, the enforcing path re-verifies revision id, size, digest, name, parent, queued ops and open handles immediately before acting rather than trusting its own pass-start snapshot. See `docs/BUGS.md` B69 and B71.
|
||||
7. **Remote Event Tasks (Tokio):** `run_event_sync` follows Proton's event stream for the Drive volume and applies each change to every mounted inode space, invalidating kernel entries as it goes. The cursor is persisted after every batch, so changes made while the daemon was stopped are applied on the next start. `run_photos_event_sync` follows the photos volume separately; it only drops gallery rows or the timeline's freshness stamp, since photos are not part of the mount.
|
||||
8. **Event Sampler (`pdfs-events`):** Publishes status, transfer and sync-progress changes to subscribed front-ends (§6).
|
||||
9. **Supervisor (`pdfs-supervisor`):** Logs workers that hold one job for minutes, a queue that stops draining and control requests that never return; samples memory; and pings the systemd watchdog only after a real round trip over the control socket, so a hung daemon is restarted (`WatchdogSec=120`). `pdfs diagnostics` reports the same data on demand.
|
||||
10. **Smaller helpers:** `pdfs-online-probe` (connectivity), `pdfs-localindex` (home-directory index for the search prompt), `pdfs-pause` (ends a timed pause), `pdfs-conflict-sweep`, and `pdfs-similar` (duplicate-photo detection, on request).
|
||||
|
||||
Every long-lived loop waits on one shared `Shutdown` signal instead of sleeping, so an in-process remount joins the old generation of threads instead of leaking it (`docs/BUGS.md` B44).
|
||||
|
||||
---
|
||||
|
||||
@@ -377,3 +470,100 @@ sequenceDiagram
|
||||
This ensures compatibility with all versions of Proton's client verification scripts.
|
||||
3. **SRP Handshake Reset:** Because a gated login burns the SRP handshake on the API side, the client cannot simply resume the previous request. Instead, `auth::login_interactive` restarts the SRP process from scratch with the verification credentials attached, keeping the complex handshake details isolated from the front-end.
|
||||
4. **CLI Fallback:** Since the CLI has no native web browser engine, hitting the CAPTCHA gate fails immediately with a user-friendly message directing the user to sign in once via the GUI (`pdfs-app`) to persist the authenticated session keys to the system keyring.
|
||||
|
||||
---
|
||||
|
||||
## 10. Feature Design Notes
|
||||
|
||||
Notes on individual features whose code is shaped by a constraint that is not obvious from the
|
||||
code alone.
|
||||
|
||||
### File Version History
|
||||
**Files**: [`revisions.rs`](../crates/pdfs-fuse/src/revisions.rs), [`control.rs`](../crates/pdfs-core/src/control.rs), [`versions_dialog.rs`](../crates/pdfs-gui/src/app/widgets/versions_dialog.rs)
|
||||
|
||||
Proton Drive keeps every revision a client committed; the daemon only ever addressed the active one, so a file overwritten by a sync pass could be recovered only from whatever the local `recovery/` directory happened to hold.
|
||||
|
||||
The control protocol gained `ListRevisions` / `RestoreRevision` / `DeleteRevision` / `SaveRevisionAs` (each with a `…ByUid` twin for nodes the primary mount cannot name), the CLI gained `pdfs versions list|restore|save|rm`, and the browser's details pane gained a **Versions** button opening a per-file dialog.
|
||||
|
||||
Three properties that shape the code:
|
||||
|
||||
- **A restore is server-side and asynchronous.** No content crosses the wire and nothing enters the drain queue; the server answers 202 and swaps the active revision in the background, so the daemon evicts the file's cached blocks and open readers rather than describing the new state, and the UI wording promises the request, not the result.
|
||||
- **The active revision cannot be deleted.** `Core::delete_revision_for_uid` checks that locally so the user gets a sentence rather than an API code, and the dialog gives the current row no delete button.
|
||||
- **Saving a version never overwrites.** `SaveRevisionAs` refuses an existing destination and removes a partial file if the download fails — a half-written export looks identical to a good one to every tool that opens it afterwards.
|
||||
|
||||
### Photo Favorites
|
||||
**Files**: [`photos.rs`](../crates/pdfs-fuse/src/photos.rs), [`photo_viewer.rs`](../crates/pdfs-gui/src/app/pages/photo_viewer.rs)
|
||||
|
||||
The gallery can mark and filter favorites, through the SDK's photo-tag API (`update_photos`). Schema **v20** adds `photos.favorite`; the flag is learned in the timeline enrichment pass that already resolves each photo's name and media type, and is kept across a refresh that could not resolve a photo — the same learned-and-kept rule as `media_type`. The lightbox carries a star toggle, the Photos header a favorites filter, and the CLI has `pdfs favorite <uid> [--remove]` plus `pdfs photos --favorites`.
|
||||
|
||||
Favouriting a photo that is not on this account's own photos volume (shared with us, or album-only) needs it re-encrypted for our timeline root, which the SDK does not implement; the daemon surfaces that as an error rather than silently doing nothing.
|
||||
|
||||
### Justified Gallery, Gallery Delete
|
||||
**Files**: [`photos.rs`](../crates/pdfs-gui/src/app/pages/photos.rs), [`photo_viewer.rs`](../crates/pdfs-gui/src/app/pages/photo_viewer.rs), [`photos.rs`](../crates/pdfs-fuse/src/photos.rs), [`background.rs`](../crates/pdfs-fuse/src/background.rs)
|
||||
|
||||
The gallery lays each day out in justified rows (`justify_rows` / `plan_rows` / `fit_row`): photos are taken in capture order until their summed aspect ratio no longer fits the target row height, and the row is then scaled so it ends exactly on the content width. A tile is therefore its own photo's shape, and `ContentFit::Contain` has nothing left to crop. The last row of a day is left at the target height rather than stretched, because a day holding two photos is a short day, not a layout fault.
|
||||
|
||||
- **Ratios that are not known yet.** `PhotoItem::ratio` is persisted, but a photo that has never been decoded has none. Those are laid out square and remembered in `assumed_ratios`; when a decode proves the real shape the day re-flows on the existing debounce timer, so a screenful of decodes costs one re-flow rather than one per photo. Ratios are clamped to 0.4–3.0 so a single panorama cannot decide what a row looks like.
|
||||
- **Thumbnails survive recycling.** A reply for a tile that has already been re-bound still lands in the texture cache, which is an LRU of 1500 textures keyed by uid, and the rows just outside the realised range are prefetched in the scroll direction.
|
||||
- **Delete is uid-addressed.** The photos volume is not in the FUSE mount, so the path-based `Request::Delete` cannot reach it. `Request::TrashNodes { uids }` trashes through the SDK and answers `Response::Trashed { trashed, failed }`; the daemon then drops those rows with `Db::photos_delete` (album membership included) so the gallery does not wait for a timeline refresh. The GUI removes the tiles optimistically with an Undo toast and puts back anything the server refused.
|
||||
- **Remote deletions arrive on their own.** The Drive volume and the photos volume have separate event streams, so `run_photos_event_sync` polls the photos volume with its own cursor (`photos_event_cursor` in the state table). Trash and delete events remove rows; anything else only invalidates freshness, because there is no inode space to converge on this volume. Together with a 60 s `TIMELINE_TTL` and a `RefreshScope::Photos` that now awaits the refresh, a photo deleted on a phone leaves the grid in about ten seconds.
|
||||
|
||||
### RAW + JPEG Grouping
|
||||
**Files**: [`photos.rs`](../crates/pdfs-core/src/db/photos.rs), [`migrations.rs`](../crates/pdfs-core/src/db/migrations.rs), [`photos.rs`](../crates/pdfs-fuse/src/photos.rs), [`photo_viewer.rs`](../crates/pdfs-gui/src/app/pages/photo_viewer.rs)
|
||||
|
||||
Schema **v30** adds `content_hash`, `main_uid` and an indexed `group_key` to `photos`. The first two come from the server's `PhotoProperties` and are filled by the enrichment pass in `refresh_timeline` that already resolves each photo's name, media type and favorite tag; `group_key` is computed in `photos_replace`, where the whole timeline is in hand.
|
||||
|
||||
- **Precedence.** The server relation first (`main_photo_uid` and `related_photo_uids`, read from whichever end resolves — the two can land in different enrichment chunks); then same capture day, same case-insensitive name stem, and one member raw while the other is not; otherwise the photo is its own group. The union-find pass is over the timeline in memory, so it costs one pass per refresh rather than a query per photo.
|
||||
- **Representative.** The non-raw member when there is one — a JPEG decodes in milliseconds and is what the person expects to see. `group_key` holds that member's uid, so "is this the tile" is `uid = group_key`, an index scan.
|
||||
- **What is grouped and what is not.** `photos_page`, `photos_months` and `photos_counts` count groups, except on the Raw tab, which lists files. Album pages are never grouped: an album is a list someone made. The relation is learned-and-kept like `media_type`, so a refresh that could not resolve a node does not break a group up.
|
||||
- **Deleting.** `Core::trash_photos` expands each uid to its group before trashing, because the grid shows the shot as one tile — leaving the RAW behind would put the photo back on the Raw tab and nowhere else. The GUI's confirmation names the file count.
|
||||
- **The other files.** `Request::PhotoGroup { uid }` answers with the group's members as ordinary `PhotoItem`s, which is what the lightbox's switch steps through.
|
||||
|
||||
### Persistent SDK Entity Cache
|
||||
**Files**: [`sdkcache.rs`](../crates/pdfs-core/src/sdkcache.rs), [`auth.rs`](../crates/pdfs-core/src/auth.rs), [`background.rs`](../crates/pdfs-fuse/src/background.rs)
|
||||
|
||||
The SDK's Drive entity cache (decrypted node metadata: name, size, parent, signing share) defaulted to memory, so every daemon restart re-fetched and re-decrypted the tree the previous run had already walked. It is now backed by SQLite.
|
||||
|
||||
- **Its own file** (`sdk_cache.db` in the state directory), not `cache.db`: the daemon's `Db` is one `Mutex<Connection>` shared by every FUSE thread and the control socket, and this traffic is frequent, small and entirely reconstructible. A separate file also means no schema migration — the store can be deleted at any time.
|
||||
- **Encrypted at rest** by wrapping it in the SDK's `EncryptedCacheRepository`, keyed by the mailbox password. A password change reads as a cold cache (the SDK treats an undecryptable entry as a miss and clears the store), not as an error.
|
||||
- **Staleness** is closed by the event loop, which already replays from a persisted cursor and calls `invalidate_caches_for_event` for every event — including those raised while the daemon was down. The one case with no trail is a *seeded* cursor (first-ever mount, or a lost cursor), where the seed path now clears the store instead of trusting it. `auth::logout` removes the file.
|
||||
|
||||
Needed a small additive SDK change (`ProtonDriveClient::with_entity_repository`, 0.5.1): `with_entity_cache` is a constructor and so could not be combined with `with_key_salts`, which the daemon requires.
|
||||
|
||||
### Per-node Batch Outcomes
|
||||
**File**: [`batch.rs`](../crates/pdfs-core/src/batch.rs)
|
||||
|
||||
SDK 0.5.0 made `trash_nodes` / `restore_nodes` / `delete_nodes` report one outcome per node instead of failing the whole call (mirroring upstream's streamed `NodeActionResult`). `pdfs_core::batch::into_unit` collapses the single-node calls back to a `Result`; `batch::split` handles a collected batch.
|
||||
|
||||
A restore is expanded before it is sent (`expand_restore`, `pdfs-fuse/src/lib.rs`): the persisted trash listing carries each row's `parent_uid` (schema 29), so a restore takes the connected piece of the trashed tree — every trashed descendant of what was asked for, and every trashed ancestor above it — and sends it shallowest wave first, because the server cannot put a node back under a parent that is still trashed. A uid the listing does not know about (it is materialised in chunks, and can be stale) is restored on its own rather than dropped.
|
||||
|
||||
The trash view's restore and permanent-delete use the SDK's **streaming** variants (`restore_nodes_streaming` / `delete_nodes_streaming`) and apply local state per node as each batch lands rather than after the last one. For a permanent delete — which is irreversible — that means a daemon interrupted mid-batch has forgotten exactly the nodes the server destroyed, no more and no fewer. Both report per-node failures and count only what actually succeeded; only a batch where nothing succeeded is an error.
|
||||
|
||||
### Open-for-Write Deferral for Mirror Sync
|
||||
**File**: [`sync.rs`](../crates/pdfs-fuse/src/sync.rs)
|
||||
|
||||
The mirror folder sync engine now defers uploading any file that is currently held open for writing by another process, matching the guarantee the FUSE mount path already provides (where uploads are deferred until `close(fd)`).
|
||||
|
||||
**Problem**: Previously, the mirror sync path relied solely on a 2-second trailing-edge debounce (with a 30-second ceiling) to avoid uploading files mid-write. This was insufficient for slow continuous writers (e.g., database dumps, large exports, or editors that keep files open for extended periods), which could have their incomplete state uploaded as a real revision.
|
||||
|
||||
**Solution**: Before each reconcile pass, the sync engine scans `/proc/*/fd` once to build a set of canonical paths within the sync root that any process holds open for writing (`O_WRONLY` or `O_RDWR`). Files in this set are:
|
||||
|
||||
- **Kept in the local walk** — so they are not misclassified as deletions
|
||||
- **Treated as unchanged** — so no upload is queued for them
|
||||
- **Counted as `deferred`** — so the activity summary reports them (e.g., "3 uploaded, 1 deferred (open for write)")
|
||||
- **Picked up on the next pass** — after the writer has closed the file
|
||||
|
||||
**How it works**:
|
||||
1. `open_for_write_set(root)` reads `/proc/*/fd` → `readlink` for each fd → prefix-checks against the sync root → reads `/proc/<pid>/fdinfo/<n>` to check the `flags:` line's low two bits (O_ACCMODE)
|
||||
2. `walk_local` sets `LocalItem.open_for_write = true` for matching files
|
||||
3. Both `do_reconcile` and `push_pass` skip upload classification for flagged files
|
||||
4. `Outcome.deferred` tracks the count for the activity summary
|
||||
|
||||
**Performance**: The `/proc` scan completes in low single-digit milliseconds on a typical desktop. Only fds whose `readlink` target falls under the sync root incur the `fdinfo` read.
|
||||
|
||||
**Tests added**: 8 unit tests covering `is_write_mode` parsing of various fdinfo flag combinations, and `Outcome` summary formatting with deferred counts.
|
||||
|
||||
| Sync Path | Open-for-write protection | Mechanism |
|
||||
|---|---|---|
|
||||
| FUSE mount | Yes | Upload deferred until `close(fd)` |
|
||||
| Mirror folders | Yes | `/proc/*/fd` scan per reconcile pass |
|
||||
@@ -11,6 +11,17 @@ scratch (user data in `staging/` and `recovery/` is never touched by this).
|
||||
|
||||
## [Unreleased]
|
||||
|
||||
### Documentation
|
||||
- **Rewritten user documentation.** New pages for installation, the user guide, the command-line
|
||||
reference, configuration and troubleshooting, and a documentation index in `docs/README.md`.
|
||||
The README is shorter and points to them.
|
||||
- **Recovery** describes the current restore flow (adopting a computer, `pdfs sync restore`, the
|
||||
machine profile) instead of the old manual runbook.
|
||||
- **Architecture** covers push events, remote event streams, the revision block geometry, the
|
||||
thread layout of 2.5.0 and the machine profile. The development page is now a developer guide,
|
||||
and open work moved to `docs/ROADMAP.md`.
|
||||
- `scripts/publish-wiki.sh` publishes the user pages to the GitHub wiki.
|
||||
|
||||
## [2.5.0] — 2026-09-28
|
||||
|
||||
A polish pass over the desktop app: the daemon pushes changes instead of being polled, pages
|
||||
|
||||
+192
@@ -0,0 +1,192 @@
|
||||
# Command-line reference
|
||||
|
||||
`pdfs` controls the Proton Drive service from a terminal and from scripts. Almost every command
|
||||
talks to the running service (`proton-drive.service`); `login`, `logout`, `mount`, `daemon` and
|
||||
`diagnose` work without it.
|
||||
|
||||
`pdfs <command> --help` prints the full help of any command. This page groups them by task.
|
||||
|
||||
- [Conventions](#conventions)
|
||||
- [Account and service](#account-and-service)
|
||||
- [Files](#files)
|
||||
- [Available offline](#available-offline)
|
||||
- [Synced folders](#synced-folders)
|
||||
- [Conflicts](#conflicts)
|
||||
- [Computers](#computers)
|
||||
- [Trash](#trash)
|
||||
- [Versions](#versions)
|
||||
- [Sharing](#sharing)
|
||||
- [Photos](#photos)
|
||||
- [Activity and transfers](#activity-and-transfers)
|
||||
- [Maintenance and diagnostics](#maintenance-and-diagnostics)
|
||||
- [Scripting with `--json`](#scripting-with---json)
|
||||
|
||||
## Conventions
|
||||
|
||||
- **Paths** name items in My files. They may be absolute paths inside the Proton Drive folder
|
||||
(`~/ProtonDrive/Documents/a.pdf`) or relative to it (`Documents/a.pdf`).
|
||||
- **UIDs** identify items that have no path in the mount: photos, trashed items, shared items and
|
||||
computers. The listing commands print them.
|
||||
- **Exit codes**: `0` on success, non-zero on any failure, including an error reported by the
|
||||
service.
|
||||
- **Output** is English and stable enough for `grep`; use `--json` where it is available.
|
||||
|
||||
## Account and service
|
||||
|
||||
| Command | Description |
|
||||
|---|---|
|
||||
| `pdfs login [-u EMAIL]` | Sign in (password, then a 2FA code if the account has one) and store the session in the system keyring. Restarts the service if it is running. |
|
||||
| `pdfs logout` | Remove the stored session. |
|
||||
| `pdfs status` | Account, mount, queue and cache state. |
|
||||
| `pdfs quota` | Storage used across all Proton products. |
|
||||
| `pdfs locations` | Every local place the service occupies: the Proton Drive folder and each synced folder, with mode and state. |
|
||||
| `pdfs daemon [MOUNTPOINT]` | Run the service in the foreground: wait for a session, mount, stay mounted. `proton-drive.service` runs this. |
|
||||
| `pdfs mount [MOUNTPOINT]` | Mount once and block until unmounted. Defaults to `~/ProtonDrive`. |
|
||||
|
||||
`pdfs login` cannot show a CAPTCHA. If Proton asks for one, sign in with `pdfs-app` instead.
|
||||
|
||||
## Files
|
||||
|
||||
| Command | Description |
|
||||
|---|---|
|
||||
| `pdfs ls [PATH]` | List a folder. |
|
||||
| `pdfs search QUERY [--in FOLDER] [--limit N]` | Search names in the local index. |
|
||||
| `pdfs mkdir PARENT NAME` | Create a folder. |
|
||||
| `pdfs rename PATH NEW_NAME` | Rename a file or folder. |
|
||||
| `pdfs move PATH NEW_PARENT` | Move into another folder. |
|
||||
| `pdfs rm PATH` | Move to the Trash. |
|
||||
| `pdfs upload SOURCES... [-t FOLDER]` | Upload local files and folders (recursively) in the background. Follow with `pdfs transfers`. |
|
||||
| `pdfs refresh [TARGET] [--full]` | Forget a cached listing so the next read fetches it again. `TARGET` is a folder, `trash` or `photos`; `--full` with `photos` re-reads every photo's metadata. |
|
||||
|
||||
Ordinary file tools (`cp`, `mv`, `rsync`, editors) work on the Proton Drive folder directly. These
|
||||
commands are for scripts and for cases where the mount is not available.
|
||||
|
||||
## Available offline
|
||||
|
||||
| Command | Description |
|
||||
|---|---|
|
||||
| `pdfs pin PATH` | Download a file completely and keep it on this computer. |
|
||||
| `pdfs unpin PATH` | Release it back to online only. |
|
||||
| `pdfs pins` | List files kept available offline. |
|
||||
|
||||
## Synced folders
|
||||
|
||||
| Command | Description |
|
||||
|---|---|
|
||||
| `pdfs sync add PATH` | Back up a local folder under this computer and keep it in sync. |
|
||||
| `pdfs sync list` | List synced folders with their IDs and state. |
|
||||
| `pdfs sync rm ID [--delete-remote]` | Stop syncing. Local files stay; `--delete-remote` also removes the copy on Proton Drive. |
|
||||
| `pdfs sync mode ID mirror\|ondemand` | Switch between a full local copy (`mirror`) and online only (`ondemand`). |
|
||||
| `pdfs sync now [ID]` | Start a sync pass now, for all folders or one. |
|
||||
| `pdfs sync pause [--for 1h] [--folder ID]` | Pause uploads and synced folders. Reading files keeps working. `--for` ends the pause by itself (`30m`, `1h`, `2d`). |
|
||||
| `pdfs sync resume [--folder ID]` | Resume after a pause. |
|
||||
| `pdfs sync limit [--up RATE] [--down RATE]` | Cap bandwidth, for example `500K` or `2M` per second. `0` removes a cap. Without options, prints the current caps. |
|
||||
| `pdfs sync queue` | List changes that have not reached Proton Drive yet. |
|
||||
| `pdfs sync retry [ID]` | Retry one queued operation, or every failed one. |
|
||||
| `pdfs sync restore [--device UID] [--yes]` | Re-attach this computer's backed-up folders to local folders and download them. `--device` restores another computer's folders. See [RECOVERY.md](RECOVERY.md). |
|
||||
|
||||
## Conflicts
|
||||
|
||||
| Command | Description |
|
||||
|---|---|
|
||||
| `pdfs conflicts` | List `(sync-conflict …)` copies. |
|
||||
| `pdfs conflicts resolve PATH --keep original\|copy\|both [--name NAME]` | `original` trashes the copy; `copy` trashes the original and gives the copy its name; `both` renames the copy to `--name`. |
|
||||
|
||||
## Computers
|
||||
|
||||
| Command | Description |
|
||||
|---|---|
|
||||
| `pdfs devices list` | List computers registered to the account. |
|
||||
| `pdfs devices rename UID NAME` | Rename a computer. |
|
||||
| `pdfs devices rm UID` | Remove a computer and its backup from the account. |
|
||||
| `pdfs devices adopt UID` | Make this machine continue another computer's backup, for example after a reinstall. `--clear` returns to matching by hostname. |
|
||||
|
||||
## Trash
|
||||
|
||||
| Command | Description |
|
||||
|---|---|
|
||||
| `pdfs trash` | List the Trash with the UIDs the next commands take. |
|
||||
| `pdfs restore UIDS...` | Put items back where they were. |
|
||||
| `pdfs delete-forever UIDS...` | Delete items permanently. |
|
||||
| `pdfs empty-trash` | Delete everything in the Trash permanently. |
|
||||
|
||||
## Versions
|
||||
|
||||
| Command | Description |
|
||||
|---|---|
|
||||
| `pdfs versions list PATH` | List a file's versions, newest first. |
|
||||
| `pdfs versions restore PATH ID` | Make an earlier version current. Runs on the server; nothing is re-uploaded. |
|
||||
| `pdfs versions save PATH ID DEST` | Write an earlier version to a local file. Refuses to overwrite `DEST`. |
|
||||
| `pdfs versions rm PATH ID` | Delete an earlier version permanently. The current version cannot be deleted. |
|
||||
|
||||
## Sharing
|
||||
|
||||
| Command | Description |
|
||||
|---|---|
|
||||
| `pdfs share PATH EMAILS... [--role viewer\|editor\|admin] [--message TEXT]` | Invite people to a file or folder. |
|
||||
| `pdfs members PATH` | List members, pending invitations and the public link. |
|
||||
| `pdfs share-role PATH ID KIND ROLE` | Change a member's or invitation's role. |
|
||||
| `pdfs unshare PATH [ID KIND]` | Stop sharing, or remove one member or invitation. |
|
||||
| `pdfs public-link create PATH [--role] [--password] [--expires EPOCH]` | Create a public link. `--expires` takes Unix seconds. |
|
||||
| `pdfs public-link remove PATH ID` | Remove a public link. |
|
||||
| `pdfs shared` | List what you share. |
|
||||
| `pdfs shared-with-me [UID]` | List what others share with you, or the contents of one shared folder. |
|
||||
| `pdfs shared-get UID [DEST]` | Download a file shared with you. |
|
||||
| `pdfs leave UID` | Leave a share. |
|
||||
| `pdfs invitations list\|accept ID\|reject ID` | Manage invitations addressed to you. |
|
||||
| `pdfs bookmarks list\|add URL [--password]\|rm TOKEN` | Manage saved public links. |
|
||||
|
||||
## Photos
|
||||
|
||||
| Command | Description |
|
||||
|---|---|
|
||||
| `pdfs photos [--limit N] [--offset N] [--favorites]` | List the timeline, newest first. |
|
||||
| `pdfs open-photo UID` | Download a photo and print its cached path. |
|
||||
| `pdfs favorite UID [--remove]` | Mark or unmark a favorite. |
|
||||
| `pdfs albums` | List albums, including those shared with you. |
|
||||
| `pdfs album UID` | List an album's photos. |
|
||||
| `pdfs new-album NAME` | Create an album and print its UID. |
|
||||
| `pdfs rename-album UID NAME` | Rename an album. |
|
||||
| `pdfs delete-album UID` | Delete an album. Its photos stay in the timeline. |
|
||||
| `pdfs add-to-album UID PHOTOS...` | Add photos to an album. |
|
||||
| `pdfs remove-from-album UID PHOTOS...` | Take photos out of an album. |
|
||||
| `pdfs import-google-photos ARCHIVES... [--dry-run] [--wait]` | Import a Google Takeout export. Pass every `.zip` of the export. |
|
||||
| `pdfs import-status` / `pdfs cancel-import` | Follow or stop a running import. |
|
||||
| `pdfs redate-photos [--dry-run] [--from DATE] [--to DATE] [--limit N] [--wait]` | Fix photos filed under their upload day when the file name carries the real date. |
|
||||
| `pdfs redate-status` / `pdfs cancel-redate` | Follow or stop a running re-date. |
|
||||
|
||||
## Activity and transfers
|
||||
|
||||
| Command | Description |
|
||||
|---|---|
|
||||
| `pdfs activity [-l N]` | Recent activity, newest first. |
|
||||
| `pdfs transfers` | Uploads and downloads in progress. |
|
||||
|
||||
## Maintenance and diagnostics
|
||||
|
||||
| Command | Description |
|
||||
|---|---|
|
||||
| `pdfs diagnose` | Check the installation and print a report. Works without the service. Exits non-zero if a check fails. |
|
||||
| `pdfs diagnostics` | What a running service is doing now: worker threads, queues, requests in flight, memory. For a service that has stopped answering. |
|
||||
| `pdfs cache inspect [--deep]` | Database size, reclaimable space, row counts, cache use against the limit. `--deep` also runs SQLite's integrity check (slow). |
|
||||
| `pdfs cache vacuum` | Compact the database. Needs free space for a second copy of it while it runs. |
|
||||
| `pdfs cache clear` | Delete cached file content. Files kept available offline stay. |
|
||||
|
||||
[TROUBLESHOOTING.md](TROUBLESHOOTING.md) explains when to use each of these.
|
||||
|
||||
## Scripting with `--json`
|
||||
|
||||
The global `--json` flag makes query commands print JSON: `status`, `ls`, `pins`, `sync list`,
|
||||
`devices list`, `locations`, `transfers`, `activity` and `cache inspect`. Commands that change
|
||||
something keep their human-readable output; check their exit code.
|
||||
|
||||
```bash
|
||||
pdfs --json status | jq -r '.mount.mountpoint'
|
||||
pdfs --json sync list | jq -r '.items[] | select(.state != "idle") | .local_path'
|
||||
pdfs --json cache inspect | jq '.db_reclaimable_bytes'
|
||||
```
|
||||
|
||||
- The payload is unwrapped: a list is `{"items": [...]}`, never the service's internal message
|
||||
name.
|
||||
- An error from the service is printed as JSON with a machine-readable `kind` and still exits
|
||||
non-zero, so `set -e` and `if pdfs …` behave as expected.
|
||||
@@ -0,0 +1,201 @@
|
||||
# Configuration
|
||||
|
||||
Most settings are in the app under **Preferences**. This page documents the configuration file
|
||||
behind them, the settings that exist only there, the environment variables the programs read,
|
||||
and where the client keeps its data.
|
||||
|
||||
- [Files and directories](#files-and-directories)
|
||||
- [`config.json`](#configjson)
|
||||
- [Environment variables](#environment-variables)
|
||||
- [The systemd service](#the-systemd-service)
|
||||
|
||||
## Files and directories
|
||||
|
||||
| Path | Contents |
|
||||
|---|---|
|
||||
| `~/.config/proton-drive-linux/config.json` | Settings (this page) |
|
||||
| `~/.local/state/proton-drive-linux/cache.db` | Metadata database: names, folder tree, sync state, upload queue, photo index |
|
||||
| `~/.local/state/proton-drive-linux/sdk_cache.db` | Encrypted cache of Proton Drive metadata. Safe to delete while the service is stopped |
|
||||
| `~/.local/state/proton-drive-linux/control.sock` | Socket the app, tray, prompt and CLI use to reach the service |
|
||||
| `~/.cache/proton-drive-linux/content/` | File content cache, see below |
|
||||
| `~/ProtonDrive` | The Proton Drive folder (default mountpoint) |
|
||||
| System keyring | The session. Never written to disk by the client |
|
||||
|
||||
The directories honour `XDG_CONFIG_HOME`, `XDG_STATE_HOME` and `XDG_CACHE_HOME`. They must be real
|
||||
directories owned by you with mode `0700`; the service refuses to start otherwise.
|
||||
|
||||
Inside `content/`:
|
||||
|
||||
| Directory | Contents | Safe to delete? |
|
||||
|---|---|---|
|
||||
| top level, `blocks/`, `thumbs/` | Cached file content and thumbnails | Yes — use `pdfs cache clear` |
|
||||
| `scratch/` | Files open for writing right now | **No** |
|
||||
| `staging/` | Closed files waiting to upload | **No** — may be the only copy |
|
||||
| `recovery/` | Writes rescued after a crash, waiting to be queued | **No** — may be the only copy |
|
||||
|
||||
> [!CAUTION]
|
||||
> Never delete `staging/` or `recovery/` by hand. Check `pdfs sync queue` first. Content there has
|
||||
> not reached Proton Drive and exists nowhere else.
|
||||
|
||||
Everything in these directories except the keyring is **decrypted**. See
|
||||
[ARCHITECTURE.md §8](ARCHITECTURE.md#8-threat-model-what-this-client-writes-to-disk-in-plaintext).
|
||||
|
||||
## `config.json`
|
||||
|
||||
The file is created with defaults on first start. Every key is optional; a missing key takes its
|
||||
default. Edit it while the app is closed, then restart the service
|
||||
(`systemctl --user restart proton-drive.service`) for service settings to apply.
|
||||
|
||||
An unreadable file is never overwritten: the programs log an error and run with defaults until you
|
||||
fix it.
|
||||
|
||||
```json
|
||||
{
|
||||
"mountpoint": "/home/you/ProtonDrive",
|
||||
"cache_budget": 10737418240,
|
||||
"upload_limit": null,
|
||||
"download_limit": 5242880,
|
||||
"ignore_patterns": ["node_modules/", "target/", "*.iso"],
|
||||
"language": "de",
|
||||
"proton_theme": true,
|
||||
"online_map": false,
|
||||
"tray_hidden": false,
|
||||
"files_view": { "list": true, "sort": "modified", "descending": true, "folders_first": true },
|
||||
"open_with": {
|
||||
"terminal": ["alacritty", "-e"],
|
||||
"rules": [{ "match": ["@text"], "command": ["nvim"], "terminal": true }]
|
||||
},
|
||||
"prompt": { "mode": "fzf", "menu_limit": 50 }
|
||||
}
|
||||
```
|
||||
|
||||
### Reference
|
||||
|
||||
| Key | Type | Default | In the app | Meaning |
|
||||
|---|---|---|---|---|
|
||||
| `mountpoint` | path | `~/ProtonDrive` | General → Location | Where My files is mounted |
|
||||
| `cache_budget` | bytes | 5 GiB | Storage → Cache | Soft limit for cached content. `0` means unlimited. Available-offline files do not count against it |
|
||||
| `upload_limit` | bytes/s | none | General → Network | Shared cap for all uploads. `0` or `null` means none |
|
||||
| `download_limit` | bytes/s | none | General → Network | Shared cap for all downloads, reads from the mount included |
|
||||
| `ignore_patterns` | list | see below | — | Global ignore rules for synced folders |
|
||||
| `device_uid` | string | none | Computers → Continue This Backup Here… | The computer this machine continues. Unset means "match by hostname" |
|
||||
| `conflict_sweep` | `off` / `report` / `enforce` | `report` | — | See [`conflict_sweep`](#conflict_sweep) |
|
||||
| `language` | gettext code | system | General → Appearance | Language of the app, tray and prompt, such as `de` or `pt_BR` |
|
||||
| `proton_theme` | bool | follow system | General → Appearance | Proton's colours instead of the system theme |
|
||||
| `online_map` | bool | `false` | General → Appearance | Street map for Places from OpenFreeMap |
|
||||
| `tray_hidden` | bool | `false` | General → Appearance | Hide the tray icon |
|
||||
| `files_view` | object | grid, by name | My files view menu | `list`, `sort` (`name`, `size`, `modified`), `descending`, `folders_first` |
|
||||
| `open_with` | object | `xdg-open` | — | See [`open_with`](#open_with) |
|
||||
| `prompt` | object | built-in window | — | See [`prompt`](#prompt) |
|
||||
|
||||
`app_version` and `user_agent` identify the client to Proton. Leave them alone.
|
||||
|
||||
### `ignore_patterns`
|
||||
|
||||
Gitignore-style rules applied to every synced folder, in addition to each folder's own
|
||||
`.pdfsignore`. When the key is absent, these defaults apply:
|
||||
|
||||
```json
|
||||
[".git/", ".hg/", ".svn/", "node_modules/", "target/", ".venv/", "__pycache__/",
|
||||
"*~", "*.swp", "*.tmp", ".DS_Store", "Thumbs.db"]
|
||||
```
|
||||
|
||||
Set it to `[]` to turn the defaults off. See
|
||||
[USER_GUIDE.md](USER_GUIDE.md#excluding-files-with-pdfsignore) for how ignoring behaves.
|
||||
|
||||
### `conflict_sweep`
|
||||
|
||||
A background task looks for `(sync-conflict …)` copies that are byte-identical to the file they
|
||||
were copied from.
|
||||
|
||||
| Value | Behaviour |
|
||||
|---|---|
|
||||
| `off` | Do not run. |
|
||||
| `report` | Log and show what would be removed; remove nothing. **Default.** |
|
||||
| `enforce` | Move copies proven identical (same size and SHA-1) to the Trash. |
|
||||
|
||||
`PDFS_CONFLICT_SWEEP` overrides the setting for one run of the service.
|
||||
|
||||
### `open_with`
|
||||
|
||||
Decides how files picked in the search launcher or the app are opened. Rules are tried in order;
|
||||
the first match wins.
|
||||
|
||||
```json
|
||||
{
|
||||
"open_with": {
|
||||
"terminal": ["alacritty", "-e"],
|
||||
"default": ["xdg-open"],
|
||||
"rules": [
|
||||
{ "match": ["@text", "*.rs", "*.toml"], "command": ["nvim"], "terminal": true },
|
||||
{ "match": ["*.png", "*.jpg"], "command": ["imv"] },
|
||||
{ "match": ["@document"], "command": ["$EDITOR", "{}"], "terminal": true }
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- `match` takes file-name globs (`*.md`, `notes-*.txt`) or the classes `@dir`, `@text`,
|
||||
`@document`, `@image`, `@media` and `@any`. Patterns are matched against the name in Drive, not
|
||||
against the cached file, which is stored under a content hash.
|
||||
- `command` is an argument list, not a shell line. `{}` is replaced by the path; without it the
|
||||
path is appended. `$VAR` expands from the environment.
|
||||
- `"terminal": true` runs the command inside `terminal`. When `terminal` is unset, the client uses
|
||||
`$PDFS_TERMINAL`, then `$TERMINAL`, then the first known terminal on `PATH`, and adds that
|
||||
terminal's "run this command" flag for you.
|
||||
- `default` replaces `xdg-open` for files no rule matches.
|
||||
|
||||
### `prompt`
|
||||
|
||||
Settings for `pdfs-prompt`.
|
||||
|
||||
| Key | Default | Meaning |
|
||||
|---|---|---|
|
||||
| `mode` | `gtk` | Front end used without a flag: `gtk`, `dmenu` or `fzf` |
|
||||
| `menu` | first installed of fuzzel, rofi, wofi, tofi, bemenu, dmenu | Launcher for `dmenu` mode, as an argument list. `{prompt}` is replaced by the prompt text; without it, the launcher's own prompt flag is added |
|
||||
| `terminal` | first installed of foot, ghostty, kitty, alacritty, wezterm, xterm | Terminal for `fzf` mode. `{cmd}` is replaced by the command; without it, the command is appended |
|
||||
| `menu_limit` | `50` | Results shown in `dmenu` and `fzf` mode |
|
||||
| `menu_icons` | `true` | File-type icons in launchers that support them |
|
||||
|
||||
```json
|
||||
{
|
||||
"prompt": {
|
||||
"mode": "dmenu",
|
||||
"menu": ["fuzzel", "--dmenu", "--width", "60"],
|
||||
"terminal": ["foot", "--app-id=pdfs-prompt", "--"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Command-line flags win over the file: `--gtk`, `--dmenu`, `--fzf` and `--menu`.
|
||||
|
||||
## Environment variables
|
||||
|
||||
| Variable | Read by | Effect |
|
||||
|---|---|---|
|
||||
| `RUST_LOG` | all | Log filter, for example `RUST_LOG=debug` or `RUST_LOG=pdfs_fuse=debug,info`. Default `info` |
|
||||
| `PDFS_CONFLICT_SWEEP` | service | Overrides `conflict_sweep` (`off`, `report`, `enforce`) |
|
||||
| `PDFS_TERMINAL`, `TERMINAL` | app, prompt | Terminal for `open_with` rules with `"terminal": true` |
|
||||
| `LANGUAGE`, `LC_ALL`, `LC_MESSAGES`, `LANG` | app, tray, prompt | Interface language when `language` is unset |
|
||||
| `PDFS_LOCALEDIR` | app, tray, prompt | Load translations from another directory (development) |
|
||||
| `PDFS_STAND_IN_WIDGETS` | app | `1` uses the libadwaita 1.5 fallback widgets on newer systems (development) |
|
||||
|
||||
The acceptance suite has its own `PDFS_ACCEPTANCE_*` variables, listed in [TESTING.md](TESTING.md).
|
||||
|
||||
## The systemd service
|
||||
|
||||
`proton-drive.service` is a user unit. It restarts the service whenever it exits, restarts it when
|
||||
it stops answering for two minutes (`WatchdogSec=120`), and caps its memory at 6 GiB. To change
|
||||
the unit without editing the packaged file, use a drop-in:
|
||||
|
||||
```bash
|
||||
systemctl --user edit proton-drive.service
|
||||
```
|
||||
|
||||
```ini
|
||||
[Service]
|
||||
Environment=RUST_LOG=pdfs_fuse=debug,info
|
||||
Environment=PDFS_CONFLICT_SWEEP=off
|
||||
```
|
||||
|
||||
Logs go to the journal: `journalctl --user -u proton-drive.service -f`.
|
||||
+126
-176
@@ -1,214 +1,164 @@
|
||||
# Development and Verification Status for 1.0
|
||||
# Development guide
|
||||
|
||||
This document summarizes the work still pending after the 1.0.0 release branch and records the most important recently completed changes. [`BUGS.md`](BUGS.md) is the authoritative issue ledger; [`TESTING.md`](TESTING.md) defines the acceptance commands.
|
||||
How to build, run, debug and release the client from source. Read
|
||||
[CONTRIBUTING.md](../CONTRIBUTING.md) for the review rules and [ARCHITECTURE.md](ARCHITECTURE.md)
|
||||
for how the pieces fit together.
|
||||
|
||||
---
|
||||
- [Setup](#setup)
|
||||
- [Repository layout](#repository-layout)
|
||||
- [Running from source](#running-from-source)
|
||||
- [Quality gates](#quality-gates)
|
||||
- [Debugging](#debugging)
|
||||
- [Common changes](#common-changes)
|
||||
- [Releasing](#releasing)
|
||||
|
||||
## 1. Core Feature Roadmap (Horizon Tasks)
|
||||
Consolidated from the historical feature roadmap; current bug status lives in [`BUGS.md`](BUGS.md).
|
||||
## Setup
|
||||
|
||||
* **Local Cache & Metadata Encryption at Rest (Priority 5 / Horizon 1)**: Encrypt the SQLite database `cache.db` on disk using SQLCipher (`rusqlite` feature `bundled-sqlcipher`), and encrypt raw content cache blocks (`content/blocks/` and `content/scratch/`) using a fast symmetric scheme like AES-GCM or ChaCha20-Poly1305. The encryption key should be derived from the OS Keyring. (The SDK entity cache in `sdk_cache.db` is already encrypted at rest — see *Persistent SDK Entity Cache* below — but `cache.db` and the content cache are not.)
|
||||
* **Active Bandwidth Throttling & Traffic Shaping (Horizon 1)**: Add speed governors for daemon uploads and downloads. Support configuration variables `max_upload_rate_kbps` and `max_download_rate_kbps` in `config.json` that can be dynamically adjusted over the Unix control socket.
|
||||
* **Interactive & Policy-Based Conflict Resolution (Horizon 1)**: Implement configurable conflict resolution policies (`rename-local`, `rename-remote`, `prefer-local`, `prefer-remote`, `interactive`). Add a "Conflicts" tab to the GUI to notify the user, block sync, and launch external visual diff tools (like Meld or KDiff3).
|
||||
* **Multi-Account / Multi-Profile Support (Horizon 3)**: Enable running multiple profiles concurrently. Support separate configuration namespaces (e.g. `profiles/<profile_name>/`), independent SQLite databases, distinct mount paths (e.g. `~/ProtonDrive/Personal` and `~/ProtonDrive/Work`), and multiple daemon processes.
|
||||
* **Custom FUSE Mount Options (Horizon 1)**: Expose custom mounting parameters in configuration (e.g. `ro` for read-only, `direct_io` to bypass kernel caching, `allow_other`). Auto-generate systemd user mount units upon sync folder configuration.
|
||||
* **Symbolic Link & Hard Link Virtualization (Horizon 2)**: Add symbolic link virtualization inside the metadata store (`NodeType::Symlink`) by intercepting `readlink(2)` and `symlink(2)`. Targets should sync remotely as small encrypted metadata placeholder files on Drive (`proton-vfs-symlink: <target>`).
|
||||
* **Desktop File Manager Integration (Horizon 2)**: Develop shell extension plugins for popular Linux file managers (Nautilus Python plugin, Dolphin Service Menus, Thunar custom actions) to offer context-menu shortcuts ("Pin", "Unpin", "Copy Share Link", "View Version History") and file overlay sync badges.
|
||||
* **Integrated Photo Gallery Enhancements (Horizon 2)**: Album *editing* — rename, cover photo, delete, and removing photos from an album — is still unported in the SDK (TS `updateAlbum` / `deleteAlbum` / `removePhotos`), as is adding a photo that lives on someone else's volume (TS `copyPhoto`). Album **creation** and adding own-volume photos landed with the Google Photos import. Still open: an auto-upload Pictures folder pipeline, and a GUI for creating albums by hand. Exif display, the date-based timeline scrubber and favorites are implemented.
|
||||
* **Google Photos import follow-ups**: the importer uploads photos one at a time — a large export would finish sooner with a bounded concurrent upload pool. Trash folders are recognized by a hardcoded list of localized names ([`takeout.rs`](../crates/pdfs-core/src/takeout.rs) `TRASH_FOLDERS`); a locale not on it imports its trash as ordinary photos. Motion-photo `.MP`/`.MV` sidecar videos are ignored rather than uploaded as related photos. Live validation against a real export is pending.
|
||||
* **Random-Access Media Streaming seek support (Horizon 2)**: Intercept out-of-order sparse reads (player seeks) in `pdfs-fuse` and prioritize downloading blocks around the seek offset, aborting/postponing sequential pre-fetches.
|
||||
* **Dynamic Sync Dashboard & Queue Visualization (Horizon 2)**: GUI real-time transfer list (progress bars, speed, ETA), sync history feed, storage usage breakdown, and global pause/resume sync controls.
|
||||
* **Interactive Terminal UI (TUI) Mode (Horizon 3)**: Implement `pdfs tui` using the `ratatui` crate to show transfer speed, sync status, active transfer queue with progress bars, and scrolling daemon logs.
|
||||
* **Shutdown Safety & Write Queue Visibility (Horizon 1 / P4)**: Register systemd inhibitor locks in `pdfs-fuse` when there are outstanding staging writes to prevent shutdown or sleep, pop up warnings when exiting the GUI, and build a blocking `pdfs sync flush` command.
|
||||
* **Block-Level Deduplication (Horizon 3)**: Transition to a Content-Addressable block cache where cached blocks are stored on disk by their SHA-256 hash. Map logical ranges in the database: `(node_uid, block_idx) -> block_hash` to avoid storing or downloading identical blocks.
|
||||
* **Pre-emptive Sync Debouncing & File System Events (Horizon 3)**: Group filesystem write events on paths and delay sync queue insertion until a quiet period has elapsed (e.g. 5 seconds of inactivity) to prevent thrashing the Proton API.
|
||||
You need Rust 1.96 or newer and the native development packages listed under
|
||||
[Build dependencies](INSTALL.md#build-dependencies) for your distribution. Then:
|
||||
|
||||
---
|
||||
```bash
|
||||
git clone https://github.com/narrrl/proton-drive-linux.git
|
||||
cd proton-drive-linux
|
||||
cargo build --workspace
|
||||
```
|
||||
|
||||
## 2. Performance, Correctness & Robustness Items
|
||||
Consolidated from the performance and media-streaming audit notes.
|
||||
The GUI builds against libadwaita 1.5, the version in Ubuntu 24.04, and uses newer widgets at run
|
||||
time when the installed library has them (`crates/pdfs-gui/src/compat.rs`).
|
||||
|
||||
* **B6. Debounce the LRU access touch**: Keep last-touch times in memory and flush them in batches (debounce window of 30-60 seconds) to avoid performing a SQLite `UPDATE` to the `cache_entries` table on every cache hit.
|
||||
* **E12. Client in-flight cap shape**: Address the lock discrepancy between `MAX_CONCURRENT_BLOCK_DOWNLOADS = 10` (per-file) and `DEFAULT_MAX_INFLIGHT_BLOCKS = 12` (global client-wide). Either raise the global cap, lower the per-file window, or dynamically calculate the window to prevent single files from starving concurrent transfers.
|
||||
* **Pipeline `enumerate_nodes_detail` (P2.8 / 8)**: Introduce pipelined node enumeration to speed up directory listings.
|
||||
* **Local ancestor-chain walk (P3.4 / 4)**: Optimize recursive path lookups where full batching is impossible.
|
||||
* **Name Search for Photos/Videos**: Add search by photo/video name (deferred from Phase 3 gallery implementation).
|
||||
* **Sequential-Read Prefetch for Media Streaming**: Implement sequential read prefetch for media files to avoid stalls when buffering.
|
||||
* **Minor sweep items (Phase F)**:
|
||||
* **F1. `StreamRing.tags` Leak**: Clean up tag entries in `StreamRing.tags` when blocks are evicted. Currently, it only shrinks on `drop_node` (revision mismatch), leading to tag accumulation.
|
||||
* **F2. Non-saturating bytes subtraction**: Use `saturating_sub` in `lib.rs:382` (`self.bytes -= dropped.len()`) to prevent release mode panics/wrapping if accounting drifts.
|
||||
* **F3. Short block yields a short read / EOF**: Address the kernel EOF interpretation on short block reads. Either pad the block or fail loudly rather than silently serving short data.
|
||||
* **F4. `stream_readahead` check-then-spawn race**: Prevent duplicate concurrent readahead tasks for the same block. Check-then-spawn is currently racey.
|
||||
* **F5. `refresh_blocks` permit lock (SDK)**: Ensure URL refreshing (`refresh_blocks`) does not hold an in-flight block permit, preventing expired URLs from pinning client permits.
|
||||
* **F7. Document temporary cache file safety**: Add explanatory comment to `cache.rs:362` explaining why `with_extension("tmp")` is safe there but not in `store_thumbnail`.
|
||||
## Repository layout
|
||||
|
||||
---
|
||||
| Path | Contents |
|
||||
|---|---|
|
||||
| `crates/pdfs-core` | Shared library: authentication and keyring (`auth`), configuration (`config`), SQLite schema and queries (`db/`), content cache (`cache`), control protocol (`control`), search scoring, sync ignore rules, Google Takeout parsing, machine profile |
|
||||
| `crates/pdfs-fuse` | The daemon: FUSE filesystem, read path (`reads`), write queue (`queue`, `drain`, `upload`), sync engine (`sync/`), remote events (`background`), push events for front ends (`events`), control handlers (`control`), photos, devices, supervisor |
|
||||
| `crates/pdfs-cli` | The `pdfs` binary |
|
||||
| `crates/pdfs-gui` | `pdfs-app`, `pdfs-tray` and `pdfs-prompt`. Pages in `src/app/pages/`, shared widgets in `src/app/widgets/`, CSS and icons in `resources/` |
|
||||
| `po/` | Translation template, catalogs and the scripts that maintain them |
|
||||
| `packaging/` | systemd unit, desktop files, icon, PKGBUILD, RPM spec, AUR recipes |
|
||||
| `scripts/` | FUSE acceptance suite, map-data generators |
|
||||
| `docs/` | This documentation |
|
||||
|
||||
## 3. Open & Unverified Bugs
|
||||
Derived from: [`BUGS.md`](BUGS.md)
|
||||
The GUI talks to the daemon only through the control socket. Anything a front end needs that the
|
||||
daemon does not offer yet is a new request in `pdfs_core::control`, not a database read.
|
||||
|
||||
* **B2. Unattributed Trash Origin**: Investigate why deleted/moved files are occasionally sent to trash instead of vanishing on older rename operations.
|
||||
* **B10. GLib Critical Warning on HUD Close**: Assertion failure `g_list_store_remove: assertion '!g_sequence_iter_is_end (it)' failed` when prompt window closes during active launch (`xdg-open`). Needs investigation under `G_DEBUG=fatal-criticals`.
|
||||
* **B15. Empty-but-listed folders and duplicate UIDs**: Investigate folder-identity issues (e.g. duplicate remote folders like `Music` with different UIDs) and how folders obtain `listed = 1` in the database without matching child rows.
|
||||
* **B8 (CAPTCHA sign-in bridge)**: Verify a real gated sign-in using Webkit CAPTCHA completion.
|
||||
* **Draft Revision Upload loop**: Verify SDK-side deletion and retry logic when a conflicting draft revision exists under the same client UID.
|
||||
* **Optimistic Size Loss on Restart**: Verify that pending uploads retain their optimistic sizes across a daemon restart.
|
||||
* **B48 — stale listing after unlink**: Session tombstones and authoritative empty listings are implemented; run focused live verification against eventually consistent remote enumeration.
|
||||
* **B49–B55 — data-safety fixes**: Conflict preservation, orphan/staging durability, transactional supersession, one-entry wipe protection, and incomplete-scan handling have regression coverage but still require the fault, power-loss, and live mode-matrix cases recorded in `BUGS.md`.
|
||||
* **B56–B60 — fail-closed state and IPC fixes**: Future schemas, event cursor advancement, socket limits, private-directory validation, and atomic config saves are implemented. Malformed-schema, database-full, connection-flood, wrong-owner, and concurrent/faulted-save verification remains.
|
||||
* **B61 — credential rotation persistence**: Surface and retry keyring persistence failures so a rotated single-use refresh token cannot be lost on restart.
|
||||
* **B62–B65 — release assurance**: Clean-install package verification, complete version/protocol identity, recovery sign-off, advisory/license policy, SBOM, provenance, checksums, and signatures remain.
|
||||
* **B66–B67 — lifecycle and recovery**: Add queue flush/shutdown protection and explicit device adoption during fresh-state restore.
|
||||
* **B68/B78 — profile backup**: the destination is fixed and verified live — `profile.json` now lives in `.proton-drive-linux/` under the device root, since the API refuses file creation at the root itself. What remains from B68 is making backup *health* visible (today a failure is a `WARN` in the log and nothing in the UI) and re-running the replacement-machine restore end to end.
|
||||
* **B79 — cross-mount permission classification**: fixed and verified live; the standing guard is the `regression B79` acceptance case. The second-account cases it neighbours (`regression B34`) still cannot run — see below.
|
||||
## Running from source
|
||||
|
||||
---
|
||||
The packaged service and a daemon run from source cannot share the same state directory. Stop the
|
||||
service before you run your own build:
|
||||
|
||||
## 4. Testing, Verification & Disaster Recovery Drills
|
||||
Derived from: [`TESTING.md`](TESTING.md) and [`RECOVERY.md`](RECOVERY.md)
|
||||
```bash
|
||||
systemctl --user stop proton-drive.service
|
||||
RUST_LOG=pdfs_fuse=debug,info cargo run -p pdfs-cli -- daemon
|
||||
```
|
||||
|
||||
* **IPC Memory and Performance Stress Tests (Phase 3)**: Verify memory allocations do not balloon when sending large `UploadPhoto` JSON payloads. Test control socket timeout behaviors under long-running block operations.
|
||||
* **Fault Injection and Resiliency Tests (Phase 4)**:
|
||||
* **Network degradation**: Verify that interrupted uploads leave readable staging buffers and result in clean backoff retries.
|
||||
* **Disk full (ENOSPC)**: Verify that write staging and gap-filling report correct errors to FUSE and preserve staged work.
|
||||
* **Concurrent reader starvation**: Test that parallel sequential reads do not freeze directory lookups or metadata handlers.
|
||||
* **Disaster Recovery Drill (P5 / Phase 5)**: Execute a complete manual disaster recovery test:
|
||||
1. Register a device.
|
||||
2. Sync a folder and upload data.
|
||||
3. Wipe the local state directory and SQLite cache.
|
||||
4. Restart the daemon.
|
||||
5. Run `pdfs sync restore` and assert the recovered filesystem matches the source byte-for-byte.
|
||||
* **Second-account sharing run (mount-architecture.md P7)**: The only outstanding verification for the mount/sharing work. One account covers `context_share_id`, the shared-with-me listing, sharing from device folders and the Locations page — all confirmed. A **second account** is required for the shared-tree rendering under a foreign volume, `accept_invitation`, `update_member_role`, the `regression B34` viewer cases (which skip cleanly today), and above all an **editor-role write into a foreign share**, the only thing that validates `membership_address_for`.
|
||||
* **Managed live mode matrix**: Before release, run `scripts/fuse-acceptance.sh --managed-live <empty-a> <empty-b>` with `PDFS_ACCEPTANCE_ONLY` unset. It validates on-demand/on-demand, on-demand/mirror, mirror/on-demand, and mirror/mirror transitions.
|
||||
* **Crash-consistency matrix**: Inject failure after scratch/sidecar sync, each staging rename, directory sync, pending-op insert/commit, and source deletion; prove that a complete discoverable copy and either the old or new queue record always survives.
|
||||
In another terminal:
|
||||
|
||||
---
|
||||
```bash
|
||||
cargo run -p pdfs-cli -- status
|
||||
po/build.sh target/locale # compile translations once
|
||||
PDFS_LOCALEDIR=target/locale cargo run -p pdfs-gui --bin pdfs-app
|
||||
cargo run -p pdfs-gui --bin pdfs-tray
|
||||
cargo run -p pdfs-gui --bin pdfs-prompt -- --fzf
|
||||
```
|
||||
|
||||
## 5. Fixed & Resolved Bugs
|
||||
Derived from: [`BUGS.md`](BUGS.md)
|
||||
To keep the systemd unit but point it at your build, see
|
||||
[INSTALL.md](INSTALL.md#using-a-binary-outside-usrbin).
|
||||
|
||||
### Completely Fixed & Verified
|
||||
* **B1 — FUSE rename loses the file (data loss)**: In `rename`, the node's database row was deleted while only updating the in-memory state, causing the file to vanish on next listing sync. Fixed by correctly calling `st.invalidate_listing(newparent)` to refresh SQLite cache states.
|
||||
* **B4 — `invalidate_listing` silently skipped non-resident folders**: Folders not loaded in memory were being skipped during listing invalidation, leaving stale cache flags in the DB. Fixed by removing the residency check guard.
|
||||
* **B5 — `ls -l` costs a network round trip per file (thumbnail xattr probes)**: File listings triggered blocking network checks for thumbnails on unsupported files. Fixed by caching negative thumbnail results and restricting xattr advertisement to supported image/media files.
|
||||
* **B6 — Daemon sets no file modes: `control.sock` is an unguarded authority**: The Unix control socket was created without restricting file permissions, exposing daemon controls to other local users. Fixed by applying proper creation permission masks.
|
||||
* **B7 — renamed directory reads as missing until the entry TTL expires**: Kernel cache maps remained stale after a FUSE directory re-anchor. Fixed by proactively sending entry invalidation notifications to the kernel.
|
||||
* **B9 — Enter did not open the selected result in the launcher**: Hooked up keyboard execution (Enter key) in `pdfs-prompt` search HUD to launch the selected item using `xdg-open`.
|
||||
* **B11 — a file moved while its create is still queued reads as empty**: Reconciling a local rename on a file that had not finished uploading yet uploaded empty blocks. Fixed by carrying over and staging the correct logical file size.
|
||||
* **B12 — cold enumeration is slow per entry, and goes superlinear past ~500**: S2K decryption and thumbnail resolution loops were serial. Fixed by parallelizing key derivations and caching metadata.
|
||||
* **B13 — `rename` over an existing destination fails instead of replacing it**: Fixed POSIX rename target overwrite behavior to replace existing destinations.
|
||||
* **B14 — provisional (ciphertext) sizes make rsync read short and abort the file**: Adjusted size reporting to align logical and ciphertext sizing, preventing premature EOF.
|
||||
* **B45 — truncate over a queued rewrite**: Path-based and handle-based truncate now compose over the complete pending blob; shrink, growth, and sparse I/O are live-verified.
|
||||
* **B46 — combined cross-directory move and rename**: The desired end state is durably queued and reconciles partially completed remote operations; replacement and combined cases are live-verified.
|
||||
* **B47 — overlong/invalid names**: All name-taking callbacks share a validator for `NAME_MAX`, reserved components, and UTF-8; managed-live verification passed.
|
||||
> [!CAUTION]
|
||||
> Develop against a test account. The acceptance suite and a buggy daemon can delete or rewrite
|
||||
> files in Proton Drive.
|
||||
|
||||
### Implemented in 1.0 (Further Fault Verification Pending)
|
||||
> [!TIP]
|
||||
> A daemon stopped in a debugger or deadlocked freezes every process that touches the mount,
|
||||
> including your shell if its prompt reads the current directory. Keep your shell outside
|
||||
> `~/ProtonDrive`, prefix commands that touch it with `timeout`, and unmount a dead mount with
|
||||
> `fusermount3 -uz ~/ProtonDrive`.
|
||||
|
||||
* **Unified search and resident prompt**: `SearchV2` combines Drive and local lookup with shared relevance scoring and content/source filters. The prompt reuses its window and opens streamable media through FUSE.
|
||||
* **Durable write publication**: Scratch sidecars and staged blobs use synced temporary files, atomic renames, and directory synchronization; orphan rescue retains its source on failure.
|
||||
* **Transactional pending operations**: Superseding a queued operation cannot delete the old durable record unless the replacement commits.
|
||||
* **Safer mirror reconciliation**: Conflict-copy failure aborts publication, incomplete scans are non-destructive, and total-wipe protection includes one-entry baselines.
|
||||
* **Bounded IPC**: Control requests are limited to 1 MiB and 10 seconds, with at most 64 active handlers.
|
||||
* **Private local state**: Sensitive directories require correct ownership, real-directory identity, and `0700`; sockets use `0600`; config saves are atomic and malformed input is preserved.
|
||||
* **Release gates**: Tag/workspace/package versions are checked and formatting, lint, tests, and offline FUSE acceptance run before packaging.
|
||||
## Quality gates
|
||||
|
||||
### Code Fixed / Implemented (Pending Verification)
|
||||
* **B8 — no way to complete a CAPTCHA, so a gated sign-in is unrecoverable**: Implemented a Webkit-based bridge to prompt the user to resolve interactive CAPTCHAs during gated logins. (Needs verification on a real gate request).
|
||||
CI (`.github/workflows/ci.yml`) runs these on every push to `main` and every pull request. Run them before you
|
||||
push:
|
||||
|
||||
### Closed / Not a Bug
|
||||
* **B3 — Activity log timestamps written in seconds, read as milliseconds**: Closed as investigator error (timestamps are consistent).
|
||||
```bash
|
||||
cargo fmt --all -- --check
|
||||
cargo clippy --workspace --all-targets -- -D warnings
|
||||
cargo test --workspace --locked
|
||||
scripts/fuse-acceptance.sh --offline-only
|
||||
```
|
||||
|
||||
---
|
||||
For changes to the FUSE layer, the write queue or the sync engine, also run the live acceptance
|
||||
cases described in [TESTING.md](TESTING.md).
|
||||
|
||||
## 6. Recently Implemented Features
|
||||
For changes to GUI strings, check that every catalog is complete:
|
||||
|
||||
### File Version History (Implemented)
|
||||
**Files**: [`revisions.rs`](../crates/pdfs-fuse/src/revisions.rs), [`control.rs`](../crates/pdfs-core/src/control.rs), [`versions_dialog.rs`](../crates/pdfs-gui/src/app/widgets/versions_dialog.rs)
|
||||
```bash
|
||||
for l in $(cat po/LINGUAS); do msgfmt --check --statistics -o /dev/null po/$l.po; done
|
||||
```
|
||||
|
||||
Proton Drive keeps every revision a client committed; the daemon only ever addressed the active one, so a file overwritten by a sync pass could be recovered only from whatever the local `recovery/` directory happened to hold.
|
||||
## Debugging
|
||||
|
||||
The control protocol gained `ListRevisions` / `RestoreRevision` / `DeleteRevision` / `SaveRevisionAs` (each with a `…ByUid` twin for nodes the primary mount cannot name), the CLI gained `pdfs versions list|restore|save|rm`, and the browser's details pane gained a **Versions** button opening a per-file dialog.
|
||||
| Tool | Use |
|
||||
|---|---|
|
||||
| `RUST_LOG` | Log filter for every binary, for example `RUST_LOG=pdfs_fuse::sync=trace,info` |
|
||||
| `pdfs diagnose` | Static checks: directories, FUSE, keyring, socket, database integrity. Works without the daemon |
|
||||
| `pdfs diagnostics` | Live state of a running daemon: each worker's current job and its age, queue depth, control requests in flight, memory |
|
||||
| `pdfs cache inspect --deep` | Database size, row counts and SQLite `integrity_check` |
|
||||
| `pdfs --json …` | Raw protocol payloads for query commands |
|
||||
| `GTK_DEBUG=interactive` | The GTK inspector for `pdfs-app` |
|
||||
| `PDFS_STAND_IN_WIDGETS=1` | Force the libadwaita 1.5 fallback widgets on a newer system |
|
||||
| `G_DEBUG=fatal-criticals` | Turn GLib criticals into crashes to get a backtrace |
|
||||
|
||||
Three properties that shape the code:
|
||||
The databases are ordinary SQLite files. Open a copy, not the live file:
|
||||
|
||||
- **A restore is server-side and asynchronous.** No content crosses the wire and nothing enters the drain queue; the server answers 202 and swaps the active revision in the background, so the daemon evicts the file's cached blocks and open readers rather than describing the new state, and the UI wording promises the request, not the result.
|
||||
- **The active revision cannot be deleted.** `Core::delete_revision_for_uid` checks that locally so the user gets a sentence rather than an API code, and the dialog gives the current row no delete button.
|
||||
- **Saving a version never overwrites.** `SaveRevisionAs` refuses an existing destination and removes a partial file if the download fails — a half-written export looks identical to a good one to every tool that opens it afterwards.
|
||||
```bash
|
||||
cp ~/.local/state/proton-drive-linux/cache.db /tmp/cache.db
|
||||
sqlite3 /tmp/cache.db '.tables'
|
||||
```
|
||||
|
||||
### Photo Favorites (Implemented)
|
||||
**Files**: [`photos.rs`](../crates/pdfs-fuse/src/photos.rs), [`photo_viewer.rs`](../crates/pdfs-gui/src/app/pages/photo_viewer.rs)
|
||||
## Common changes
|
||||
|
||||
The gallery can mark and filter favorites, through the SDK's photo-tag API (`update_photos`). Schema **v20** adds `photos.favorite`; the flag is learned in the timeline enrichment pass that already resolves each photo's name and media type, and is kept across a refresh that could not resolve a photo — the same learned-and-kept rule as `media_type`. The lightbox carries a star toggle, the Photos header a favorites filter, and the CLI has `pdfs favorite <uid> [--remove]` plus `pdfs photos --favorites`.
|
||||
**A new control request.** Add the variant to `Request` (and a `Response` if it returns data) in
|
||||
`crates/pdfs-core/src/control.rs`, handle it in `crates/pdfs-fuse/src/control.rs`, and list the
|
||||
`Topic`s it changes in the same file so subscribed front ends refresh. A daemon from the previous
|
||||
release may still be running when a new front end starts, so treat an error reply to a new
|
||||
request as "not supported".
|
||||
|
||||
Favouriting a photo that is not on this account's own photos volume (shared with us, or album-only) needs it re-encrypted for our timeline root, which the SDK does not implement; the daemon surfaces that as an error rather than silently doing nothing.
|
||||
**A schema change.** Migrations are forward-only. Add a new step to
|
||||
`crates/pdfs-core/src/db/migrations.rs` and bump `SCHEMA_VERSION`; never edit a shipped step. Add
|
||||
a test in `crates/pdfs-core/src/db/tests.rs` that migrates from the previous version.
|
||||
|
||||
### Justified Gallery, Gallery Delete (Implemented)
|
||||
**Files**: [`photos.rs`](../crates/pdfs-gui/src/app/pages/photos.rs), [`photo_viewer.rs`](../crates/pdfs-gui/src/app/pages/photo_viewer.rs), [`photos.rs`](../crates/pdfs-fuse/src/photos.rs), [`background.rs`](../crates/pdfs-fuse/src/background.rs)
|
||||
**A GUI string.** Wrap it in the helpers from `crates/pdfs-gui/src/i18n.rs`, add any new source
|
||||
file to `po/POTFILES.in`, run `po/update.sh`, and translate the new entries in every catalog. See
|
||||
[TRANSLATING.md](TRANSLATING.md). The CLI and daemon messages stay in English.
|
||||
|
||||
The gallery lays each day out in justified rows (`justify_rows` / `plan_rows` / `fit_row`): photos are taken in capture order until their summed aspect ratio no longer fits the target row height, and the row is then scaled so it ends exactly on the content width. A tile is therefore its own photo's shape, and `ContentFit::Contain` has nothing left to crop. The last row of a day is left at the target height rather than stretched, because a day holding two photos is a short day, not a layout fault.
|
||||
**A setting.** Add the field to `AppConfig` in `crates/pdfs-core/src/config.rs` with
|
||||
`#[serde(default)]`, so older files still load, and document it in
|
||||
[CONFIGURATION.md](CONFIGURATION.md).
|
||||
|
||||
- **Ratios that are not known yet.** `PhotoItem::ratio` is persisted, but a photo that has never been decoded has none. Those are laid out square and remembered in `assumed_ratios`; when a decode proves the real shape the day re-flows on the existing debounce timer, so a screenful of decodes costs one re-flow rather than one per photo. Ratios are clamped to 0.4–3.0 so a single panorama cannot decide what a row looks like.
|
||||
- **Thumbnails survive recycling.** A reply for a tile that has already been re-bound still lands in the texture cache, which is an LRU of 1500 textures keyed by uid, and the rows just outside the realised range are prefetched in the scroll direction.
|
||||
- **Delete is uid-addressed.** The photos volume is not in the FUSE mount, so the path-based `Request::Delete` cannot reach it. `Request::TrashNodes { uids }` trashes through the SDK and answers `Response::Trashed { trashed, failed }`; the daemon then drops those rows with `Db::photos_delete` (album membership included) so the gallery does not wait for a timeline refresh. The GUI removes the tiles optimistically with an Undo toast and puts back anything the server refused.
|
||||
- **Remote deletions arrive on their own.** The Drive volume and the photos volume have separate event streams, so `run_photos_event_sync` polls the photos volume with its own cursor (`photos_event_cursor` in the state table). Trash and delete events remove rows; anything else only invalidates freshness, because there is no inode space to converge on this volume. Together with a 60 s `TIMELINE_TTL` and a `RefreshScope::Photos` that now awaits the refresh, a photo deleted on a phone leaves the grid in about ten seconds.
|
||||
## Releasing
|
||||
|
||||
### RAW + JPEG Grouping (Implemented)
|
||||
**Files**: [`photos.rs`](../crates/pdfs-core/src/db/photos.rs), [`migrations.rs`](../crates/pdfs-core/src/db/migrations.rs), [`photos.rs`](../crates/pdfs-fuse/src/photos.rs), [`photo_viewer.rs`](../crates/pdfs-gui/src/app/pages/photo_viewer.rs)
|
||||
Releases are cut from `main` by pushing a `v*` tag. `.github/workflows/release.yml` then:
|
||||
|
||||
Schema **v30** adds `content_hash`, `main_uid` and an indexed `group_key` to `photos`. The first two come from the server's `PhotoProperties` and are filled by the enrichment pass in `refresh_timeline` that already resolves each photo's name, media type and favorite tag; `group_key` is computed in `photos_replace`, where the whole timeline is in hand.
|
||||
1. checks that the tag, the workspace version in `Cargo.toml` and `pkgver` in
|
||||
`packaging/PKGBUILD` agree;
|
||||
2. runs the quality gates;
|
||||
3. builds the release binaries and packages a `.tar.gz`, a `.deb` and a GPG-signed `.rpm`;
|
||||
4. publishes them as a GitHub release;
|
||||
5. calls `.github/workflows/aur.yml`, which updates and pushes the AUR recipes and commits them
|
||||
back to `main`.
|
||||
|
||||
- **Precedence.** The server relation first (`main_photo_uid` and `related_photo_uids`, read from whichever end resolves — the two can land in different enrichment chunks); then same capture day, same case-insensitive name stem, and one member raw while the other is not; otherwise the photo is its own group. The union-find pass is over the timeline in memory, so it costs one pass per refresh rather than a query per photo.
|
||||
- **Representative.** The non-raw member when there is one — a JPEG decodes in milliseconds and is what the person expects to see. `group_key` holds that member's uid, so "is this the tile" is `uid = group_key`, an index scan.
|
||||
- **What is grouped and what is not.** `photos_page`, `photos_months` and `photos_counts` count groups, except on the Raw tab, which lists files. Album pages are never grouped: an album is a list someone made. The relation is learned-and-kept like `media_type`, so a refresh that could not resolve a node does not break a group up.
|
||||
- **Deleting.** `Core::trash_photos` expands each uid to its group before trashing, because the grid shows the shot as one tile — leaving the RAW behind would put the photo back on the Raw tab and nowhere else. The GUI's confirmation names the file count.
|
||||
- **The other files.** `Request::PhotoGroup { uid }` answers with the group's members as ordinary `PhotoItem`s, which is what the lightbox's switch steps through.
|
||||
To prepare a release:
|
||||
|
||||
### Persistent SDK Entity Cache (Implemented)
|
||||
**Files**: [`sdkcache.rs`](../crates/pdfs-core/src/sdkcache.rs), [`auth.rs`](../crates/pdfs-core/src/auth.rs), [`background.rs`](../crates/pdfs-fuse/src/background.rs)
|
||||
```bash
|
||||
# 1. Bump the version in Cargo.toml and packaging/PKGBUILD, then refresh the lock file.
|
||||
cargo update --workspace
|
||||
# 2. Move the [Unreleased] notes in docs/CHANGELOG.md under the new version.
|
||||
# 3. Commit, tag and push.
|
||||
git commit -am "chore(release): X.Y.Z"
|
||||
git tag vX.Y.Z
|
||||
git push origin main vX.Y.Z
|
||||
```
|
||||
|
||||
The SDK's Drive entity cache (decrypted node metadata: name, size, parent, signing share) defaulted to memory, so every daemon restart re-fetched and re-decrypted the tree the previous run had already walked. It is now backed by SQLite.
|
||||
|
||||
- **Its own file** (`sdk_cache.db` in the state directory), not `cache.db`: the daemon's `Db` is one `Mutex<Connection>` shared by every FUSE thread and the control socket, and this traffic is frequent, small and entirely reconstructible. A separate file also means no schema migration — the store can be deleted at any time.
|
||||
- **Encrypted at rest** by wrapping it in the SDK's `EncryptedCacheRepository`, keyed by the mailbox password. A password change reads as a cold cache (the SDK treats an undecryptable entry as a miss and clears the store), not as an error.
|
||||
- **Staleness** is closed by the event loop, which already replays from a persisted cursor and calls `invalidate_caches_for_event` for every event — including those raised while the daemon was down. The one case with no trail is a *seeded* cursor (first-ever mount, or a lost cursor), where the seed path now clears the store instead of trusting it. `auth::logout` removes the file.
|
||||
|
||||
Needed a small additive SDK change (`ProtonDriveClient::with_entity_repository`, 0.5.1): `with_entity_cache` is a constructor and so could not be combined with `with_key_salts`, which the daemon requires.
|
||||
|
||||
### Per-node Batch Outcomes (Implemented)
|
||||
**File**: [`batch.rs`](../crates/pdfs-core/src/batch.rs)
|
||||
|
||||
SDK 0.5.0 made `trash_nodes` / `restore_nodes` / `delete_nodes` report one outcome per node instead of failing the whole call (mirroring upstream's streamed `NodeActionResult`). `pdfs_core::batch::into_unit` collapses the single-node calls back to a `Result`; `batch::split` handles a collected batch.
|
||||
|
||||
A restore is expanded before it is sent (`expand_restore`, `pdfs-fuse/src/lib.rs`): the persisted trash listing carries each row's `parent_uid` (schema 29), so a restore takes the connected piece of the trashed tree — every trashed descendant of what was asked for, and every trashed ancestor above it — and sends it shallowest wave first, because the server cannot put a node back under a parent that is still trashed. A uid the listing does not know about (it is materialised in chunks, and can be stale) is restored on its own rather than dropped.
|
||||
|
||||
The trash view's restore and permanent-delete use the SDK's **streaming** variants (`restore_nodes_streaming` / `delete_nodes_streaming`) and apply local state per node as each batch lands rather than after the last one. For a permanent delete — which is irreversible — that means a daemon interrupted mid-batch has forgotten exactly the nodes the server destroyed, no more and no fewer. Both report per-node failures and count only what actually succeeded; only a batch where nothing succeeded is an error.
|
||||
|
||||
|
||||
### Open-for-Write Deferral for Mirror Sync (Implemented)
|
||||
**File**: [`sync.rs`](../crates/pdfs-fuse/src/sync.rs)
|
||||
|
||||
The mirror folder sync engine now defers uploading any file that is currently held open for writing by another process, matching the guarantee the FUSE mount path already provides (where uploads are deferred until `close(fd)`).
|
||||
|
||||
**Problem**: Previously, the mirror sync path relied solely on a 2-second trailing-edge debounce (with a 30-second ceiling) to avoid uploading files mid-write. This was insufficient for slow continuous writers (e.g., database dumps, large exports, or editors that keep files open for extended periods), which could have their incomplete state uploaded as a real revision.
|
||||
|
||||
**Solution**: Before each reconcile pass, the sync engine scans `/proc/*/fd` once to build a set of canonical paths within the sync root that any process holds open for writing (`O_WRONLY` or `O_RDWR`). Files in this set are:
|
||||
|
||||
- **Kept in the local walk** — so they are not misclassified as deletions
|
||||
- **Treated as unchanged** — so no upload is queued for them
|
||||
- **Counted as `deferred`** — so the activity summary reports them (e.g., "3 uploaded, 1 deferred (open for write)")
|
||||
- **Picked up on the next pass** — after the writer has closed the file
|
||||
|
||||
**How it works**:
|
||||
1. `open_for_write_set(root)` reads `/proc/*/fd` → `readlink` for each fd → prefix-checks against the sync root → reads `/proc/<pid>/fdinfo/<n>` to check the `flags:` line's low two bits (O_ACCMODE)
|
||||
2. `walk_local` sets `LocalItem.open_for_write = true` for matching files
|
||||
3. Both `do_reconcile` and `push_pass` skip upload classification for flagged files
|
||||
4. `Outcome.deferred` tracks the count for the activity summary
|
||||
|
||||
**Performance**: The `/proc` scan completes in low single-digit milliseconds on a typical desktop. Only fds whose `readlink` target falls under the sync root incur the `fdinfo` read.
|
||||
|
||||
**Tests added**: 8 unit tests covering `is_write_mode` parsing of various fdinfo flag combinations, and `Outcome` summary formatting with deferred counts.
|
||||
|
||||
| Sync Path | Open-for-write protection | Mechanism |
|
||||
|---|---|---|
|
||||
| FUSE mount | ✅ Perfect | Upload deferred until `close(fd)` |
|
||||
| Mirror folders | ✅ Perfect | `/proc/*/fd` scan per reconcile pass |
|
||||
Before a release that touches the filesystem or sync, run the managed live mode matrix from
|
||||
[TESTING.md](TESTING.md). Open release-assurance items are listed in [ROADMAP.md](ROADMAP.md).
|
||||
+243
@@ -0,0 +1,243 @@
|
||||
# Installation
|
||||
|
||||
This page covers installing Proton Drive for Linux from a package or from source, the first
|
||||
sign-in, running without a desktop, and removing the client again.
|
||||
|
||||
- [Requirements](#requirements)
|
||||
- [Install a package](#install-a-package)
|
||||
- [Build from source](#build-from-source)
|
||||
- [First run](#first-run)
|
||||
- [Headless and server use](#headless-and-server-use)
|
||||
- [Updating](#updating)
|
||||
- [Uninstalling](#uninstalling)
|
||||
|
||||
## Requirements
|
||||
|
||||
| | Minimum |
|
||||
|---|---|
|
||||
| Architecture | x86_64 (release packages); other architectures build from source |
|
||||
| Kernel | FUSE 3 (`fuse3` package, `/dev/fuse` available to your user) |
|
||||
| GTK / libadwaita | GTK 4.12, libadwaita 1.5 (1.8 or newer gets the newest widgets) |
|
||||
| WebKitGTK | 6.0 — used only for the CAPTCHA page during sign-in |
|
||||
| Secret Service | GNOME Keyring, KWallet, KeePassXC, or another provider of `org.freedesktop.secrets` |
|
||||
| Rust (source builds) | 1.96 |
|
||||
|
||||
The session is stored only in the Secret Service. Without a running provider, sign-in succeeds but
|
||||
cannot be saved, and the service cannot start unattended.
|
||||
|
||||
Optional runtime extras:
|
||||
|
||||
| Package | Adds |
|
||||
|---|---|
|
||||
| `exiftool` (`perl-image-exiftool`, `libimage-exiftool-perl`) | Thumbnails for camera RAW files |
|
||||
| `ffmpeg` | Video thumbnails |
|
||||
| `iso-codes` | Country names in your language on the Places map |
|
||||
| `xdg-utils` | "Open Folder" in the tray, and the default file opener |
|
||||
| `fzf` plus a terminal (foot, kitty, alacritty, …) | `pdfs-prompt --fzf`, the search-as-you-type launcher |
|
||||
| AppIndicator extension (GNOME only) | The tray icon. KDE Plasma and most other desktops show it natively |
|
||||
|
||||
## Install a package
|
||||
|
||||
Every [release](https://github.com/narrrl/proton-drive-linux/releases/latest) ships a `.deb`, a
|
||||
signed `.rpm` and a `.tar.gz` of the raw binaries. All packages install the same files:
|
||||
|
||||
| Path | Purpose |
|
||||
|---|---|
|
||||
| `/usr/bin/pdfs` | Command-line client and background service |
|
||||
| `/usr/bin/pdfs-app` | Desktop app |
|
||||
| `/usr/bin/pdfs-tray` | Tray icon |
|
||||
| `/usr/bin/pdfs-prompt` | Search launcher |
|
||||
| `/usr/lib/systemd/user/proton-drive.service` | User service that keeps the drive mounted |
|
||||
| `/etc/xdg/autostart/io.narl.proton-drive-linux-tray.desktop` | Starts the tray at login |
|
||||
| `/usr/share/locale/*/LC_MESSAGES/pdfs.mo` | Translations |
|
||||
|
||||
### Debian and Ubuntu (24.04 or newer)
|
||||
|
||||
```bash
|
||||
sudo apt install ./proton-drive-linux_*_amd64.deb
|
||||
```
|
||||
|
||||
### Fedora (44 or newer)
|
||||
|
||||
```bash
|
||||
sudo dnf install ./proton-drive-linux-*.x86_64.rpm
|
||||
```
|
||||
|
||||
For a Fedora package built from your own checkout, see
|
||||
[Build an RPM locally](#build-an-rpm-locally).
|
||||
|
||||
### Arch Linux (AUR)
|
||||
|
||||
Three packages cover the usual choices. They conflict with each other, so install one:
|
||||
|
||||
| Package | Contents |
|
||||
|---|---|
|
||||
| [`proton-drive-for-linux`](https://aur.archlinux.org/packages/proton-drive-for-linux) | Latest tagged release, built from source |
|
||||
| [`proton-drive-for-linux-bin`](https://aur.archlinux.org/packages/proton-drive-for-linux-bin) | Latest tagged release, prebuilt binaries |
|
||||
| [`proton-drive-for-linux-git`](https://aur.archlinux.org/packages/proton-drive-for-linux-git) | `main`, built from git |
|
||||
|
||||
```bash
|
||||
paru -S proton-drive-for-linux # or yay, or any other AUR helper
|
||||
```
|
||||
|
||||
The recipes live in [`packaging/aur/`](../packaging/aur/README.md).
|
||||
|
||||
### Other distributions
|
||||
|
||||
Unpack the `.tar.gz` into a directory on your `PATH`, then install the service unit as shown in
|
||||
[Using a binary outside `/usr/bin`](#using-a-binary-outside-usrbin).
|
||||
|
||||
## Build from source
|
||||
|
||||
### Build dependencies
|
||||
|
||||
**Debian / Ubuntu 24.04+**
|
||||
|
||||
```bash
|
||||
sudo apt-get install -y pkg-config gettext libfuse3-dev libgtk-4-dev libadwaita-1-dev \
|
||||
libwebkitgtk-6.0-dev libsecret-1-dev libdbus-1-dev
|
||||
```
|
||||
|
||||
**Fedora 44+**
|
||||
|
||||
```bash
|
||||
sudo dnf install -y cargo rust gettext pkgconf-pkg-config fuse3-devel gtk4-devel \
|
||||
libadwaita-devel webkitgtk6.0-devel libsecret-devel dbus-devel glib2-devel
|
||||
```
|
||||
|
||||
**Arch Linux**
|
||||
|
||||
```bash
|
||||
sudo pacman -S --needed rust gettext pkgconf fuse3 gtk4 libadwaita webkitgtk-6.0 libsecret dbus
|
||||
```
|
||||
|
||||
Install Rust 1.96 or newer with [rustup](https://rustup.rs) if your distribution ships an older
|
||||
toolchain.
|
||||
|
||||
### Compile
|
||||
|
||||
```bash
|
||||
git clone https://github.com/narrrl/proton-drive-linux.git
|
||||
cd proton-drive-linux
|
||||
cargo build --release --locked
|
||||
po/build.sh target/locale # optional: compile the translations
|
||||
```
|
||||
|
||||
The four binaries are in `target/release/`: `pdfs`, `pdfs-app`, `pdfs-tray` and `pdfs-prompt`.
|
||||
|
||||
### Build a package from the working tree
|
||||
|
||||
**Arch Linux:**
|
||||
|
||||
```bash
|
||||
cd packaging && makepkg -fi
|
||||
```
|
||||
|
||||
<a id="build-an-rpm-locally"></a>**Fedora:**
|
||||
|
||||
```bash
|
||||
sudo dnf install -y rpm-build
|
||||
rpmbuild -bb packaging/proton-drive-linux.spec \
|
||||
--define "git_dir $PWD" \
|
||||
--define "_rpmdir $PWD/packaging/out" \
|
||||
--define "_builddir $PWD/packaging/build" \
|
||||
--define "_sourcedir $PWD" \
|
||||
--define "_specdir $PWD/packaging" \
|
||||
--define "_srcrpmdir $PWD/packaging/out"
|
||||
sudo dnf install packaging/out/x86_64/proton-drive-linux-*.rpm
|
||||
```
|
||||
|
||||
### Using a binary outside `/usr/bin`
|
||||
|
||||
The service unit starts `/usr/bin/pdfs daemon`. If you installed the binaries somewhere else, for
|
||||
example `~/.local/bin`, install the unit for your user and point it at your binary:
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.config/systemd/user
|
||||
cp packaging/proton-drive.service ~/.config/systemd/user/
|
||||
sed -i "s|^ExecStart=.*|ExecStart=$HOME/.local/bin/pdfs daemon|" \
|
||||
~/.config/systemd/user/proton-drive.service
|
||||
systemctl --user daemon-reload
|
||||
```
|
||||
|
||||
To start the tray at login, copy `packaging/io.narl.proton-drive-linux-tray.desktop` to
|
||||
`~/.config/autostart/`. For the app launcher entry, copy `packaging/io.narl.proton-drive-linux.desktop`
|
||||
to `~/.local/share/applications/` and the icon `packaging/io.narl.proton-drive-linux.svg` to
|
||||
`~/.local/share/icons/hicolor/scalable/apps/`.
|
||||
|
||||
## First run
|
||||
|
||||
### With the desktop app
|
||||
|
||||
1. Open **Proton Drive** from your application menu, or run `pdfs-app`.
|
||||
2. Sign in with your Proton email and password, and your two-factor code if the account has one.
|
||||
If Proton asks for a CAPTCHA (common on a VPN or a new network), the app shows the challenge in
|
||||
a window and continues after you solve it.
|
||||
3. The app enables and starts `proton-drive.service`. Your Drive appears at `~/ProtonDrive`.
|
||||
|
||||
The service is tied to your graphical session. It starts after you log in and stops when you log
|
||||
out. Change the folder location under **Preferences → General → Location**.
|
||||
|
||||
### With the command line
|
||||
|
||||
`pdfs login` stores the session but does not enable the service, so a setup that runs the daemon
|
||||
another way stays untouched. Enable the service yourself:
|
||||
|
||||
```bash
|
||||
pdfs login # email, password, 2FA code
|
||||
systemctl --user enable --now proton-drive.service
|
||||
pdfs status # account, mount and queue state
|
||||
```
|
||||
|
||||
The CLI cannot show a CAPTCHA. If sign-in reports one, sign in once with `pdfs-app` instead; the
|
||||
session it stores is used by the CLI and the service as well.
|
||||
|
||||
## Headless and server use
|
||||
|
||||
The service unit is bound to `graphical-session.target`. On a machine without a desktop session,
|
||||
run the daemon directly or from your own unit:
|
||||
|
||||
```bash
|
||||
pdfs daemon # waits for a stored session, mounts, stays mounted
|
||||
pdfs mount /srv/proton # mounts once at a given path, blocks until unmounted
|
||||
```
|
||||
|
||||
Both still need a Secret Service provider. On a server, run
|
||||
`gnome-keyring-daemon --unlock` or KeePassXC's Secret Service integration inside the user's D-Bus
|
||||
session.
|
||||
|
||||
## Updating
|
||||
|
||||
Install the new package over the old one. The service picks up the new binary the next time it
|
||||
starts; to switch at once:
|
||||
|
||||
```bash
|
||||
systemctl --user restart proton-drive.service
|
||||
```
|
||||
|
||||
Database migrations run automatically and only move forward. A database written by a newer
|
||||
release refuses to open in an older one, so downgrading means clearing the local database (see
|
||||
[Troubleshooting](TROUBLESHOOTING.md#start-over-with-a-clean-local-state)).
|
||||
|
||||
## Uninstalling
|
||||
|
||||
> [!WARNING]
|
||||
> Check that nothing is waiting to upload before you remove local state. `pdfs sync queue` must be
|
||||
> empty. Queued writes exist only on this computer until they reach Proton Drive.
|
||||
|
||||
```bash
|
||||
pdfs sync queue # must list nothing
|
||||
systemctl --user disable --now proton-drive.service
|
||||
pdfs logout # removes the session from the keyring
|
||||
```
|
||||
|
||||
Then remove the package (`sudo apt remove proton-drive-linux`, `sudo dnf remove
|
||||
proton-drive-linux`, or `sudo pacman -R proton-drive-for-linux`), and, if you want no trace left,
|
||||
the local data:
|
||||
|
||||
```bash
|
||||
rm -rf ~/.config/proton-drive-linux ~/.local/state/proton-drive-linux ~/.cache/proton-drive-linux
|
||||
```
|
||||
|
||||
Sign out of the device in your Proton account settings as well, and remove the computer from
|
||||
**Computers** in the Proton Drive web app if you no longer want its backups.
|
||||
@@ -0,0 +1,28 @@
|
||||
# Documentation
|
||||
|
||||
## For users
|
||||
|
||||
| Page | What it covers |
|
||||
|---|---|
|
||||
| [Installation](INSTALL.md) | Packages, building from source, first sign-in, updating and uninstalling |
|
||||
| [User guide](USER_GUIDE.md) | My files, available offline, synced folders, conflicts, Photos, sharing, Trash and versions, Computers, the search launcher, the tray |
|
||||
| [Command-line reference](CLI.md) | Every `pdfs` command, grouped by task, and scripting with `--json` |
|
||||
| [Configuration](CONFIGURATION.md) | `config.json`, environment variables, file locations, the systemd service |
|
||||
| [Troubleshooting](TROUBLESHOOTING.md) | Diagnosing problems, common symptoms, starting over, reporting a bug |
|
||||
| [Recovering on a new computer](RECOVERY.md) | What survives a lost machine and how to restore your synced folders |
|
||||
| [Changelog](CHANGELOG.md) | What changed in each release |
|
||||
|
||||
## For contributors
|
||||
|
||||
| Page | What it covers |
|
||||
|---|---|
|
||||
| [Development guide](DEVELOPMENT.md) | Building, running and debugging from source; releasing |
|
||||
| [Architecture](ARCHITECTURE.md) | Crates, read and write paths, sync engine, control protocol, threads, threat model |
|
||||
| [Testing](TESTING.md) | Unit tests and the FUSE acceptance suite |
|
||||
| [Translating](TRANSLATING.md) | Adding and updating translations |
|
||||
| [Roadmap](ROADMAP.md) | Planned work and verification still owed |
|
||||
| [Bug ledger](BUGS.md) | Every tracked defect with its analysis and status |
|
||||
| [UI/UX plan](UI_UX_PLAN.md) | Design audit and notes behind the 2.x desktop app |
|
||||
|
||||
Also see [CONTRIBUTING.md](../CONTRIBUTING.md) and [SECURITY.md](../SECURITY.md) in the repository
|
||||
root.
|
||||
+119
-213
@@ -1,262 +1,168 @@
|
||||
# Recovery: Getting a Replacement Machine Back onto Your Device
|
||||
# Recovering on a new computer
|
||||
|
||||
You lose the laptop. You install `pdfs` on a new one. What does it take to get the
|
||||
synced folders back?
|
||||
Your laptop is lost, stolen or reinstalled. This page explains what survives, and how to get
|
||||
your synced folders back on the replacement machine.
|
||||
|
||||
This document is two things: **§2 is the runbook that works with the client as it
|
||||
stands today**, gotchas included, and **§3 is the plan to reduce that runbook to
|
||||
one command.** §1 is the part neither can fix — what actually died with the
|
||||
machine.
|
||||
- [1. What survives](#1-what-survives)
|
||||
- [2. Restore your synced folders](#2-restore-your-synced-folders)
|
||||
- [3. How the restore works](#3-how-the-restore-works)
|
||||
- [4. Known gaps](#4-known-gaps)
|
||||
|
||||
---
|
||||
## 1. What survives
|
||||
|
||||
## 1. What survives, and what does not
|
||||
### On Proton Drive
|
||||
|
||||
### Survives (it is on Drive, or derivable)
|
||||
|
||||
| Thing | Where it lives |
|
||||
| What | Where |
|
||||
|---|---|
|
||||
| Every file that finished uploading | Proton Drive |
|
||||
| The Device registration itself | Proton Drive (`enumerate_devices`) |
|
||||
| The device's folder tree — one folder per synced folder | Proton Drive, under the device root |
|
||||
| Your account, keys, sharing | Proton |
|
||||
| The computer's registration and its backup | **Computers** in the app and the web |
|
||||
| One folder per synced folder, under that computer | Proton Drive |
|
||||
| The machine profile: which folders were synced, to which local path, in which mode; pins; ignore patterns | `.proton-drive-linux/profile.json` under the computer's backup, end-to-end encrypted like any other file |
|
||||
| Your account, keys and shares | Proton |
|
||||
|
||||
### Does not survive
|
||||
The service rewrites the profile a short while after you add, remove or switch a synced folder,
|
||||
or change a pin.
|
||||
|
||||
| Thing | Why | Recoverable? |
|
||||
### Lost with the machine
|
||||
|
||||
| What | Why | Recoverable? |
|
||||
|---|---|---|
|
||||
| Undrained `staging/` + `recovery/` blobs | Writes the kernel accepted but that never reached Drive. They existed only on that disk. | **No.** |
|
||||
| Local-only files in a mirror folder that had not uploaded yet | Same. | **No.** |
|
||||
| `sync_folder` rows — which local path maps to which remote folder, and in which mode | Local SQLite (`cache.db`) | Rebuildable by hand (§2), not automatically (§3) |
|
||||
| `sync_entry` baseline | Local SQLite | Not needed. An empty baseline reconciles correctly — see §2.4. |
|
||||
| Pins | Local SQLite | Rebuildable by hand |
|
||||
| `config.json` — mountpoint, cache budget | Local config dir | Rebuildable by hand |
|
||||
| `cache.db` node/FTS/photo caches | Local SQLite | Pure cache; rebuilds itself |
|
||||
| Changes still in `staging/` or `recovery/` | Writes that were accepted locally but never reached Proton Drive | **No** |
|
||||
| New files in a synced folder that had not uploaded yet | Same | **No** |
|
||||
| `config.json`: mountpoint, cache limit, bandwidth limits, appearance | Local config directory | Set again in **Preferences** |
|
||||
| The local database and content cache | Local disk | Not needed; rebuilt from Proton Drive |
|
||||
|
||||
The first two rows are the only genuinely unrecoverable ones, and today nothing
|
||||
warns you they are non-empty before you walk away from a machine. That is tracked
|
||||
separately from this document as a pending-writes visibility gap.
|
||||
Only the first two rows are real losses. Before you retire a working machine, check that
|
||||
`pdfs sync queue` prints "Nothing queued" (or that **Sync → Overview** shows nothing waiting).
|
||||
|
||||
### Before anything else: revoke
|
||||
### Before anything else: revoke the old session
|
||||
|
||||
The lost machine holds a decrypted content cache, a plaintext index of every node
|
||||
name in your Drive (`cache.db`), and a live session in its keyring. Whether that
|
||||
matters depends on whether its disk was encrypted — but the session does not.
|
||||
The lost machine holds a decrypted content cache, a plain-text index of your file names and a
|
||||
live session in its keyring. Whether its disk was encrypted decides how much of that is exposed,
|
||||
but the session is valid either way.
|
||||
|
||||
**Revoke the session from your Proton account settings before restoring.** Nothing
|
||||
in this client can do that for you; the daemon on the lost machine holds
|
||||
credentials it will happily keep refreshing.
|
||||
**Sign the lost machine out from your Proton account's security settings before you restore.**
|
||||
The client cannot do that for you.
|
||||
|
||||
If you have also lost your password, Proton's recovery phrase is what determines
|
||||
whether the data is reachable at all. That is upstream of this client entirely: if
|
||||
zero-knowledge encryption worked as advertised, nobody at Proton can help.
|
||||
If you have also lost your password, account recovery is Proton's matter, not this client's.
|
||||
Proton Drive is end-to-end encrypted: without the password or a recovery method, the data cannot
|
||||
be decrypted.
|
||||
|
||||
---
|
||||
## 2. Restore your synced folders
|
||||
|
||||
## 2. The runbook that works today
|
||||
### Step 1: Install and sign in
|
||||
|
||||
### 2.1 Install, log in
|
||||
Install the client as described in [INSTALL.md](INSTALL.md) and sign in with `pdfs-app`. Signing
|
||||
in from the app also starts the service.
|
||||
|
||||
```bash
|
||||
pdfs login # stores the session in the keyring
|
||||
systemctl --user start proton-drive # or let autostart do it
|
||||
```
|
||||
### Step 2: Continue the old computer's backup
|
||||
|
||||
### 2.2 Re-adopt the device — check this before anything else
|
||||
Tell this machine which computer it replaces, so new changes go into the existing backup instead
|
||||
of a second, empty one.
|
||||
|
||||
`Core::ensure_device` recovers an existing device by **matching a Linux device
|
||||
whose name equals this machine's hostname**, read from
|
||||
`/proc/sys/kernel/hostname`. So:
|
||||
- **In the app:** open **Computers**, open the menu of the old computer and choose
|
||||
**Continue This Backup Here…**.
|
||||
- **From a terminal:**
|
||||
|
||||
```bash
|
||||
hostnamectl hostname # what this machine will register as
|
||||
pdfs devices list # what the account already has
|
||||
```
|
||||
```bash
|
||||
pdfs devices list # find the old computer's UID
|
||||
pdfs devices adopt UID
|
||||
```
|
||||
|
||||
- **Hostnames match** → the new machine silently re-adopts the old device and its
|
||||
root folder. This is the happy path, and it is why the rest of the runbook works.
|
||||
- **Hostnames differ** → `pdfs` registers a **second device**. Nothing errors.
|
||||
Your old device and all its folders are still there, but this machine is not
|
||||
attached to them, and every step below will quietly create empty folders under
|
||||
the new device instead.
|
||||
Adoption takes effect at once and is stored in `config.json` as `device_uid`. It survives a
|
||||
change of hostname. `pdfs devices adopt --clear` returns to the default, which is to match a
|
||||
computer whose name equals this machine's hostname.
|
||||
|
||||
> **The single most important step in this document:** if the hostnames differ,
|
||||
> set the new machine's hostname to match the old device's name *before* adding
|
||||
> any sync folders.
|
||||
> ```bash
|
||||
> sudo hostnamectl set-hostname OLD-DEVICE-NAME
|
||||
> ```
|
||||
> There is no supported way to adopt a device by uid yet — see §3.1.
|
||||
> [!NOTE]
|
||||
> Without adoption, the client only finds the old computer if this machine has the same
|
||||
> hostname. Otherwise it registers a new computer, and nothing points at the old backup.
|
||||
|
||||
### 2.3 Find out which folders the device had
|
||||
### Step 3: Restore the folders
|
||||
|
||||
```bash
|
||||
pdfs devices list # confirm the device and note its name
|
||||
```
|
||||
- **In the app:** open **Computers**, open the menu of **This computer** and choose
|
||||
**Restore Folders…**. Confirm or change the local path of each folder.
|
||||
- **From a terminal:**
|
||||
|
||||
The device's synced folders are the folders directly under its root in Drive.
|
||||
Browse them in the GUI's Computers page, or in the Proton Drive web app under
|
||||
that device. **Write down their exact names** — you need them in the next step.
|
||||
```console
|
||||
$ pdfs sync restore
|
||||
Documents [mirror] -> /home/you/Documents (Enter to accept, 'n' to skip, or a path)
|
||||
Projects [ondemand] -> /home/you/Projects (Enter to accept, 'n' to skip, or a path)
|
||||
```
|
||||
|
||||
### 2.4 Re-attach each folder
|
||||
Press Enter to accept a path, type `n` to skip the folder, or type another path. `--yes`
|
||||
accepts every proposal without asking.
|
||||
|
||||
For each folder name you noted, create the local directory and add it:
|
||||
For each folder you accept, the service creates the local directory, attaches it to the folder in
|
||||
the backup, restores its mode (**Mirror** or **Online only**) and downloads it. Follow the
|
||||
progress on **Sync → Overview** or with `pdfs sync list`.
|
||||
|
||||
```bash
|
||||
mkdir -p ~/Documents
|
||||
pdfs sync add ~/Documents
|
||||
```
|
||||
> [!TIP]
|
||||
> Restore into empty or missing directories. If a directory already holds files, for example
|
||||
> from another backup, the client cannot tell which side is newer. It keeps both: your local file
|
||||
> is renamed to a `(sync-conflict …)` copy and the version from Proton Drive is downloaded. See
|
||||
> [Conflicts](USER_GUIDE.md#conflicts).
|
||||
|
||||
`add_sync_folder` looks for a folder under the device root named after the local
|
||||
directory's **basename**, and reuses it if found rather than creating a second
|
||||
one. So `~/Documents` re-attaches to the existing `Documents`. With an empty
|
||||
baseline and an empty local directory, the first reconcile classifies every remote
|
||||
path as `(None, Some(remote))` with no baseline → **download**, and the folder
|
||||
refills from Drive.
|
||||
### Step 4: Restore the rest by hand
|
||||
|
||||
Three things to be careful about:
|
||||
- **Available offline files.** The profile records them, but the restore does not apply them yet.
|
||||
Mark them again in the app, or with `pdfs pin PATH`.
|
||||
- **Preferences.** Set the cache limit, bandwidth limits, mountpoint and appearance again.
|
||||
|
||||
- **The basename must match exactly.** Restoring to `~/docs` when the device
|
||||
folder is `Documents` does not re-attach — it creates a *new*, empty `docs`
|
||||
folder in Drive and syncs nothing. The failure is silent; you just see an empty
|
||||
directory. Check with `pdfs sync list` and the Computers page.
|
||||
- **Add the folder empty, or accept conflict copies.** If the local directory
|
||||
already has files (restored from a backup, say), there is no baseline to say
|
||||
which side is newer, so both sides read as changed and the reconcile takes the
|
||||
conflict arm: your local file is renamed to a `(sync-conflict <ts>)` copy and
|
||||
the remote version is downloaded. Nothing is lost, but it is noisy. Restoring
|
||||
into an empty directory avoids it.
|
||||
- **A wholly empty local tree is now safe.** Before the audit fixes, adding a
|
||||
folder whose local side was empty against a populated remote could, on a later
|
||||
pass, be read as "the user deleted everything" and trash the lot. `sync.rs`'s
|
||||
`guard_local_wipe` now refuses any pass where every baseline path has vanished
|
||||
locally, which is exactly the restore shape.
|
||||
### Step 5: Clean up
|
||||
|
||||
### 2.5 Restore modes, pins, and settings by hand
|
||||
|
||||
```bash
|
||||
pdfs sync list # note the ids
|
||||
pdfs sync mode <id> ondemand # for folders that were on-demand
|
||||
```
|
||||
|
||||
Nothing records which folders were `ondemand` before, so this is from memory. Pins
|
||||
and the cache budget/mountpoint likewise: set them again from the Settings page.
|
||||
|
||||
### 2.6 Clean up
|
||||
|
||||
If a duplicate device got created before you noticed the hostname mismatch:
|
||||
If this machine registered a second computer before you adopted the old one, remove it:
|
||||
|
||||
```bash
|
||||
pdfs devices list
|
||||
pdfs devices rm <uid-of-the-stray-device>
|
||||
pdfs devices rm UID
|
||||
```
|
||||
|
||||
Check what is under it in the web app first. Deleting a device you actually
|
||||
attached folders to will take its folders with it.
|
||||
> [!WARNING]
|
||||
> Removing a computer deletes its backup from Proton Drive. Check what is under it in
|
||||
> **Computers → Browse Files** first.
|
||||
|
||||
---
|
||||
### Restoring another computer's folders
|
||||
|
||||
## 3. The plan: make this one command
|
||||
To bring folders from a computer that still exists, for example a desktop whose documents you want
|
||||
on a laptop, use **Restore to This Computer…** on that computer's row, or:
|
||||
|
||||
The pieces all exist — device enumeration, folder-name reuse, an empty-baseline
|
||||
reconcile that downloads correctly. What is missing is that the restore is
|
||||
**implicit, name-based, and undiscoverable**. Each phase below removes one of
|
||||
those properties. They are independent and land in this order by value.
|
||||
```bash
|
||||
pdfs sync restore --device UID
|
||||
```
|
||||
|
||||
### P1 — Adopt a device explicitly, by uid
|
||||
The folders stay part of the other computer's backup and sync in both directions. This machine
|
||||
does not take over that computer's backup.
|
||||
|
||||
**Problem:** device identity is inferred from the hostname. A new laptop with a
|
||||
new name silently forks a second device, and the failure looks like "my files
|
||||
didn't come back" rather than an error.
|
||||
## 3. How the restore works
|
||||
|
||||
- Add `Request::AdoptDevice { uid }`: validate the uid against
|
||||
`enumerate_devices`, write the `StoredDevice` row, and refuse if any
|
||||
`sync_folder` rows already reference a different device.
|
||||
- `pdfs devices adopt <uid>`, and an "Adopt this device" action on rows in the
|
||||
GUI's Computers page that are not the current machine.
|
||||
- Make the fork *visible* rather than silent: when `ensure_device` is about to
|
||||
create a device and the account already has other Linux devices, log a warning
|
||||
naming them, and surface it in `pdfs status`.
|
||||
This section is for the curious and for anyone debugging a restore.
|
||||
|
||||
Keep hostname matching as the default. It is right for the common case; it just
|
||||
must not be the *only* way.
|
||||
- **Which computer the machine is.** At start, the service uses `device_uid` from `config.json`
|
||||
when it is set. When it is not, it looks for a Linux computer in the account whose name equals
|
||||
the hostname, and registers a new one when there is none. An adopted UID that no longer exists
|
||||
in the account is reported in the log instead of being replaced silently.
|
||||
- **What can be restored.** `pdfs sync restore` lists the folders directly under the computer's
|
||||
backup, except `.proton-drive-linux`. Folders already synced on this machine are skipped.
|
||||
- **Proposed paths.** When the profile names a local path whose parent directory exists on this
|
||||
machine, that path is proposed. Otherwise the proposal is `~/<folder name>`. The service never
|
||||
writes to a path you have not confirmed.
|
||||
- **Attaching by UID.** The restore binds each local path to the remote folder's UID, not to its
|
||||
name. Restoring `Documents` into `~/docs` works.
|
||||
- **Downloading.** A restored folder starts with an empty sync baseline. Against an empty local
|
||||
directory, every remote file counts as new and is downloaded. Files present on both sides with
|
||||
no baseline become conflict copies, as described above.
|
||||
- **The wipe guard.** A sync pass in which every previously synced file has vanished locally is
|
||||
refused instead of being mirrored to Proton Drive as a mass deletion. A folder that was emptied
|
||||
by accident therefore does not empty the backup.
|
||||
- **The profile format.** `profile.json` carries a `version` field. A client refuses a profile
|
||||
written by a newer, incompatible client instead of applying part of it.
|
||||
|
||||
### P2 — Discover and re-attach the device's folders
|
||||
## 4. Known gaps
|
||||
|
||||
**Problem:** §2.3 and §2.4 are "remember what you had, then retype it exactly."
|
||||
|
||||
- Add `Request::ListDeviceFolders { device_uid }` — enumerate the device root's
|
||||
child folders and report name, node uid, child count, and total size. This is
|
||||
the "what did this machine sync?" answer that today requires the web app.
|
||||
- Add `Request::AttachSyncFolder { remote_uid, local_path, mode }` — the
|
||||
re-attach counterpart to `AddSyncFolder`. It binds a local path to a **specific
|
||||
remote uid** rather than resolving by basename, which removes the silent
|
||||
`~/docs` vs `Documents` failure entirely.
|
||||
- CLI: `pdfs sync restore [--device <uid>] [--into <dir>]` — list the device's
|
||||
folders, propose `<dir>/<name>` for each (default `$HOME`), and attach the ones
|
||||
the user confirms.
|
||||
- GUI: a "Restore folders from this device" flow on the Computers page, with a
|
||||
per-folder local-path picker defaulting to `~/<name>`.
|
||||
|
||||
Refuse to attach into a non-empty directory without an explicit
|
||||
`--allow-nonempty`, so the conflict-copy noise of §2.4 is opt-in rather than a
|
||||
surprise.
|
||||
|
||||
### P3 — Back the profile up to Drive
|
||||
|
||||
**Problem:** modes, pins, mountpoint, and cache budget exist only on the dead
|
||||
machine, so even a perfect P2 restores folders in the wrong mode with no pins.
|
||||
|
||||
Write a small JSON document into a hidden folder in the user's own Drive — say
|
||||
`.proton-drive-linux/profile.json` — containing, per device:
|
||||
|
||||
- sync folders: remote uid, the local path last used, and mode
|
||||
- pinned node uids
|
||||
- mountpoint and cache budget
|
||||
|
||||
It rides on Drive's own encryption, so this introduces no new crypto and no new
|
||||
place for plaintext to sit. Rewrite it whenever any of those change, debounced.
|
||||
|
||||
On a fresh install, after login: *"Found settings from `<device>`, last updated
|
||||
`<date>`. Restore?"* Node uids are stable across machines, so pins restore
|
||||
exactly. Local paths need remapping when the username or home differs — show the
|
||||
old path, default the new one to `$HOME/<basename>`.
|
||||
|
||||
Store the last-used local path only as a *hint*. Restoring a profile must never
|
||||
write to a path the user has not confirmed in this session.
|
||||
|
||||
### P4 — Make the unrecoverable visible
|
||||
|
||||
Nothing above helps with §1's undrained writes, because by then it is too late.
|
||||
The mitigation is to make the pending queue impossible to miss *before* the
|
||||
machine is lost:
|
||||
|
||||
- pending count and bytes in `pdfs status`, using the existing `pending` map and
|
||||
`TransferRegistry`
|
||||
- a tray icon state and a GUI banner while the queue is non-empty
|
||||
- a warning on logout or shutdown while it is non-empty
|
||||
|
||||
### P5 — Verification
|
||||
|
||||
None of the above is trustworthy without exercising the actual shape of the
|
||||
disaster. The end-to-end test is: register a device, sync a folder, upload
|
||||
content, **delete the local state directory and cache entirely** (simulating the
|
||||
lost machine), restart, restore, and assert the tree comes back byte-identical.
|
||||
|
||||
That is a two-account or at least two-state-dir integration test against a live
|
||||
account, not a unit test. Until the mock-backend problem described in
|
||||
`audit-plan.md` is solved, it stays manual — but it should be run, and its result
|
||||
recorded here, before P1–P3 are called done.
|
||||
|
||||
---
|
||||
|
||||
## 4. Current status
|
||||
|
||||
| Phase | State |
|
||||
| Gap | Effect |
|
||||
|---|---|
|
||||
| Manual runbook (§2) | Works, with the hostname and basename caveats |
|
||||
| P1 explicit adoption | Not started |
|
||||
| P2 discover + attach | Not started |
|
||||
| P3 profile on Drive | Not started |
|
||||
| P4 pending visibility | Not started |
|
||||
| P5 restore drill | Never run |
|
||||
| Pins are backed up but not restored | Mark files available offline again by hand |
|
||||
| No warning at shutdown or sign-out while changes are queued | Check `pdfs sync queue` before you retire a machine |
|
||||
| The full disaster drill (delete all local state, restore, compare byte for byte) has not been run against a live account | The individual steps are tested; the whole sequence is not |
|
||||
|
||||
Planned work is tracked in [ROADMAP.md](ROADMAP.md).
|
||||
@@ -0,0 +1,72 @@
|
||||
# Roadmap
|
||||
|
||||
Planned work and open verification, as of 2.5.0. Individual defects and their status live in
|
||||
[BUGS.md](BUGS.md), which is the authoritative ledger; this page groups what is left by theme.
|
||||
Nothing here is a promise of a date.
|
||||
|
||||
- [Data safety and recovery](#data-safety-and-recovery)
|
||||
- [Features](#features)
|
||||
- [Performance and correctness](#performance-and-correctness)
|
||||
- [Verification still owed](#verification-still-owed)
|
||||
- [Release assurance](#release-assurance)
|
||||
|
||||
## Data safety and recovery
|
||||
|
||||
| Item | State | Notes |
|
||||
|---|---|---|
|
||||
| Protect queued changes at shutdown | Not started | A systemd inhibitor lock while `staging/` holds unsent data, a warning when signing out, and a blocking `pdfs sync flush`. Today the queue is visible through `pdfs sync queue`, the tray and **Sync → Overview**, but nothing stops a shutdown (B66) |
|
||||
| Restore pins from the machine profile | Not started | `profile.json` records pins; `sync restore` does not apply them yet |
|
||||
| Profile backup health | Not started | A failed profile upload is a `WARN` in the log and nothing in the UI (B68) |
|
||||
| Rotated credentials survive a keyring failure | Open | Surface and retry keyring write failures so a rotated single-use refresh token is not lost (B61) |
|
||||
| Encrypt local state at rest | Not started | SQLCipher for `cache.db` and an AEAD for the content cache, keyed from the keyring. `sdk_cache.db` is already encrypted. See [ARCHITECTURE.md §8](ARCHITECTURE.md#8-threat-model-what-this-client-writes-to-disk-in-plaintext) |
|
||||
|
||||
## Features
|
||||
|
||||
| Item | State | Notes |
|
||||
|---|---|---|
|
||||
| File-manager integration | Not started | Context-menu actions (available offline, share link, versions) and sync badges for Nautilus, Dolphin and Thunar |
|
||||
| Terminal UI | Not started | `pdfs tui` with transfers, sync state and logs |
|
||||
| Multiple accounts | Not started | Separate config, state and mountpoint per profile, one daemon each |
|
||||
| Mount options | Not started | Read-only mount, `allow_other` |
|
||||
| Symbolic links | Not started | Proton Drive has no link type; links would need a placeholder format. Until then, creating one fails with `EOPNOTSUPP` |
|
||||
| Add someone else's photo to your album | Blocked | Needs `copyPhoto` in the SDK |
|
||||
| Photo name search | Not started | Photos search by date and filters only |
|
||||
| Automatic photo upload from a folder | Not started | |
|
||||
| Faster Google Photos import | Not started | Uploads run one at a time. Trash folders of locales missing from `TRASH_FOLDERS` import as photos; motion-photo `.MP` parts are skipped |
|
||||
| Content-addressed block cache | Idea | Store blocks by hash to deduplicate identical content |
|
||||
|
||||
## Performance and correctness
|
||||
|
||||
| Item | Notes |
|
||||
|---|---|
|
||||
| Saturating stream-ring accounting | `self.bytes -= …` in `crates/pdfs-fuse/src/reads.rs` should saturate so an accounting drift cannot wrap in release builds |
|
||||
| Block geometry learned one read late | The first read of a file plans on 4 MiB blocks; accepted as a bounded cost (B87) |
|
||||
| Path-based commands under secondary mounts | `pin`, `rename`, `move`, `rm` and sharing cannot name a path inside an on-demand synced folder yet (B88) |
|
||||
| Unicode normalization | NFC and NFD names are distinct, deliberately (B36) |
|
||||
| Pipelined node enumeration | Faster cold listings of large folders |
|
||||
|
||||
## Verification still owed
|
||||
|
||||
Fixes marked *unverified* in [BUGS.md](BUGS.md) have unit or offline coverage but have not been
|
||||
driven against a live account. The larger outstanding runs:
|
||||
|
||||
- **Disaster-recovery drill.** Register a device, sync a folder, delete all local state, restore
|
||||
with `pdfs sync restore` and compare the tree byte for byte. See [RECOVERY.md](RECOVERY.md).
|
||||
- **Second-account sharing.** Shared trees on a foreign volume, accepting invitations, changing
|
||||
roles, the viewer cases of `regression B34`, and an editor writing into someone else's share.
|
||||
- **Fault injection.** Network loss mid-upload, a full disk during staging, and crash points
|
||||
across the write publication path (after each fsync, rename and queue commit).
|
||||
- **CAPTCHA sign-in** against a real verification request (B8).
|
||||
- **Managed live mode matrix** before each release:
|
||||
`scripts/fuse-acceptance.sh --managed-live <empty-a> <empty-b>`. See [TESTING.md](TESTING.md).
|
||||
- **The overnight hang** (B91) is not diagnosed yet. The supervisor and `pdfs diagnostics` exist to
|
||||
catch the next occurrence.
|
||||
|
||||
## Release assurance
|
||||
|
||||
| Item | State |
|
||||
|---|---|
|
||||
| Tag, workspace and PKGBUILD version agreement | Enforced by the release workflow |
|
||||
| Clean-install test of the `.deb` and `.rpm` in a VM | Pending (B62) |
|
||||
| Protocol version identity between front ends and daemon | Open (B63) |
|
||||
| SBOM, provenance and checksums for release artifacts | Open (B65). The RPM is GPG-signed |
|
||||
+3
-4
@@ -78,10 +78,9 @@ in-flight `.crdownload` must not be sealed as a revision) and B74 (a file
|
||||
renamed after close must keep its content) need a real mount and a reachable
|
||||
daemon; they are skipped, not failed, without one.
|
||||
|
||||
B74 is currently **failing** — it is a live data-loss defect, not a regression
|
||||
guard, and it was found by exactly this mechanism: the B70 case failed, and
|
||||
narrowing it produced a smaller reproduction that has its own case now. Expect a
|
||||
red run against a real mount until it is fixed.
|
||||
B74 was found by exactly this mechanism: the B70 case failed, and narrowing it
|
||||
produced a smaller reproduction that got its own case. The defect is fixed and
|
||||
live-validated (2026-07-26); the case now guards against its return.
|
||||
|
||||
**B79** (an on-demand device folder accepts writes) discovers its target from
|
||||
`pdfs locations --json` and skips when this machine has no mounted on-demand
|
||||
|
||||
@@ -0,0 +1,204 @@
|
||||
# Troubleshooting
|
||||
|
||||
Start with `pdfs diagnose`, then find your symptom below. If nothing here helps,
|
||||
[open an issue](https://github.com/narrrl/proton-drive-linux/issues/new/choose) with the
|
||||
information listed under [Reporting a problem](#reporting-a-problem).
|
||||
|
||||
- [First checks](#first-checks)
|
||||
- [Signing in](#signing-in)
|
||||
- [The Proton Drive folder](#the-proton-drive-folder)
|
||||
- [Uploads and sync](#uploads-and-sync)
|
||||
- [Disk space](#disk-space)
|
||||
- [Desktop integration](#desktop-integration)
|
||||
- [Start over with a clean local state](#start-over-with-a-clean-local-state)
|
||||
- [Reporting a problem](#reporting-a-problem)
|
||||
|
||||
## First checks
|
||||
|
||||
### `pdfs diagnose`
|
||||
|
||||
Checks the installation and prints a report. It does not need the service, because the state
|
||||
worth diagnosing is often the one where the service will not start.
|
||||
|
||||
```console
|
||||
$ pdfs diagnose
|
||||
Paths
|
||||
[ok ] state dir: /home/you/.local/state/proton-drive-linux
|
||||
[ok ] cache dir: /home/you/.cache/proton-drive-linux
|
||||
[ok ] state dir writable: write and fsync succeeded
|
||||
[ok ] database: /home/you/.local/state/proton-drive-linux/cache.db (473.1 MiB)
|
||||
|
||||
FUSE
|
||||
[ok ] /dev/fuse: /dev/fuse
|
||||
[ok ] unmount helper: fusermount3 or fusermount on PATH
|
||||
|
||||
Account
|
||||
[ok ] keyring session: you@proton.me
|
||||
|
||||
Daemon
|
||||
[ok ] control socket: /home/you/.local/state/proton-drive-linux/control.sock
|
||||
[ok ] daemon responding
|
||||
[ok ] active mount: /home/you/ProtonDrive (fuse.protondrive)
|
||||
[ok ] network: online
|
||||
[ok ] queued writes: none
|
||||
[ok ] database integrity: SQLite integrity_check passed
|
||||
[ok ] configured mountpoint: /home/you/ProtonDrive
|
||||
|
||||
No problems found.
|
||||
```
|
||||
|
||||
It exits non-zero when a check fails, so it also works in a health-check script.
|
||||
|
||||
### Logs
|
||||
|
||||
```bash
|
||||
journalctl --user -u proton-drive.service -f # follow the service
|
||||
journalctl --user -u proton-drive.service -b -p warning # warnings since boot
|
||||
```
|
||||
|
||||
For more detail, raise the log level with a drop-in (see
|
||||
[CONFIGURATION.md](CONFIGURATION.md#the-systemd-service)) and restart the service.
|
||||
|
||||
### Service state
|
||||
|
||||
```bash
|
||||
systemctl --user status proton-drive.service
|
||||
pdfs status
|
||||
```
|
||||
|
||||
## Signing in
|
||||
|
||||
**"Proton is asking for a CAPTCHA"** — Proton wants human verification, usually on a VPN or an
|
||||
unfamiliar network. The CLI cannot show it. Sign in with `pdfs-app`, which displays the challenge;
|
||||
the stored session then works for the CLI too.
|
||||
|
||||
**Sign-in works but is forgotten after a restart** — no Secret Service provider is running, or its
|
||||
keyring is locked. Install and unlock GNOME Keyring, KWallet or KeePassXC (with Secret Service
|
||||
enabled). `pdfs diagnose` shows `keyring session` as failing in that case.
|
||||
|
||||
## The Proton Drive folder
|
||||
|
||||
> [!TIP]
|
||||
> When the service hangs, any program that touches the Proton Drive folder can hang with it,
|
||||
> including `ls` and your shell's prompt. Prefix exploratory commands with `timeout 5`.
|
||||
|
||||
**`Transport endpoint is not connected`** — the service stopped without unmounting. Unmount and
|
||||
restart:
|
||||
|
||||
```bash
|
||||
fusermount3 -uz ~/ProtonDrive
|
||||
systemctl --user restart proton-drive.service
|
||||
```
|
||||
|
||||
**The folder is empty or missing** — check that the service runs and is signed in
|
||||
(`pdfs status`). The service waits for a stored session before it mounts.
|
||||
|
||||
**Everything in the folder hangs** — find out what the service is doing, then restart it:
|
||||
|
||||
```bash
|
||||
timeout 10 pdfs diagnostics
|
||||
systemctl --user restart proton-drive.service
|
||||
```
|
||||
|
||||
The service watchdog restarts a service that stops answering for two minutes by itself. Attach the
|
||||
`pdfs diagnostics` output to a bug report; it shows which worker is stuck.
|
||||
|
||||
**A change made on another device does not show up** — changes arrive through Proton's event
|
||||
stream, normally within seconds. To fetch a folder again at once:
|
||||
|
||||
```bash
|
||||
pdfs refresh Documents
|
||||
```
|
||||
|
||||
**"Permission denied" when writing** — the item is in a share where you are a viewer, or under
|
||||
`Shared with me/`, which is read-only as a folder. Check your role with `pdfs shared-with-me`.
|
||||
|
||||
**A program says "Operation not supported"** — Proton Drive cannot store symbolic links, hard
|
||||
links, device files or FIFOs. The error is intentional. Use a synced folder for
|
||||
projects that need them, or exclude those paths.
|
||||
|
||||
## Uploads and sync
|
||||
|
||||
**Something is stuck uploading** — list the queue and retry:
|
||||
|
||||
```bash
|
||||
pdfs sync queue
|
||||
pdfs sync retry # every failed operation
|
||||
pdfs sync retry 42 # one operation
|
||||
```
|
||||
|
||||
The app shows the same list on **Sync → Overview**. An operation that keeps failing shows its
|
||||
error there.
|
||||
|
||||
**A file in a synced folder does not upload** — check that:
|
||||
|
||||
- it is not matched by `.pdfsignore` or `ignore_patterns`;
|
||||
- no program still holds it open for writing (such files wait until closed);
|
||||
- sync is not paused (`pdfs status`, tray);
|
||||
- the folder has no error on **Sync → Folders**.
|
||||
|
||||
`pdfs sync now` starts a pass immediately.
|
||||
|
||||
**Files named `(sync-conflict …)` appeared** — the file changed in two places at once. Nothing was
|
||||
lost; see [Conflicts](USER_GUIDE.md#conflicts) to pick a version.
|
||||
|
||||
**Photos show the wrong date after a Google Takeout import** — run
|
||||
`pdfs redate-photos --dry-run`, see [USER_GUIDE.md](USER_GUIDE.md#importing-from-google-photos).
|
||||
|
||||
## Disk space
|
||||
|
||||
| What | Check | Reduce |
|
||||
|---|---|---|
|
||||
| Content cache | `pdfs cache inspect` | Lower **Preferences → Storage → Cache size limit**, or `pdfs cache clear` |
|
||||
| Available-offline files | `pdfs pins` | `pdfs unpin PATH` |
|
||||
| Metadata database | `pdfs cache inspect` (reclaimable) | `pdfs cache vacuum` |
|
||||
| Synced folders | `pdfs sync list` | Switch large folders to online only: `pdfs sync mode ID ondemand` |
|
||||
|
||||
`pdfs cache vacuum` locks the database while it runs and needs free space for a second copy of it.
|
||||
|
||||
## Desktop integration
|
||||
|
||||
**No tray icon on GNOME** — install and enable the AppIndicator and KStatusNotifierItem Support
|
||||
extension. Other desktops show the icon natively. If you hid it from its own menu, turn it back on
|
||||
under **Preferences → General → Appearance**.
|
||||
|
||||
**The search launcher does nothing** — `pdfs-prompt` needs the service. Run it from a terminal to
|
||||
see its error. For `--fzf`, install `fzf` and a supported terminal.
|
||||
|
||||
**The app shows "Not responding"** — the service runs but does not answer within five seconds.
|
||||
See [Everything in the folder hangs](#the-proton-drive-folder).
|
||||
|
||||
## Start over with a clean local state
|
||||
|
||||
This removes the local database and cache so they are rebuilt from Proton Drive. It is the fix for
|
||||
a damaged database and the only way to downgrade to an older release.
|
||||
|
||||
> [!WARNING]
|
||||
> Content in `staging/` and `recovery/` has not reached Proton Drive yet. Deleting it loses those
|
||||
> changes permanently. Wait until `pdfs sync queue` is empty.
|
||||
|
||||
```bash
|
||||
pdfs sync queue # must list nothing
|
||||
systemctl --user stop proton-drive.service
|
||||
mv ~/.local/state/proton-drive-linux ~/.local/state/proton-drive-linux.bak
|
||||
mv ~/.cache/proton-drive-linux ~/.cache/proton-drive-linux.bak
|
||||
systemctl --user start proton-drive.service
|
||||
```
|
||||
|
||||
Your session is in the keyring and your settings in `~/.config`, so you stay signed in. Synced
|
||||
folders are not re-attached automatically; restore them with `pdfs sync restore` as described in
|
||||
[RECOVERY.md](RECOVERY.md#2-restore-your-synced-folders). Delete the `.bak` directories once
|
||||
everything is back.
|
||||
|
||||
## Reporting a problem
|
||||
|
||||
Include:
|
||||
|
||||
- `pdfs --version`, your distribution and desktop;
|
||||
- the output of `pdfs diagnose`;
|
||||
- relevant log lines from `journalctl --user -u proton-drive.service`;
|
||||
- for a hang, the output of `timeout 10 pdfs diagnostics`;
|
||||
- the steps that reproduce it.
|
||||
|
||||
Logs contain file names. Remove anything private before posting. Report security problems
|
||||
privately as described in [SECURITY.md](../SECURITY.md).
|
||||
@@ -0,0 +1,294 @@
|
||||
# User guide
|
||||
|
||||
How Proton Drive for Linux works and how to use it day to day. For installation see
|
||||
[INSTALL.md](INSTALL.md); every command mentioned here is described in [CLI.md](CLI.md).
|
||||
|
||||
- [How it works](#how-it-works)
|
||||
- [My files](#my-files)
|
||||
- [Keeping files on this computer](#keeping-files-on-this-computer)
|
||||
- [Syncing local folders](#syncing-local-folders)
|
||||
- [Conflicts](#conflicts)
|
||||
- [Pausing and limiting sync](#pausing-and-limiting-sync)
|
||||
- [Photos](#photos)
|
||||
- [Sharing](#sharing)
|
||||
- [Trash and version history](#trash-and-version-history)
|
||||
- [Computers](#computers)
|
||||
- [Search launcher](#search-launcher)
|
||||
- [Choosing how files open](#choosing-how-files-open)
|
||||
- [Tray](#tray)
|
||||
- [Preferences](#preferences)
|
||||
|
||||
## How it works
|
||||
|
||||
A background service, `proton-drive.service`, runs `pdfs daemon`. It holds your session, talks to
|
||||
Proton Drive, and keeps your Drive mounted as a folder. Everything else is a front end that asks
|
||||
the service to do things over a local socket:
|
||||
|
||||
| Program | What it is |
|
||||
|---|---|
|
||||
| `pdfs-app` | The desktop app: files, photos, sharing, sync, preferences |
|
||||
| `pdfs-tray` | Tray icon with status, pause and quick actions |
|
||||
| `pdfs-prompt` | A search launcher for a keyboard shortcut |
|
||||
| `pdfs` | The command-line client, for everything above and for scripts |
|
||||
|
||||
Your Drive, your file names and your photos are end-to-end encrypted by Proton. On this computer,
|
||||
the service must decrypt what it shows you, and it keeps a decrypted cache and index on disk. Use
|
||||
full-disk or home-directory encryption. [ARCHITECTURE.md §8](ARCHITECTURE.md#8-threat-model-what-this-client-writes-to-disk-in-plaintext)
|
||||
lists exactly what is stored.
|
||||
|
||||
The app uses these words consistently, and so does this guide:
|
||||
|
||||
| Term | Meaning |
|
||||
|---|---|
|
||||
| **My files** | The root of your Drive |
|
||||
| **Proton Drive folder** | Where My files appears on disk, `~/ProtonDrive` by default |
|
||||
| **Online only** | A file or folder whose content downloads when opened |
|
||||
| **Available offline** | A single file kept on this computer |
|
||||
| **Synced folder** | A local folder with a full copy on this computer, backed up to Proton Drive |
|
||||
| **Proton Drive service** | The background service (`proton-drive.service`) |
|
||||
|
||||
## My files
|
||||
|
||||
My files is mounted at `~/ProtonDrive`. Every file and folder appears immediately, but content
|
||||
downloads only when a program reads it:
|
||||
|
||||
- **Reads fetch only what is needed.** A video player that seeks, or a tool that reads a file
|
||||
header, downloads only those parts. Media streams while it plays.
|
||||
- **Writes are safe offline.** When a program closes a file it wrote, the service stores the new
|
||||
content on disk and queues the upload. The queue survives network loss, restarts and crashes.
|
||||
`pdfs sync queue` lists what has not reached Proton Drive yet.
|
||||
- **Recently read content is cached** on disk up to the cache size limit (5 GiB by default) and
|
||||
evicted oldest first.
|
||||
- **Items shared with you** appear under `Shared with me/` inside the Proton Drive folder. Shares
|
||||
where you are a viewer are read-only.
|
||||
|
||||
The **My files** page of the app browses the same tree without going through the mount. It has a
|
||||
grid and a list view, sorting, thumbnails (including camera RAW previews), multi-select and drag
|
||||
and drop upload. **Details** (Alt+Enter) shows size, dates, sharing and version history for the
|
||||
selected item.
|
||||
|
||||
Symbolic links, hard links, device files and FIFOs cannot be stored on Proton Drive. Programs that
|
||||
try to create them get a clean error, not a hang or `EIO`.
|
||||
|
||||
## Keeping files on this computer
|
||||
|
||||
Turn on **Make available offline** for a file in My files, or run `pdfs pin <path>`. The file is
|
||||
downloaded completely and never evicted from the cache. `pdfs pins` lists these files, and
|
||||
**Preferences → Storage → Available offline** shows them in the app.
|
||||
|
||||
Turning it off (`pdfs unpin <path>`) frees the space. The file stays on Proton Drive.
|
||||
|
||||
## Syncing local folders
|
||||
|
||||
A synced folder is an ordinary folder on this computer, for example `~/Documents`, that is
|
||||
backed up to Proton Drive under this computer's name. It appears on the **Computers** page of the
|
||||
app and in the web app.
|
||||
|
||||
- Add one with **Add Folder to Sync** on the **Computers** page, or `pdfs sync add ~/Documents`.
|
||||
- Changes flow both ways. Local edits upload a few seconds after the file is closed; remote edits
|
||||
download on the next pass.
|
||||
- A file that another program still holds open for writing is not uploaded until it is closed.
|
||||
- **Sync → Folders** in the app, and `pdfs sync list`, show every folder and its state.
|
||||
|
||||
Each synced folder can also be switched to **Online only**. The local copy is replaced by a mount
|
||||
of the folder, so the files stay visible but take no disk space until opened. Switch with the
|
||||
**Synced / Online only** switch on the folder's card, or `pdfs sync mode <id> ondemand` and back
|
||||
with `pdfs sync mode <id> mirror`. `pdfs locations` lists every local place the service occupies.
|
||||
|
||||
Removing a synced folder (**Stop Syncing** or `pdfs sync rm <id>`) keeps the local files and the
|
||||
copy on Proton Drive. Add `--delete-remote` (or tick **Also delete from Proton Drive**) to delete
|
||||
the copy on Proton Drive as well.
|
||||
|
||||
### Excluding files with `.pdfsignore`
|
||||
|
||||
Synced folders skip build output, dependency folders and editor leftovers. Rules come from two
|
||||
places, and both apply:
|
||||
|
||||
1. A `.pdfsignore` file at the root of the synced folder (`.protonignore` also works), using
|
||||
gitignore syntax, including `!` to re-include:
|
||||
|
||||
```gitignore
|
||||
build/
|
||||
*.log
|
||||
!important.log
|
||||
```
|
||||
|
||||
2. The global `ignore_patterns` list in `config.json` (see
|
||||
[CONFIGURATION.md](CONFIGURATION.md#ignore_patterns)). When unset, it defaults to `.git/`,
|
||||
`.hg/`, `.svn/`, `node_modules/`, `target/`, `.venv/`, `__pycache__/`, `*~`, `*.swp`, `*.tmp`,
|
||||
`.DS_Store` and `Thumbs.db`.
|
||||
|
||||
Rules are re-read on every pass. Ignoring never deletes anything: a file that becomes ignored is
|
||||
simply no longer tracked, and its copy on Proton Drive stays.
|
||||
|
||||
## Conflicts
|
||||
|
||||
When the same file changed on this computer and somewhere else since the last sync, neither side
|
||||
is thrown away. The local version is kept as a copy named like
|
||||
`report (sync-conflict 1759068180).odt`, where the number is the time of the conflict in seconds
|
||||
since 1970, and the remote version takes the original name.
|
||||
|
||||
Conflicts appear under **Sync → Overview → Needs attention** and in `pdfs conflicts`. For each
|
||||
one, keep the original, keep the copy, or keep both under a new name:
|
||||
|
||||
```bash
|
||||
pdfs conflicts
|
||||
pdfs conflicts resolve "Documents/report (sync-conflict 1759068180).odt" --keep copy
|
||||
```
|
||||
|
||||
The version you do not keep goes to the Trash, so a wrong choice can be undone.
|
||||
|
||||
## Pausing and limiting sync
|
||||
|
||||
- **Pause** from the tray, the Sync page, or `pdfs sync pause`. Uploads and synced folders wait;
|
||||
reading files keeps working. `pdfs sync resume` continues.
|
||||
- **Limit bandwidth** under **Preferences → General → Network**, or with
|
||||
`pdfs sync limit --up 2M --down 10M`. `0` removes a limit.
|
||||
- **Retry** a failed upload from **Sync → Overview**, or with `pdfs sync retry`.
|
||||
|
||||
## Photos
|
||||
|
||||
The **Photos** page shows your Proton Photos library. Photos are stored separately from My files
|
||||
and do not appear in the Proton Drive folder.
|
||||
|
||||
- **Timeline** groups photos by day, month or year as you zoom. Drag the scrubber on the right edge
|
||||
to jump through the years. **On this day** shows photos from the same date in earlier years.
|
||||
- **Filters** narrow the timeline to images, videos or RAW files, to favorites, or to photos that
|
||||
are in no album.
|
||||
- **RAW + JPEG pairs** of the same shot show as one tile. The viewer switches between them, and
|
||||
moving the tile to the Trash removes both.
|
||||
- **Albums** lists your albums and albums shared with you. Create, rename and delete albums, and
|
||||
add or remove photos.
|
||||
- **Places** groups photos by the town they were taken in, as cards or on a map. Towns come from
|
||||
bundled [GeoNames](https://www.geonames.org/) data (CC BY 4.0) and the map from
|
||||
[Natural Earth](https://www.naturalearthdata.com/) (public domain), so nothing is fetched online.
|
||||
An optional street map from [OpenFreeMap](https://openfreemap.org/) (© OpenStreetMap
|
||||
contributors) can be enabled under **Preferences → General → Appearance**. It is off by default
|
||||
because the tile server learns which areas you look at.
|
||||
- **Viewer**: favorites, EXIF details, show on map, slideshow (F5).
|
||||
- **Find Duplicates…** in the page menu lists byte-identical copies. The **Similar** switch also
|
||||
finds resized or re-encoded copies and burst shots by comparing thumbnails.
|
||||
- **Upload** adds photos. Its menu holds **Import from Google Photos…**.
|
||||
|
||||
### Importing from Google Photos
|
||||
|
||||
Request a Google Takeout export of Google Photos, then pass every `.zip` of it at once. A photo's
|
||||
metadata often sits in a different part of the export than the photo itself.
|
||||
|
||||
```bash
|
||||
pdfs import-google-photos --dry-run ~/Downloads/takeout-*.zip # see what would happen
|
||||
pdfs import-google-photos --wait ~/Downloads/takeout-*.zip
|
||||
```
|
||||
|
||||
Albums are recreated, capture dates and locations are taken from the metadata, and photos already
|
||||
on the account are skipped, so an interrupted import can be run again. `pdfs import-status` and
|
||||
`pdfs cancel-import` follow or stop an import that runs in the background.
|
||||
|
||||
If photos from an earlier import are filed under the day they were uploaded,
|
||||
`pdfs redate-photos --dry-run` finds those whose file name carries a different date, and
|
||||
`pdfs redate-photos` fixes them. Proton cannot change a capture date in place, so each fix
|
||||
re-uploads the photo and moves the original to the Trash, keeping favorites and albums.
|
||||
|
||||
## Sharing
|
||||
|
||||
- **Share…** on a file or folder invites people by email as viewer or editor, or creates a public
|
||||
link with an optional password and expiry. `pdfs share`, `pdfs members`, `pdfs share-role`,
|
||||
`pdfs unshare` and `pdfs public-link` do the same from a terminal.
|
||||
- **Shared by me** lists everything you share, filtered by links, people or expired links. Copy a
|
||||
live link or stop several shares at once.
|
||||
- **Shared with me** lists what others share with you, with who shared it and your access.
|
||||
Pending invitations wait in a banner; `pdfs invitations` accepts or rejects them. Saved public
|
||||
links (`pdfs bookmarks`) have their own view.
|
||||
|
||||
## Trash and version history
|
||||
|
||||
The **Trash** page lists trashed items with the date they were deleted. Restore puts an item back
|
||||
where it was, together with trashed folders above it. **Delete Forever** and **Empty Trash** are
|
||||
permanent. The CLI equivalents are `pdfs trash`, `pdfs restore`, `pdfs delete-forever` and
|
||||
`pdfs empty-trash`.
|
||||
|
||||
Proton Drive keeps earlier versions of every file. **Details → Versions…** in the app, or
|
||||
`pdfs versions list <path>`, shows them. You can:
|
||||
|
||||
- **Restore** a version. This happens on the server; nothing is re-uploaded.
|
||||
- **Save** a version to a separate local file without touching the current one.
|
||||
- **Delete** an old version permanently. The current version cannot be deleted.
|
||||
|
||||
## Computers
|
||||
|
||||
**Computers** lists this computer and every other computer that backs up to your account.
|
||||
|
||||
- **This computer** shows its synced folders with their state, and **Restore Folders…** brings
|
||||
back folders that are backed up under it but not synced here yet.
|
||||
- **Another computer** can be browsed read-only in the same list or grid as My files, and
|
||||
**Restore to This Computer…** downloads its folders here.
|
||||
- **Continue This Backup Here…** makes this computer take over another computer's backup, for
|
||||
example after reinstalling or replacing a machine. See [RECOVERY.md](RECOVERY.md).
|
||||
|
||||
## Search launcher
|
||||
|
||||
`pdfs-prompt` searches Proton Drive and your home folder together, in one ranked list. It
|
||||
tolerates prefixes, abbreviations, typos and swapped letters, and matches on parent folder names
|
||||
as well. Bind it to a keyboard shortcut in your desktop settings.
|
||||
|
||||
The window stays loaded after the first use, so later shortcuts open it instantly. Folders, audio
|
||||
and video open straight from the Proton Drive folder, so players can start before the whole file
|
||||
downloads. Other Drive files download first, then open.
|
||||
|
||||
### Using your own launcher
|
||||
|
||||
`pdfs-prompt --dmenu` shows the results in fuzzel, rofi, wofi, tofi, bemenu or dmenu, whichever is
|
||||
installed:
|
||||
|
||||
```bash
|
||||
pdfs-prompt --dmenu
|
||||
pdfs-prompt --dmenu --menu 'fuzzel --dmenu --width 60'
|
||||
pdfs-prompt --dmenu --query invoice
|
||||
```
|
||||
|
||||
A dmenu-style launcher filters a fixed list and cannot ask for new results per keystroke, so the
|
||||
search takes two steps. The first list, `Search Drive ›`, shows your available-offline files; type
|
||||
a query and press Enter to search. The second, `Drive: invoice ›`, shows the results; Enter opens
|
||||
one, and typing something else searches again.
|
||||
|
||||
### Search as you type with fzf
|
||||
|
||||
`pdfs-prompt --fzf` re-queries the service on every keystroke, like the built-in window. When
|
||||
started from a keybinding without a terminal, it opens one itself (foot, ghostty, kitty,
|
||||
alacritty, wezterm or xterm) with the app ID `pdfs-prompt`, so one window rule covers all of them.
|
||||
For Hyprland:
|
||||
|
||||
```ini
|
||||
windowrulev2 = float, class:^(pdfs-prompt)$
|
||||
windowrulev2 = size 900 500, class:^(pdfs-prompt)$
|
||||
windowrulev2 = center, class:^(pdfs-prompt)$
|
||||
bind = SUPER, space, exec, pdfs-prompt --fzf
|
||||
```
|
||||
|
||||
To make `--dmenu` or `--fzf` the default without changing your keybinding, set `prompt.mode` in
|
||||
`config.json` ([CONFIGURATION.md](CONFIGURATION.md#prompt)). `--gtk` forces the built-in window.
|
||||
|
||||
## Choosing how files open
|
||||
|
||||
Files open with `xdg-open` by default. The `open_with` section of `config.json` overrides that per
|
||||
file type, for example text in Neovim inside a terminal. The rules apply to the search launcher
|
||||
and to the app. See [CONFIGURATION.md](CONFIGURATION.md#open_with).
|
||||
|
||||
## Tray
|
||||
|
||||
`pdfs-tray` starts at login and shows whether files are up to date, syncing, paused or offline.
|
||||
Its menu opens the app or the Proton Drive folder, pauses or resumes sync, and stops or connects
|
||||
the service. **Hide Tray Icon** removes it until you turn it back on under
|
||||
**Preferences → General → Appearance → Show tray icon**.
|
||||
|
||||
GNOME needs the AppIndicator extension to show tray icons.
|
||||
|
||||
## Preferences
|
||||
|
||||
| Page | Settings |
|
||||
|---|---|
|
||||
| **General** | Start on login · Proton Drive folder location · upload and download limits · Proton theme, street map for Places, tray icon · language |
|
||||
| **Storage** | Cache size limit · clear the cache · files kept available offline |
|
||||
|
||||
The account menu shows storage used and holds **Sign Out…**. Settings not exposed in the app are
|
||||
listed in [CONFIGURATION.md](CONFIGURATION.md).
|
||||
Executable
+134
@@ -0,0 +1,134 @@
|
||||
#!/usr/bin/env bash
|
||||
# Publish the user documentation in docs/ to the GitHub wiki.
|
||||
#
|
||||
# The pages in docs/ are the source of truth; the wiki is a generated copy for
|
||||
# people who look there first. Each run clones the wiki, replaces the pages
|
||||
# listed below, rewrites links between them to wiki page names and every other
|
||||
# repository link to an absolute GitHub URL, regenerates Home and _Sidebar, and
|
||||
# commits. Nothing is pushed without --push.
|
||||
#
|
||||
# GitHub creates the wiki repository only when the first page is saved, so
|
||||
# create any page once in the web UI before the first run.
|
||||
#
|
||||
# usage: scripts/publish-wiki.sh [--push] [WORKDIR]
|
||||
set -euo pipefail
|
||||
|
||||
repo_url="https://github.com/narrrl/proton-drive-linux"
|
||||
wiki_remote="git@github.com:narrrl/proton-drive-linux.wiki.git"
|
||||
|
||||
push=0
|
||||
if [ "${1:-}" = "--push" ]; then
|
||||
push=1
|
||||
shift
|
||||
fi
|
||||
|
||||
root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
||||
workdir="${1:-$(mktemp -d)}"
|
||||
wiki="$workdir/wiki"
|
||||
|
||||
if [ -d "$wiki/.git" ]; then
|
||||
git -C "$wiki" pull --ff-only --quiet
|
||||
else
|
||||
git clone --quiet "$wiki_remote" "$wiki"
|
||||
fi
|
||||
|
||||
rev="$(git -C "$root" rev-parse --short HEAD)"
|
||||
version="$(grep -m1 '^version' "$root/Cargo.toml" | cut -d'"' -f2)"
|
||||
|
||||
python3 - "$root" "$wiki" "$repo_url" "$version" <<'EOF'
|
||||
import pathlib
|
||||
import re
|
||||
import sys
|
||||
|
||||
root, wiki, repo_url, version = sys.argv[1:]
|
||||
root = pathlib.Path(root)
|
||||
wiki = pathlib.Path(wiki)
|
||||
|
||||
# docs/ file -> wiki page name, in sidebar order.
|
||||
PAGES = {
|
||||
"INSTALL.md": "Installation",
|
||||
"USER_GUIDE.md": "User-Guide",
|
||||
"CLI.md": "Command-Line-Reference",
|
||||
"CONFIGURATION.md": "Configuration",
|
||||
"TROUBLESHOOTING.md": "Troubleshooting",
|
||||
"RECOVERY.md": "Recovery",
|
||||
}
|
||||
|
||||
LINK = re.compile(r"(\]\()([^)\s]+)(\))")
|
||||
|
||||
|
||||
def rewrite(target: str) -> str:
|
||||
if re.match(r"^[a-z]+:|^#", target):
|
||||
return target
|
||||
path, _, anchor = target.partition("#")
|
||||
anchor = f"#{anchor}" if anchor else ""
|
||||
if path in PAGES:
|
||||
return PAGES[path] + anchor
|
||||
# Anything else is a file in the repository: link to it on GitHub.
|
||||
resolved = (root / "docs" / path).resolve().relative_to(root)
|
||||
kind = "tree" if (root / resolved).is_dir() else "blob"
|
||||
return f"{repo_url}/{kind}/main/{resolved}{anchor}"
|
||||
|
||||
|
||||
def convert(text: str) -> str:
|
||||
return LINK.sub(lambda m: m.group(1) + rewrite(m.group(2)) + m.group(3), text)
|
||||
|
||||
|
||||
note = (
|
||||
"<!-- Generated from docs/ in the repository by scripts/publish-wiki.sh."
|
||||
" Edit the source there; changes made here are overwritten. -->\n\n"
|
||||
)
|
||||
|
||||
for source, page in PAGES.items():
|
||||
text = (root / "docs" / source).read_text()
|
||||
(wiki / f"{page}.md").write_text(note + convert(text))
|
||||
|
||||
|
||||
def title(source: str) -> str:
|
||||
return (root / "docs" / source).read_text().splitlines()[0].lstrip("# ").strip()
|
||||
|
||||
|
||||
home = [
|
||||
note,
|
||||
"# Proton Drive for Linux\n\n",
|
||||
"An unofficial Proton Drive client for the Linux desktop: your files as a folder that ",
|
||||
"downloads on demand, synced local folders, Photos, sharing, a GTK4 app with tray and search ",
|
||||
"launcher, and a scriptable CLI.\n\n",
|
||||
f"This wiki mirrors the documentation of version {version}. The source, releases and issue ",
|
||||
f"tracker are in the [repository]({repo_url}).\n\n",
|
||||
"## Pages\n\n",
|
||||
]
|
||||
home += [f"- [{title(source)}]({page})\n" for source, page in PAGES.items()]
|
||||
home += [
|
||||
"\n## More\n\n",
|
||||
f"- [Changelog]({repo_url}/blob/main/docs/CHANGELOG.md)\n",
|
||||
f"- [Architecture]({repo_url}/blob/main/docs/ARCHITECTURE.md)\n",
|
||||
f"- [Contributing]({repo_url}/blob/main/CONTRIBUTING.md)\n",
|
||||
f"- [Report a problem]({repo_url}/issues/new/choose)\n",
|
||||
]
|
||||
(wiki / "Home.md").write_text("".join(home))
|
||||
|
||||
sidebar = ["**[Home](Home)**\n\n"]
|
||||
sidebar += [f"- [{title(source)}]({page})\n" for source, page in PAGES.items()]
|
||||
sidebar += [
|
||||
"\n---\n\n",
|
||||
f"[Releases]({repo_url}/releases) · [Issues]({repo_url}/issues)\n",
|
||||
]
|
||||
(wiki / "_Sidebar.md").write_text("".join(sidebar))
|
||||
EOF
|
||||
|
||||
cd "$wiki"
|
||||
git add -A
|
||||
if git diff --cached --quiet; then
|
||||
echo "Wiki is already up to date."
|
||||
exit 0
|
||||
fi
|
||||
git commit --quiet -m "Update from docs at $rev"
|
||||
git show --stat --format='%s' HEAD
|
||||
|
||||
if [ "$push" = 1 ]; then
|
||||
git push --quiet
|
||||
echo "Pushed to $wiki_remote."
|
||||
else
|
||||
echo "Committed in $wiki. Review it, then push from there or re-run with --push."
|
||||
fi
|
||||
Reference in new issue
Block a user