# Guth
Guth is a native Rust file manager for fast, bounded local desktop workflows. It combines a compact professional interface with asynchronous previews, explicit resource limits, undoable operations, and Linux desktop folder integration.
## Highlights
- Responsive, viewport-virtualized grid and list views with a cohesive, proportion-locked vector icon family.
- Places sidebar, pinned folders, history, breadcrumbs, location entry, and current-folder search.
- Debounced, cancellable recursive search on one bounded background worker, with containing-folder context for every result.
- Image thumbnails and optional `ffmpeg` video posters and hover strips.
- Adaptive inline image, video, text, code, Markdown, CSV, and log previews with file metadata, navigation, zoom, and explicit loading or failure states.
- Multi-selection, range selection, copy, cut, paste, duplicate, rename, trash, permanent delete, and undo.
- Drag folders onto Pinned Folders, files into the current folder, or selected entries onto Trash.
- Floating Properties, Settings, and input-isolated quick-look previews instead of a permanent inspector pane.
- Original Guth application artwork plus persistent Guth/Studio themes, view settings, bookmarks, and restrained backgrounds.
- Explicit limits for scans, searches, operations, thumbnails, previews, launchers, history, logs, and undo state.
## Install
Install the published binary with Cargo:
```bash
cargo install guth
```
Run Guth in your home folder or open a specific directory:
```bash
guth
guth /path/to/folder
```
### Linux Folder Integration
Install Guth's embedded desktop entry for file-manager discovery and **Open With** support:
```bash
guth --install-desktop
```
Install the entry and make Guth the default handler for `inode/directory`:
```bash
guth --set-default
```
`--set-default` intentionally invokes `xdg-mime`. `--install-desktop` only invokes it when migrating an existing KnottFiles default association to Guth; normal startup never changes the default file manager.
The installed desktop entry uses the exact UTF-8 executable path returned by the running Guth binary, so it does not depend on the desktop session inheriting Cargo's `PATH`.
## Keyboard Shortcuts
| `F5` or `Ctrl+R` / `Cmd+R` | Refresh current folder |
| `Alt+Left` / `Alt+Right` | Navigate back / forward |
| `Alt+Up` or `Backspace` | Open parent folder |
| `Ctrl+L` / `Cmd+L` | Focus folder location entry |
| `Ctrl+F` / `Cmd+F` | Focus file search or text-preview find |
| `Esc` | Cancel a dialog/location, close preview, clear search, or clear selection |
| `Up` / `Down` | Move selection focus by row in lists and grids |
| `Left` / `Right` in grid view | Move selection focus by item |
| `Home` / `End` | Move selection focus to the first / last item |
| `Shift` plus selection keys | Extend the selection range |
| `Space` | Toggle an inline preview |
| `Left` / `Right` in preview | Previous / next previewable item |
| `Up` / `Down` in preview | Zoom in / out |
| `Enter` | Open a folder or supported inline preview |
| `Shift+Enter` | Open with the system default application |
| `Alt+Enter` or `Ctrl+I` / `Cmd+I` | Toggle Properties |
| `Ctrl+,` / `Cmd+,` | Toggle Settings |
| `Ctrl+A` / `Cmd+A` | Select all visible items |
| `Ctrl+C`, `Ctrl+X`, `Ctrl+V` | Copy, cut, paste |
| `Ctrl+D` / `Cmd+D` | Duplicate selection |
| `Ctrl+Z` / `Cmd+Z` | Undo the latest undoable operation |
| `Ctrl+N` / `Cmd+N` | Create a folder |
| `Ctrl+H` / `Cmd+H` | Toggle hidden files |
| `F2` | Rename one selected item |
| `Delete` | Move selection to trash |
| `Shift+Delete` | Confirm permanent deletion |
## Knotwork Previews
Guth includes the `Knotwork` registry with two bundled preview plugins:
- **Knotlook Media** uses one active image worker plus the latest pending request, preserves source dimensions, shows transparency correctly, and uses the thumbnail pipeline for video posters and strips.
- **Knotread Text** uses one active reader plus the latest pending request, reads at most 2 MiB and 2,000 lines, detects likely binary files, labels truncation/lossy UTF-8, and provides a compact line-number and case-insensitive find toolbar.
Previewable files open inline by default when their plugin is enabled. `Shift+Enter` and **Open Externally** always route to the system application.
The viewer supports toolbar and arrow-key zoom, mouse-wheel zoom over image/video stages, drag-to-pan above the fitted scale, and double-click reset to the fitted view.
Media and text scaling are independent, and preview shortcuts act only on the displayed file rather than the file canvas behind it.
The primary file canvas lays out only viewport rows, uses rendered font measurements for middle elision, and adapts list metadata columns to the available width. Keyboard movement keeps the focused item visible, and sort changes reorder the loaded snapshot without rescanning the directory.
## Filesystem Safety
- Ordinary delete moves items to the Freedesktop local trash.
- Permanent delete requires an explicit confirmation click and cannot be accepted with `Enter`.
- Destination paths inside a copied/moved source are rejected to prevent recursive self-copy.
- Conflicting destinations receive `copy`, `copy 2`, and similar names instead of overwriting data.
- Operation source count, traversal item count, and traversal depth are bounded.
- Undo is bounded and best-effort. A failed multi-item undo may have applied earlier items, so the consumed action is not re-queued with stale paths.
- Operation and thumbnail worker disconnects are recovered instead of wedging the UI.
- External child processes are reaped through a bounded watcher pool.
## Renderer Options
Guth uses `egui_glow` by default and also compiles the WGPU renderer:
```bash
guth --renderer glow
guth --renderer glow --gles 2
guth --renderer wgpu --wgpu-backend vulkan,gl --wgpu-power high
guth --gpu preferred
guth --no-vsync
```
Environment equivalents:
- `GUTH_RENDERER=glow|wgpu`
- `GUTH_GPU=required|preferred|off`
- `GUTH_GLES=1|2`
- `GUTH_WGPU_BACKEND=vulkan,gl,metal,dx12,primary,secondary`
- `GUTH_WGPU_POWER=high|low`
- `GUTH_FRAME_LATENCY=<positive integer>`
- `GUTH_VSYNC=true|false`
## Configuration
Preferences are stored at `$XDG_CONFIG_HOME/guth/preferences.conf`, or `~/.config/guth/preferences.conf` when `XDG_CONFIG_HOME` is unset. Pinned folders are stored beside it in `bookmarks.conf`.
The configuration is intentionally plain text. Unknown palette values fall back to the professional dark theme.
On launch, Guth copies missing `knottfiles/preferences.conf` and `knottfiles/bookmarks.conf` files into the Guth configuration directory without overwriting Guth files. Missing files are retried on later launches.
## Build And Verify
```bash
cargo run -- /path/to/folder
cargo fmt --check
cargo test --all-targets
cargo clippy --all-targets -- -D warnings
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps
cargo package --list
```
The crates.io payload is restricted in `Cargo.toml` to Rust sources, desktop data, `README.md`, `LICENSE`, and Cargo manifests. Local notes, generated targets, editor state, screenshots, and session artifacts are not packaged.
## Project Layout
| `src/app.rs` | Guth application state, layout, dialogs, shortcuts, previews, and interaction flow |
| `src/fs_model.rs` | Scanning, places, breadcrumbs, sorting, search, validation, and metadata |
| `src/ops.rs` | Threaded operations, trash, launchers, progress, and undo |
| `src/plugins.rs` | Knotwork registry and bundled plugin descriptors |
| `src/theme.rs` | Native visual helpers and content background rendering |
| `src/thumbnails.rs` | Bounded thumbnail cache, image decoding, and optional ffmpeg integration |
| `data/io.github.tknott95.Guth.desktop` | Linux desktop and directory MIME metadata |
| `data/io.github.tknott95.Guth.svg` | Original scalable Guth application icon |
## License
Guth is available under the MIT License. See [`LICENSE`](LICENSE).