Pathfinder

A native file manager for Linux, built with Rust and GTK4 / libadwaita. File operations are implemented directly on top of the Rust standard library rather than through a GIO/KIO wrapper. Tags, search and a SQLite index are planned for v2.

Features (v1)

• Navigation — breadcrumb path bar, toggleable editable path bar, back/forward/up, history.
• Views — detailed list (with columns) and icon/grid view; switchable size S/M/L; list virtualization for 10k+ entries.
• Sort & filter — by name, size, date, type; type-ahead quick filter; folders-before-files; toggle for hidden files.
• Operations — copy, move, rename, delete (freedesktop trash), new folder; progress dialog with cancel; conflict dialog (overwrite / skip / rename / keep both / apply to all).
• Drag & drop — move files/folders by drag & drop (default) or copy (hold Ctrl); drop targets include folders in the file list as well as sidebar places and removable volumes; reuses the shared transfer engine (progress and conflict handling).
• Selection — multi-selection via Ctrl/Shift; rubber-band selection; cut/copy/paste.
• System clipboard (cross-application) — cut/copy/paste interoperates with the rest of the desktop: files copied or cut in Pathfinder can be pasted in other file managers or on the desktop and vice versa; cut files are moved (KDE/GNOME cut markers). Image data on the clipboard (e.g. a screenshot) is written on paste as a new PNG file (unique timestamped name, atomic, never overwriting); a single image file can be pasted as pixels into image editors, paths as text. Uses the native GTK clipboard; external files pass through the same data-safe transfer engine (conflict handling, move only after the target is verified). See docs/design-clipboard-interop.md.
• Sidebar — favorites/bookmarks (drag-reorder, persistent); recently visited places (max. 12); removable volumes with eject; internal and network mounts; every section configurable.
• Customizable toolbar — the toolbar is edited directly in the app: the gear menu → “Customize toolbar…” slides the file list aside, a “Done” bar appears (with “Reset”), and a centered palette of hidden items below it. The toolbar itself becomes a drag & drop surface: 15 items (new, back/forward/up/refresh, copy/paste/rename/trash, filter, sort, view/size/hidden, details) can be reordered freely, moved between the left and right zones, and hidden or restored via the palette; the path center and the settings gear are fixed anchors. “Done”/Esc applies; the layout (ordered left/right lists per zone) is persisted backward-compatibly in the config. On the start page the list-specific controls (filter, sort, view, size, hidden) are hidden, as no file list is active there.
• Properties dialog — two tabs: General (name, path, MIME, size, timestamps, symlink target) and Permissions (see below). Owner/group are displayed; editing them is planned for v2.
• Permissions — view and edit file permissions: a permission matrix (read/write/execute × owner/group/others) with tooltips plus special flags (setuid, setgid, sticky); live symbolic and octal preview; quick presets (600/700/644/755); “Apply” calls chmod via the backend. Available in the properties dialog (Permissions tab) and in the right-hand details panel. Only the owner or root can change permissions (editable flag from the backend); editing is disabled for multi-selections. The mode is masked to 0o7777 (no type bits), the path is resolved via canonicalize, and authorization is left to the OS (EPERM when the caller lacks the right); chmod does not modify file contents.
• Thumbnails — image previews (PNG/JPEG and others) as well as STL/3MF renderings, cached in the shared freedesktop thumbnail cache ($XDG_CACHE_HOME/thumbnails/); compatible with Dolphin/Nautilus/Thunar (shared reuse); automatic age-based cleanup (90 days), no size cap.
• Filesystem watcher — watches the current directory (non-recursive); self-healing reload on changes.
• Appearance — light/dark/system theme; configurable accent color; panel transparency; compositor blur flag.
• Internationalization — German and English; switchable at runtime; the locale is detected from LANG and stored in the config.
• Symlinks — displayed (target, broken flag); creation is planned for v2.
• Open with… — right-clicking a file opens a dialog of installed applications that support the file type (MIME); select with a single click, launch with a double click or “Open”. MIME detection uses the file extension (mime_guess) — files without an extension may not list a matching application. Application icons, “browse for other application”, and setting a persistent default application are planned for v2.
• Terminal — right-clicking a folder or the empty area opens the “Terminal ▸” submenu with two entries: “Open terminal here” launches the detected emulator in the selected directory; “Root terminal” additionally launches it through a privilege-escalation tool (sudo/doas/su). The emulator is resolved automatically: first $TERMINAL (checked against a whitelist), then a probe list (konsole, alacritty, kitty, foot, wezterm, ghostty, gnome-terminal, ptyxis, tilix, xfce4-terminal, xterm). Security: no sh -c, all arguments passed as separate argv elements, the escalation command comes solely from a backend constant, and Pathfinder never launches itself as root. Both terminal variants start in the selected directory: the root terminal deliberately uses non-login shells (sudo -s / su / doas -s) that retain the working directory (a login shell such as sudo -i would switch to /root), at the cost of not loading the root shell’s full login environment. Choosing the terminal in settings is planned for v2.
• OneDrive status (onedriver) — in directories mounted by onedriver (FUSE), the detailed view shows an additional “Status” column with sync icons: empty cloud = online only (not present locally), checkmark cloud = available locally. OneDrive roots are detected from enabled systemd units (onedriver@*.service) at startup and on window focus. If a configured folder is not mounted, a notice is shown instead of an empty list. Read-only — no pinning, no download trigger, no cloud access. Status is derived locally via an st_blocks heuristic (standard library only). v1 scope: only the “online only” / “available locally” states; syncing, error and pinned states are prepared in the data model but arrive in v2 via onedriver’s own mechanism (xattr/D-Bus). See docs/design-onedrive-status.md.
• Skyhook engine (direct OneDrive) — Pathfinder’s own OneDrive module using the Microsoft Graph API directly (phase 1: read-only). Sign-in via OAuth2 PKCE (public client); refresh token stored in the OS keyring/KWallet. Settings → Accounts → “Skyhook (OneDrive direct)”. “Read OneDrive” loads the complete OneDrive tree as a metadata shadow into a local SQLite database (no content download), incrementally via the delta endpoint, resumable. The sidebar entry “Skyhook” opens a virtual cloud view (skyhook://) with breadcrumb and status column (online only / pinned / loading / orphaned). On demand: “Make available offline” downloads a file atomically into the app cache (tmp → fsync → rename, hash verification: quickXorHash for personal accounts, sha256 for business/education); “Free up space” removes only the unchanged local cache copy. Double-click: pinned → open, online only → download. Refresh: incremental delta sync; pinned files are re-fetched when the cloud copy changes (eTag). Offline: browsing and pinned files remain available. Data safety: eviction only for unchanged files. Coexists with onedriver support (separate sidebar entry). Writing (phase 2): (2a) Upload — an edited and saved pinned file is uploaded automatically after a quiet period (cache watcher with debounce/stability gate); on conflict (cloud changed in the meantime) a conflict copy is created, never an overwrite (If-Match/pre-flight eTag); large files use an upload session (320 KiB fragments). (2b) Cloud operations — new folder/file, rename, move (context-menu cut/paste and drag & drop onto folders/breadcrumb, multi-selection capable; best-effort on name conflicts with a persistent report dialog), delete (→ OneDrive trash, confirmation dialog, If-Match). Creation uses conflictBehavior=fail (never overwrite). Cloud deletions are reflected locally: a deleted item disappears locally as well; a pinned copy is moved safely into a fallback trash (Settings → Accounts, viewable/restorable/emptyable) rather than being lost. See docs/design-onedrive-graph.md, docs/design-skyhook-upload.md, docs/design-skyhook-2b.md.

Keyboard shortcuts

Shortcut	Action
Ctrl+C	Copy
Ctrl+X	Cut
Ctrl+V	Paste
Del	Move to trash
F2	Rename
Alt+Enter	Properties dialog
Ctrl+A	Select all
Ctrl+H	Show/hide hidden files
Ctrl+L	Toggle the path bar into edit mode
Ctrl+F	Focus the quick filter
Ctrl+Shift+N	New folder
Ctrl (while dragging)	Drag & drop: copy instead of move
Esc	Clear selection / cancel input
Space / Enter	Open entry (navigate folder, open file with default app)

Architecture

Pathfinder is a Cargo workspace with two crates:

• pathfinder-core — a UI-free backend library: services, models, utilities and the native thumbnail helpers. It follows a layered model — services/ (testable logic) → models/ (serde DTOs) + util/. All filesystem calls run in a blocking pool so a slow or hanging mount cannot stall the async executor. Path-safety guards live here.
• pathfinder-gtk — the GTK4 / libadwaita user interface, built with relm4. It consumes pathfinder-core and translates its events into UI updates.

Detailed architecture: docs/architecture.md.

Build & development

cargo build -p pathfinder-gtk          # build the GTK frontend
./target/debug/pathfinder-gtk          # run
cargo test --workspace                 # run the unit tests
cargo clippy --workspace               # lint

A render self-check that detects a blank window is available via PF_SELFCHECK=1 ./target/debug/pathfinder-gtk or bash scripts/gtk-selfcheck.sh (prints PF_SELFCHECK: OK on success).

System requirements

• Rust / Cargo (stable)
• GTK 4 and libadwaita development packages (on Debian/Ubuntu: libgtk-4-dev libadwaita-1-dev)
• A C compiler (cc) for the bundled thumbnail helpers
• A Secret Service provider (e.g. GNOME Keyring or KWallet) at runtime for Skyhook token storage

SQLite is bundled; TLS uses rustls, so no system OpenSSL is required.

Configuration & data paths

File	Purpose
$XDG_CONFIG_HOME/pathfinder/config.json	Main configuration (appearance, view, sidebar, toolbar, i18n)
$XDG_CONFIG_HOME/pathfinder/recent.json	Recently visited places (max. 12 entries)
$XDG_CACHE_HOME/thumbnails/ (fallback ~/.cache/thumbnails/)	Thumbnail cache, shared with other file managers (freedesktop Thumbnail Managing Standard: normal/large/x-large/xx-large, filename = MD5 of the file:// URI, validated by mtime/size)
$XDG_CACHE_HOME/pathfinder/skyhook/	Skyhook file cache (pinned OneDrive files; layout <sha256hex(item-id)>/<real-name>)

$XDG_CONFIG_HOME falls back to ~/.config, $XDG_CACHE_HOME to ~/.cache. The config is written atomically (tmp + rename). On corruption a .bak backup is created and the defaults are used.

Roadmap (v2)

Tags, color labels, full-text search, smart folders (SQLite package); undo/redo, preview panel, compress/extract, symlink creation, chown (change owner/group), terminal selection in settings. onedriver: fine-grained syncing/error/pinned states via onedriver’s own xattr or D-Bus mechanism; a connected/disconnected sidebar indicator. Skyhook: optional LRU eviction.

License

Pathfinder is dual-licensed — you may use it under either license:

• Open source: GPL-3.0-only. Free to use, modify and redistribute; distributed derivative works must also be released as open source under the GPL-3.0 (copyleft).
• Commercial license: for use in proprietary/closed-source software, without the GPL obligations, a commercial license is available from the copyright holder. Details: LICENSING.md.

© 2026 Patrick Stratil.