✓ Stable v0.1.0

garfield

Modern file explorer for the gardesk desktop

garfield is a file explorer designed for the gardesk ecosystem. It features tabbed browsing, split panes, multiple view modes (grid, list, column), thumbnails and previews, undo/redo for file operations, trash support, and XDG Desktop Portal integration for native file picker dialogs across applications.

View on GitHub Download RPM

🎯 RPM Available

Installation

garfield is available as an RPM package for Fedora and RHEL-compatible distributions.

Using DNF (Recommended)

$sudo dnf config-manager --add-repo https://repos.musicsian.com/musicsian.repo

$sudo dnf install garfield

Building from Source

$git clone https://github.com/espadon/gardesk.git

$cd gardesk/garfield

$cargo build --release

$sudo cp target/release/garfield /usr/local/bin/

$sudo cp target/release/garfieldctl /usr/local/bin/

$sudo cp target/release/garfield-portal /usr/local/bin/

Quick Start

Launch garfield to browse your files:

Basic Usage

$# Open home directory

$garfield

$# Open a specific directory

$garfield /path/to/directory

$# Open current directory

$garfield .

File Picker Mode

garfield can be used as a file picker dialog:

$# Open file picker

$garfield --picker

$# Pick directories only

$garfield --picker --directory

$# Allow multiple selection

$garfield --picker --multiple

$# Filter by file type

$garfield --picker --filter "*.rs;*.toml"

$# Save file dialog

$garfield --picker --save --save-filename "document.txt"

Keyboard Shortcuts

garfield is keyboard-driven. Here are the essential shortcuts:

Key	Action
`Enter`	Open selected item
`Backspace`	Go to parent directory
`Ctrl+T`	New tab
`Ctrl+W`	Close tab
`Ctrl+Tab`	Next tab
`Ctrl+Shift+Tab`	Previous tab
`Ctrl+C`	Copy selected files
`Ctrl+X`	Cut selected files
`Ctrl+V`	Paste files
`Ctrl+Z`	Undo last operation
`Ctrl+Shift+Z`	Redo operation
`Delete`	Move to trash
`Shift+Delete`	Delete permanently
`Ctrl+N`	New folder
`F2`	Rename
`Ctrl+H`	Toggle hidden files
`Ctrl+1`	Grid view
`Ctrl+2`	List view
`Ctrl+3`	Column view
`Ctrl+\`	Split pane horizontal
`Ctrl+-`	Split pane vertical
`?`	Show help
`Escape`	Cancel/close dialog

Features

Tabbed Browsing

Open multiple directories in tabs. Ctrl+T for new tab, Ctrl+W to close.

Split Panes

Split view horizontally or vertically for side-by-side browsing.

Multiple Views

Grid, list, and column (Miller columns) view modes.

Previews

Thumbnails for images, previews for images and PDFs in column view.

Undo/Redo

Undo file operations like move, copy, delete. Ctrl+Z/Ctrl+Shift+Z.

Portal Integration

XDG Desktop Portal backend for native file dialogs in any application.

Command Line Options

garfield accepts the following command-line options:

Option	Type	Default	Description
`PATH`	path	$HOME	Starting directory
`--picker, -p`	flag	false	Enable file picker mode
`--directory, -d`	flag	false	Select directories only (requires --picker)
`--multiple, -m`	flag	false	Allow multiple selection (requires --picker)
`--filter, -f`	string	none	File filter patterns (semicolon-separated, e.g., ".rs;.toml")
`--title, -t`	string	auto	Dialog title (requires --picker)
`--accept-label`	string	"Open"/"Save"	Custom accept button text
`--save`	flag	false	Enable save mode for SaveFile portal requests
`--save-filename`	string	none	Suggested filename for save mode
`--parent-window`	u32	none	Parent X11 window ID for transient-for hint

Picker Mode Examples

Open Single File

$garfield --picker

/home/user/selected-file.txt

Open Multiple Files

$garfield --picker --multiple

/home/user/file1.txt /home/user/file2.txt

Select Directory

$garfield --picker --directory

/home/user/projects

Save File with Suggestion

$garfield --picker --save --save-filename "report.pdf"

/home/user/Documents/report.pdf

Filter by Extension

$# Only show Rust source files

$garfield --picker --filter "*.rs"

/home/user/src/main.rs

$# Multiple extensions

$garfield --picker --filter "*.jpg;*.png;*.gif"

/home/user/images/photo.jpg

Environment Variables

GARFIELD_LOG - Set log level (trace, debug, info, warn, error)
XDG_RUNTIME_DIR - Directory for IPC socket

Overview

garfield is the file explorer for the gardesk desktop environment. It provides a modern, keyboard-driven interface for file management with features like tabs, split panes, and advanced previews. garfield also serves as the XDG Desktop Portal file chooser, providing native file dialogs for all applications.

Key components:

garfield - The file explorer application
garfieldctl - CLI control tool for IPC
garfield-portal - XDG Desktop Portal backend

garfield renders using gartk (the gardesk UI toolkit) with native X11 support, avoiding external framework dependencies like GTK or Qt.

Architecture

garfield uses a recursive pane tree architecture inspired by tiling window managers like i3 and bspwm. This enables unlimited nesting of split panes, each maintaining independent tabs and view modes.

Window Layout
├── Pane (Split: Horizontal, ratio=0.5)
│   ├── Pane (Leaf)
│   │   ├── Tab 1: /home/user/Documents
│   │   └── Tab 2: /home/user/Downloads
│   └── Pane (Split: Vertical, ratio=0.6)
│       ├── Pane (Leaf)
│       │   └── Tab 1: /home/user/Projects
│       └── Pane (Leaf)
│           └── Tab 1: /home/user/Music

Pane System

The pane system uses a recursive tree structure with two node types:

Leaf panes - Contain actual content (tabs with filesystem views). Each leaf maintains its own tab stack with an active tab index.
Split panes - Container nodes with two child panes arranged horizontally (side-by-side) or vertically (stacked). A ratio (0.0-1.0) determines proportional sizing.

Layout constants define the pane dimensions:

Constant	Value	Purpose
`MIN_PANE_SIZE`	100px	Minimum pane dimension
`DIVIDER_SIZE`	4px	Divider hit area width
`PANE_TOOLBAR_HEIGHT`	24px	Per-pane toolbar height
`VIEW_BUTTON_WIDTH`	24px	View mode button size

When splitting a pane, the new pane inherits the current directory and view mode from the focused pane. Closing a split pane transfers focus to its sibling, preventing closure when only one pane remains.

# Split operations
Ctrl+\    # Split current pane horizontally (side-by-side)
Ctrl+-    # Split current pane vertically (stacked)

# Focus navigation between panes
Focus moves via spatial navigation (left/right/up/down)
Similar to tmux panes or i3wm containers

Tab Management

Each leaf pane contains a vector of tabs with independent navigation state. Tab operations include:

Operation	Shortcut	Description
new_tab	`Ctrl+T`	Create tab cloning current directory
close_active_tab	`Ctrl+W`	Close focused tab
next_tab	`Ctrl+Tab`	Switch to next tab
prev_tab	`Ctrl+Shift+Tab`	Switch to previous tab
switch_tab(n)	`Ctrl+1-9`	Switch to tab by number
reorder_tab	Drag tab	Reorder tabs via drag-drop

Middle-clicking a file or folder opens it in a new tab, preserving the current view.

Vim-Style Navigation

garfield implements Vim-inspired keyboard navigation that adapts to the current view mode:

Key	Alt	Action
`h`	`Left`	Move left / go to parent directory
`j`	`Down`	Move selection down
`k`	`Up`	Move selection up
`l`	`Right`	Move right / enter directory
`g`	`Home`	Jump to first item
`G`	`End`	Jump to last item
`~`	-	Go to home directory
`/`	-	Go to root directory
`Enter`	-	Open selected item
`Backspace`	-	Go to parent directory
`r`	`F5`	Refresh directory listing
`H`	`Ctrl+H`	Toggle hidden files

Grid mode: All four directional keys move the cursor in a 2D grid. List mode: Vertical keys move selection; horizontal keys traverse directories.

Sidebar & Bookmarks

The sidebar provides quick access to XDG standard directories and user bookmarks. It uses the dirs crate for automatic path discovery.

XDG Places

Home - User home directory (~)
Desktop - XDG Desktop folder
Documents - XDG Documents folder
Downloads - XDG Downloads folder
Pictures - XDG Pictures folder
Music - XDG Music folder
Videos - XDG Videos folder
Trash - Freedesktop trash location
Recent Files - Recently accessed files

Bookmark System

Custom bookmarks are stored in ~/.config/garfield/bookmarks and support drag-drop reordering:

Add bookmark - Drag any directory to the sidebar
Reorder bookmarks - Drag bookmarks within the sidebar
Remove bookmark - Right-click and select "Remove"

The drag-drop system uses a 300ms hover delay to prevent accidental reordering, with visual drop highlight feedback showing the insertion point.

Sidebar layout: 28px item height, 8px padding for comfortable click targets while maintaining compact vertical space.

View Modes

garfield supports three view modes, switchable via the per-pane toolbar or keyboard shortcuts. Each pane maintains its own view mode independently.

Grid View (Ctrl+1)

Icons arranged in a responsive grid with thumbnails for images. Best for visual browsing of image directories or when you need to see many files at once.

Automatic thumbnail generation for supported image formats
4-directional cursor movement (h/j/k/l or arrows)
Grid columns adjust based on pane width
Thumbnail cache for fast subsequent access

List View (Ctrl+2)

Detailed list with sortable columns showing file metadata:

Name - Filename with icon
Size - Human-readable file size
Modified - Last modification timestamp
Type - MIME type or file extension

Click column headers to sort. Click again to reverse direction. Navigation uses vertical movement (j/k or up/down) with Enter/Backspace for directory traversal.

Miller Columns (Ctrl+3)

Three-pane hierarchical view following the Miller columns pattern popularized by macOS Finder. Each column shows one directory level:

Parent column (left) - Dimmed view showing siblings of current directory
Current column (center) - Active directory with selection highlight
Preview column (right) - Subdirectory contents or file preview

Column layout constants:

Row height: 24px per item
Minimum column width: 150px
Default layout: Width divided into thirds

Preview System

The preview column renders different content based on selection:

Directories - Show directory contents listing
Images - Rendered preview with Cairo surface caching
PDFs - First page preview with Cairo surface caching
Other files - File info (size, type, modified date)

Surface caching prevents re-rendering on every frame, maintaining smooth scrolling even with large image previews.

File Operations

Standard file operations with full undo/redo support. All destructive operations can be reversed.

Clipboard

Copy and move files using the clipboard. The clipboard integrates with X11 for inter-application copy/paste compatibility.

Ctrl+C - Copy selected files to clipboard
Ctrl+X - Cut selected files (move on paste)
Ctrl+V - Paste files to current directory
Ctrl+Shift+V - Paste with rename if collision

When pasting files that already exist in the destination, garfield automatically generates unique names by appending numbers (e.g., file.txt → file (1).txt).

Undo/Redo

File operations can be undone and redone, maintaining a history stack:

Ctrl+Z - Undo last operation
Ctrl+Shift+Z (or Ctrl+Y) - Redo undone operation

Supported undoable operations:

Move files/folders
Copy files/folders
Delete (restore from trash)
Rename files/folders
Create new folder
Create new file

Freedesktop Trash

garfield implements the Freedesktop.org Trash specification, moving deleted files to a recoverable location instead of permanent deletion.

Delete - Move selected files to trash
Shift+Delete - Permanently delete (with confirmation dialog)

Access the Trash from the sidebar to:

View trashed files with original locations
Restore files to their original path
Permanently delete individual files
Empty trash (delete all)

Trash location follows XDG specification: ~/.local/share/Trash/

Context Menu

Right-click to access context-sensitive actions. The menu adapts based on what's selected:

Context Types

File - Single file selected
Folder - Directory selected (adds "Open in New Tab")
Empty Space - Blank area (shows create options)
Multi-Selection - Multiple items selected (bulk actions)

Available Actions

Action	Shortcut	Description
Open	`Enter`	Open with default application
Open With...	-	Choose application (submenu)
Open in New Tab	Middle-click	Open folder in new tab
Copy	`Ctrl+C`	Copy to clipboard
Cut	`Ctrl+X`	Cut to clipboard
Paste	`Ctrl+V`	Paste from clipboard
Duplicate	`Ctrl+D`	Create copy in same directory
Rename	`F2`	Rename selected item
Move to Trash	`Delete`	Move to trash
Delete	`Shift+Del`	Permanent deletion
Properties	`Alt+Enter`	Show file properties dialog

Empty Space Actions

New File - Create empty file
New Folder - Create directory (Ctrl+N)
Paste - Paste clipboard contents
Refresh - Reload directory listing
View ▸ - Submenu for List/Grid/Columns modes
Sort By ▸ - Submenu for Name/Size/Date/Type sorting

Menu styling uses 28px item height, 200px minimum width, with 300ms hover delay before opening submenus to prevent accidental triggers.

Previews

garfield generates previews for supported file types, with caching for performance.

Thumbnails

Automatic thumbnail generation for images in grid view. The thumbnail system uses Triangle filter for high-quality downsampling with caching:

Thumbnails generated on first view
Cached to disk for fast subsequent access
Cache location: ~/.cache/garfield/thumbnails/
Automatic cache cleanup for deleted files

Image Preview

Full image preview in column view's preview pane. Uses Cairo surface caching to maintain smooth scrolling with large images.

Supported image formats:

PNG, JPEG, GIF (including animated), WebP
BMP, ICO, TIFF
PNM (PBM, PGM, PPM)
TGA, DDS, HDR

PDF Preview

First page preview for PDF documents in column view. Uses Poppler for rendering with Cairo surface caching.

Requirements:

$sudo dnf install poppler-utils

Search & Filter

garfield provides search and filtering capabilities for quickly locating files.

Fuzzy Search

Press / or Ctrl+F to open the search bar. Type to filter the current directory:

Case-insensitive substring matching
Results filtered incrementally as you type
Press Enter to navigate to first match
Press Escape to cancel search

Extension Filtering

In picker mode, the --filter flag restricts visible files by extension:

$# Single extension

$garfield --picker --filter "*.rs"

$# Multiple extensions (semicolon-separated)

$garfield --picker --filter "*.jpg;*.png;*.gif"

Empty filters match all files. Filters apply pattern matching with glob-style wildcards.

XDG Desktop Portal

garfield-portal implements the XDG Desktop Portal FileChooser interface, providing native file dialogs for all applications. When an application requests a file dialog, garfield opens in picker mode.

Setup

To use garfield as the system file chooser:

1. Install Portal Backend

$sudo dnf install garfield

2. Configure Portal

Create a portal configuration file:

# ~/.config/xdg-desktop-portal/portals.conf
[preferred]
default=garfield
org.freedesktop.impl.portal.FileChooser=garfield

3. Start Portal Daemon

$garfield-portal

INFO Starting garfield-portal INFO garfield-portal listening on D-Bus session bus

4. Autostart

Add to your window manager startup:

-- ~/.config/gar/init.lua
gar.spawn("garfield-portal")

Portal Methods

garfield-portal implements the following XDG portal methods:

OpenFile

Opens a file picker dialog. Supports options:

multiple - Allow multiple selection
directory - Select directories only
filters - File type filters
current_folder - Starting directory

SaveFile

Opens a save file dialog. Additional options:

current_name - Suggested filename
current_folder - Starting directory

D-Bus Interface

Service: org.freedesktop.impl.portal.desktop.garfield
Object: /org/freedesktop/portal/desktop
Interface: org.freedesktop.impl.portal.FileChooser

Methods:
  OpenFile(handle, app_id, parent_window, title, options)
  SaveFile(handle, app_id, parent_window, title, options)

Testing Portal

Test the portal with a GTK or Qt application:

$# Firefox should use garfield for file dialogs

$firefox

$# Or test with zenity

$zenity --file-selection

Control CLI: garfieldctl

The garfieldctl command-line tool controls a running garfield instance via IPC.

Commands

Command	Description
`open PATH [--new-tab]`	Open a directory in garfield (optionally in new tab)
`current-dir`	Get the current working directory
`status`	Get garfield status
`quit`	Quit garfield

Usage Examples

Open Directory in Running Instance

$garfieldctl open /home/user/Documents

$# Open in new tab

$garfieldctl open /home/user/Downloads --new-tab

Get Current Directory

$garfieldctl current-dir

"/home/user/Documents"

Check Status

$garfieldctl status

{ "running": true, "tabs": 3, "current_dir": "/home/user/Documents" }

IPC Protocol

garfield listens on a Unix domain socket at $XDG_RUNTIME_DIR/garfield.sock. Commands are sent as JSON lines.

Available Commands

Command	Description
`open`	Open a directory (path: string, new_tab: bool)
`current_dir`	Get current directory path
`status`	Get application status
`quit`	Quit the application

Integration with gar

Open directories from gar keybindings:

-- ~/.config/gar/init.lua

-- Launch garfield or focus existing instance
gar.bind("super+e", function()
    -- Try to show existing instance, or start new
    if os.execute("garfieldctl status > /dev/null 2>&1") then
        gar.spawn("garfieldctl open " .. os.getenv("HOME"))
    else
        gar.spawn("garfield")
    end
end)

Common Issues

No Thumbnails

If thumbnails aren't showing:

Ensure the image library dependencies are installed
Check permissions on the thumbnail cache directory
Try switching to grid view (Ctrl+1) which shows thumbnails

PDF Preview Not Working

PDF preview requires poppler-utils:

$sudo dnf install poppler-utils

Portal Not Working

If applications aren't using garfield for file dialogs:

1. Check Portal is Running

$pgrep garfield-portal

$# If not running, start it:

$garfield-portal &

2. Check Portal Configuration

$cat ~/.config/xdg-desktop-portal/portals.conf

[preferred] default=garfield

3. Restart xdg-desktop-portal

$systemctl --user restart xdg-desktop-portal

IPC Connection Refused

If garfieldctl can't connect to garfield:

$# Check if garfield is running

$pgrep garfield

$# Check socket exists

$ls $XDG_RUNTIME_DIR/garfield.sock

$# Remove stale socket if garfield not running

$rm -f $XDG_RUNTIME_DIR/garfield.sock

Debug Mode

Run garfield with verbose logging:

$GARFIELD_LOG=debug garfield

DEBUG Creating X11 window... DEBUG Loading sidebar places... ...

Getting Help

For further assistance:

Press ? in garfield to show keyboard shortcuts
Check the GitHub issues
Open a new issue with debug logs

garfield

Installation

Using DNF (Recommended)

Building from Source

Quick Start

Basic Usage

File Picker Mode

Keyboard Shortcuts

Features

Tabbed Browsing

Split Panes

Multiple Views

Previews

Undo/Redo

Portal Integration

Command Line Options

Picker Mode Examples

Open Single File

Open Multiple Files

Select Directory

Save File with Suggestion

Filter by Extension

Environment Variables

Overview

Architecture

Pane System

Tab Management

Navigation

Vim-Style Navigation

Sidebar & Bookmarks

XDG Places

Bookmark System

Breadcrumb & Address Bar

View Modes

Grid View (Ctrl+1)

List View (Ctrl+2)

Miller Columns (Ctrl+3)

Preview System

File Operations

Clipboard

Undo/Redo

Freedesktop Trash

Context Menu

Context Types

Available Actions

Empty Space Actions

Previews

Thumbnails

Image Preview

PDF Preview

Search & Filter

Fuzzy Search

Extension Filtering

XDG Desktop Portal

Setup

1. Install Portal Backend

2. Configure Portal

3. Start Portal Daemon

4. Autostart

Portal Methods

OpenFile

SaveFile

D-Bus Interface

Testing Portal

Control CLI: garfieldctl

Commands

Usage Examples

Open Directory in Running Instance

Get Current Directory

Check Status

IPC Protocol

Available Commands

Integration with gar

Common Issues

No Thumbnails

PDF Preview Not Working

Portal Not Working

1. Check Portal is Running

2. Check Portal Configuration

3. Restart xdg-desktop-portal