Files

Files

synfiles is SynapseOS's file manager, and what a folder opens in. It is one C binary plus a quickshell window, in the same shape as synpkg: the binary does the work and prints records, the window only renders them. Nothing in the QML knows how to stat a file, and everything the window can do has a command-line half.

Front-end	Command
The window	Files in the start menu, double-clicking a folder, or synfiles gui [dir]
Command line	synfiles list, synfiles find, synfiles trash, …

It has no dependency but libc. File types come from shared-mime-info's data files, mounting is delegated to udisks2, and the icon theme is resolved by the front-end that already has it loaded.

It replaced Dolphin as the default in August 2026. Dolphin is still installed and still works — it simply is not what a folder opens in. See Getting Dolphin back.

---

The window

• Tabs (Ctrl+T), each with its own history — Back and Forward are per tab, because a shared history sends Back somewhere this tab has never been.
• Split view (F3): two panes side by side, each with its own tabs, selection and search. An accent line marks the active one. Drag between them.
• Three view modes — Icons, Compact and Details — picked from the View button. The default is auto, which follows the icon size: a details list for small icons, a grid for large ones.
• Thumbnails, from the shared freedesktop cache. Anything Dolphin, GTK or a video player has already thumbnailed appears here for free, video and PDF included, because it is the same cache keyed the same way.
• Folder tree, toggleable, expanded one level at a time.
• Address bar: breadcrumbs, or Ctrl+L to type a path.
• Sidebar — pinned places, Recent, Trash, and your disks with fill meters.
• Drag and drop — between panes, between windows, onto the desktop, and out to any other application. A drop from another application copies rather than moves: moving would delete another program's data on a guess.

Keyboard

Key	Action
Enter	Open
Alt+Enter	Properties
F2	Rename, in place, in whichever view you are in
F3	Split view on/off
Delete	Move to trash
Backspace	Up one folder
Ctrl+F	Search this folder and everything below it
Ctrl+L	Edit the path
Ctrl+C / Ctrl+X / Ctrl+V	Copy / cut / paste
Ctrl+Z	Undo the last thing that changed files
Ctrl+A	Select all
Ctrl+N	New folder
Ctrl+T / Ctrl+W	New tab / close tab
Escape	Close a dialog, end a search, or clear the selection

---

The trash, and undo

These two are the whole safety design, and they are worth knowing before you need them.

Delete means the trash — the XDG trash, the same one Dolphin and Nautilus use, so what one of them put there is what you see here, and restoring puts a file back where it came from rather than in your home directory. A file on another disk goes to that disk's trash, because trashing is always a rename and never a copy.

synfiles trash notes.txt      # what Delete does
synfiles trash list
synfiles trash restore notes.txt
synfiles trash empty --yes

The permanent one is synfiles delete --yes, it is gated behind that flag, and no key or click in the window reaches it.

Anything that changed files can be undone — Ctrl+Z, or the chip in the toolbar, which says what it would reverse ("↶ Move of 2 items"). A recovery control that does not say what it undoes goes unpressed.

synfiles undo list      # what would be reversed
synfiles undo

Three rules it follows:

• A batch is one thing. Moving six files undoes as one operation.
• Undoing a copy trashes the copies rather than unlinking them. The copy may have been edited since, and undo must never be a shorter road to losing work than delete is.
• It verifies, then refuses. If something else now occupies the old place, undo stops rather than overwriting a file created after the operation being undone. delete --yes is deliberately not journalled at all: an undo entry that cannot undo would look like a safety net and not be one.

---

Properties

Alt+Enter, or Properties… in the right-click menu. The panel is a view over synfiles info, so the dialog and the command show the same list by construction — name, type, mime type, size, permissions, owner, the three timestamps, link target, and resolution for images and video.

synfiles info photo.jpg

Resolution is read from the file's magic bytes, never its extension, so a photo saved as .txt still reports its size and a text file named .png is not parsed into a plausible-looking lie. PNG, JPEG, GIF, BMP, WebP, TIFF, ICO, AVIF, HEIF, MP4 and MOV are read in-tree with no extra package. Matroska, WebM and AVI carry their size somewhere no small parser should go, so those are handed to ffprobe — install ffmpeg and the row appears; without it, those files simply have no resolution row rather than a guessed one.

Selecting several files answers a different question instead: how many, and how much.

Only info ever reads a file's content. A listing never does — opening four thousand files to draw four thousand rows is what makes a file manager hang on a network share.

---

The right-click menu

Open With comes from the desktop-entry index, and the Extract / Crop / Mount ISO / Run with Wine / Set as Wallpaper entries are synui's own KIO service menus, read straight out of $XDG_DATA_DIRS/kio/servicemenus. That is where Dolphin reads them too, so a helper written once appears in both file managers.

The window never builds a command line: it names an action, and the binary does the Exec= parsing and the %F/%f/%U substitution. Nothing goes to a shell.

A mixed-type selection offers no service menus at all, because an action that applies to one kind of file and not another has no honest answer for the group.

---

Places, volumes and archives

Pinned places are Dolphin's own file — ~/.local/share/user-places.xbel. Your existing sidebar is there the first time you open the window, and running both file managers does not fork your bookmarks into two diverging lists. Pin and unpin splice a single entry and take a one-time .pre-synfiles backup before first touching the file.

Volumes come from lsblk, /proc/self/mounts and systemd .mount units, which is more work than it sounds like it should be: an automounted disk shows no mount point in lsblk until something touches it, and a file manager that believes lsblk alone will call a working drive "not mounted" and offer to mount it a second time. Unmounted volumes are shown dimmed with a mount button; mounting and unmounting go through udisksctl, which owns the polkit rules that let a desktop user do it without root.

Archives: select, right-click, Compress — tar.gz, tar.xz, tar.zst, zip or 7z. Every input must share one parent, and the tool runs with that parent as its working directory, or the archive stores absolute paths and unpacking it scatters files across the disk. Compressing is journalled, so Ctrl+Z puts a mistaken archive in the trash. Extraction is the service menu that was already there.

---

Search

Ctrl+F searches the current folder and everything below it. The filter box does double duty and says which mode it is in — filtering is instant, searching walks the tree.

synfiles find . --name=iso                 # no glob characters means "contains"
synfiles find ~/src --name='*.c' --content=TODO

• Never descends a symlink. A link to its own ancestor is a loop and one pointing at / turns a search of a project folder into a search of the whole machine. Links are reported, not followed.
• Bounded — 1000 results and 16 levels by default, both adjustable.
• --name and --content are ANDed; --content skips binary files and caps each one at 8 MB.
• Every hit carries the folder it was found in. "config.json" appears eleven times in a source tree, and which one it is is the only useful thing about it.

---

Settings

Remembered in ~/.config/synfiles/settings, written by the binary rather than by the window:

synfiles config list
synfiles config set view details
synfiles config set icon_size 48
synfiles config reset

Key	Values	Default
view	auto, icons, compact, details	auto
icon_size	16–128	20
previews	on/off	on
tree	on/off	off
hidden	on/off	off
sort	name, size, mtime, type	name
reverse	on/off	off
split	on/off	off
text_scale	75–175 (percent)	100

Numbers clamp; an unknown key or an invalid value is refused rather than stored, because a settings file that accepts anything accumulates typos that never read back. sort, reverse and hidden are per tab, so what is saved is the default a new tab starts from.

---

For scripts: --rec

Every command takes --rec and prints tab-separated records — the same ones the window parses.

synfiles --rec list ~/Downloads
synfiles --rec info photo.jpg

Every field carrying a name or a path is percent-encoded, and this is not decoration. A filename is any sequence of bytes except / and NUL: tabs, newlines, quotes and invalid UTF-8 are all legal, and a file called notes<TAB>receipts does not make a broken row in a naive TSV — it makes a plausible row naming a different file, which is then handed back to something that renames or deletes it.

The encoded form is the identity. Decode it for display only, and never hand the decoded string back to anything that touches the disk.

Exit status is 0 for success, 1 for failure and 100 for "nothing to list", so a script can tell an empty folder from a broken command without parsing output.

---

Getting Dolphin back

One command, and it wins because it lands in your own config rather than in the distribution's:

xdg-mime default org.kde.dolphin.desktop inode/directory

The reverse is xdg-mime default synfiles.desktop inode/directory, or delete the line from ~/.config/mimeapps.list to fall back to the system default, which is synfiles.

If Dolphin is not installed any more: synpkg install dolphin.

---

See also

• The Desktop — the bar, widgets, desktop icons, themes
• Commands — the whole command-line surface
• Software — synpkg, the package manager built the same way
• Troubleshooting — when a folder opens in the wrong thing