# Guth
Guth is a native Rust file manager for fast, bounded local desktop workflows. It combines a compact Nautilus/Finder-style interface with asynchronous previews, explicit resource limits, undoable operations, and Linux desktop folder integration.
## Highlights
- Adaptive grid and list views with proportion-locked dimensional icons.
- Places sidebar, pinned folders, history, breadcrumbs, location entry, and current-folder search.
- Debounced, cancellable recursive search on one bounded background worker.
- Image thumbnails and optional `ffmpeg` video posters and hover strips.
- Default inline image, video, text, code, Markdown, CSV, and log previews.
- 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 preview surfaces instead of a permanent inspector pane.
- Persistent dark/light themes, view settings, bookmarks, background image, and opacity controls.
- 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`, `Home` / `End` | Move selection focus |
| `Shift` plus selection keys | Extend the selection range |
| `Space` | Toggle an inline preview |
| `Left` / `Right` in preview | Previous / next previewable item |
| `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, 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 line numbers and case-insensitive find.
Previewable files open inline by default when their plugin is enabled. `Shift+Enter` and **Open Externally** always route to the system application.
## 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 |
## License
Guth is available under the MIT License. See [`LICENSE`](LICENSE).