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.

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. F9 puts it away (Dolphin's key, and Nautilus'), and that is remembered.
• 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.

Copying, moving and deleting

Everything long says how long is left, in the unit that decides it. That is not decoration: emptying the trash of a folder off a USB stick is two or three minutes of work — an unlink there measures around 12 ms — and a GUI silent that long cannot be told from a hang.

Recursive deletes report as they go rather than as one record at the end, and copies show a rate and an estimate.

Copying used to be 147× slower than cp. An fsync per file: 2000 small files took 12.25 s against cp -r's 0.08 s on an SSD, and on a USB stick, where an fsync is tens of milliseconds, that was the whole of "copying seems slow". It is 0.08 s now. The fsync was there for a reason — a cross-filesystem move deletes the original — so the durability barrier stayed where it belongs and left the copy path alone.

A mounted disc image appears under Removable Devices — right-click an .iso and choose Mount Image, or mount one any other way. It is named by its volume label, or by its file name when it has none. Eject unmounts it and releases the loop device behind it; if the image is open in a pane, the pane goes to your home folder first. A hybrid image (one that also boots from a USB stick) lists the filesystem inside it, not the container.

A USB stick with no partition table — a filesystem written straight to the device — appears under Removable Devices. One was mounted, browsable and invisible in the sidebar because the scan expected every filesystem to sit on a partition.

Keyboard

In a terminal

synfiles tui [dir] is the same file manager with a terminal for a front-end. It is the one to reach for over SSH, on a TTY, or on a machine whose desktop will not start — and it needs nothing installed that the window does not.

synfiles tui               # here
synfiles tui ~/Downloads   # somewhere else

y is copy rather than c, which is already "cd" — two operations that ask the same question ("to:") should not be a shift away from each other.

It reimplements nothing. The listing is the scan synfiles list prints, properties are synfiles info, sizes are synfiles du, moving and copying are synfiles move and synfiles copy. So a move made here is in the same journal as a move made in the window, and Ctrl+Z — synfiles undo — reverses it. A browser that walked directories itself would be a second set of answers about symlinks, broken links and sort order, and the two would drift on the first bug fixed in one of them.

A path you type is relative to what you are browsing, not to the shell's working directory: typing alpha while looking at a folder that plainly contains an alpha goes there. ~ works. Only a leading / is absolute.

t reaches the trash, never synfiles delete — the permanent one is gated behind --yes and no key here reaches it, exactly as in the window.

What it does to your terminal

It turns off echo and line-buffering so that arrow keys arrive without Enter, and nothing else:

• No mouse reporting. That is the one that does real harm: a full-screen TUI killed mid-flight never sends the sequence that turns it off, and the shell underneath then reads every pointer movement as typed input.
• No alternate screen. What you browsed stays in the scrollback.
• Ctrl+C still interrupts, rather than being swallowed as a keystroke.

The settings are put back on exit, on Ctrl+C, and on SIGTERM, SIGHUP and SIGQUIT. The worst a kill -9 can leave behind is a terminal with echo off, which reset fixes.

Piping to it

If stdin is not a terminal, it runs a line protocol instead — the same browser driven a line at a time, which is what makes it scriptable and testable:

printf '1\nq\n' | synfiles tui        # open row 1, quit

There, a bare row number opens, and the actions take the row as an argument: i 2, z 2, t 2, m 3 ~/dest, y 3 ~/dest, c ~/Pictures, / report, n/p for pages.

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.

Hovering over something

Rest the pointer on a file or a folder, in the list or in the icon view, and a panel says what it is:

stat reports the size of the directory entry for a folder — a few hundred bytes for a tree holding an ISO — so the panel runs the same walk Properties does and shows the answer as it climbs. It starts when the panel appears rather than when the pointer arrives, so crossing a grid of folders costs nothing, and it stops when the panel goes. A finished measurement is remembered until the listing is next re-read; after a copy, a delete or F5 it is measured again, because a remembered one would be wrong.

The disk figure leads because it is the one that costs you something: a tree of small files takes a block each and occupies far more room than it contains.

The type's name is shared-mime-info's own, read from the same database every other file manager on the machine reads, so a file is called the same thing here as it is anywhere else. It travels on the listing row, so hovering costs nothing — no lookup happens when the pointer arrives.

The panel waits half a second before it appears. Crossing a grid of icons to reach something else brushes a dozen of them on the way, and a panel on each would be a strobe. Scrolling or clicking takes it down.

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 records by construction. It has four tabs:

For a folder, the size is a walk of the tree: what it costs on disk, with what it contains beside it. Several selected items get the General tab only — how many, how much, and the disk they are on.

synfiles info photo.jpg
synfiles chmod 755 build.sh

Disk space is counted the same way as the sidebar's meters, so both show the same percentage for the same drive. Free is what an ordinary user can still write — the same figure df gives as Avail — and the reserve only root may use counts as used.

Permissions apply immediately. A symbolic link has no permissions of its own — the boxes show its target's and are greyed; change them on the target. Boxes are greyed too on a file you do not own, and the panel says who does. synfiles chmod takes an octal mode only and never follows a link.

Checksums use coreutils (md5sum, sha256sum and the rest), one at a time, and nothing is read until you ask. Paste a checksum from a download page into the box and the matching algorithm is calculated for you, followed by whether the file matches. A whole line out of a SHA256SUMS file works; case does not matter.

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.

Sizes

A folder's size is its contents, not the few hundred bytes of the directory entry that stat reports — which is the right answer to what stat was asked and the wrong answer to what anybody opening properties is asking.

synfiles du ~/Videos

It is a separate command from info, and deliberately: walking a large tree takes seconds, and folding it into info would freeze the properties panel on exactly the folders anyone would ask about. The panel draws first and the total arrives after, streaming as it counts, so there is a running number rather than "calculating…" and then a jump.

Two totals, because they disagree and answer different questions: bytes (apparent size — what has to fit when you copy it) and disk (blocks — a tree of tiny files takes more, a sparse file less). Hard links are counted once: a 4 GB file linked in twice is not 8 GB, and a package cache is full of them. Symlinks are never followed, which would double-count and hang on a cycle. Both totals agree with du -sb and du -s exactly, and the tests assert that against coreutils rather than against a remembered constant.

Closing the properties panel stops the walk. One left running lands its records in whatever folder is asked about next.

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.

The list keeps up on its own — plug a stick in, put a disc in a drive, or mount something from another program or a terminal, and the sidebar changes without a refresh. That takes three mechanisms, and none of them covers the other two. A device arriving, and a disc going into a drive, are kernel uevents, read from a netlink socket joined to udev's own multicast group, which needs no privileges; the kernel notices the disc at all only because it polls removable media a few times a minute. Mounting and unmounting emit no uevent whatsoever — nothing about the device changed, only what is being done with it — so the mount table is watched instead, with a poll() for POLLPRI on /proc/self/mountinfo, the one thing that file answers. And a network share is neither: gvfs hangs every share off a single FUSE mount, so mounting a second one does not touch the mount table either, and each share appears as a directory under /run/user/<uid>/gvfs — which is inotify's question. A burst is coalesced, because one stick is five or six uevents with a mount behind them and re-reading the list once per event would put six process spawns behind one plug. synfiles volumes --watch is the same stream on the command line.

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

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