Beta

garfield

File Manager

A multi-paned graphical file manager with tabbed navigation, multiple view modes, and full file operations. garfield features list, grid, and column views, split-pane layouts, undo/redo history, Freedesktop trash support, and IPC control via garfieldctl.

View on GitHub Install

garfield file manager - bookmarks sidebar

Features

List, grid, and column view modes
Multi-tab navigation with keyboard shortcuts
Horizontal and vertical split panes
Copy, cut, paste with conflict resolution
Freedesktop trash support with metadata
Undo/redo for all file operations (100 levels)
Inline rename with cursor editing
Bookmarks sidebar with drag-and-drop
XDG places and auto-detected mounted volumes
Context menu with sort, open-with, and file actions
garfield-portal: XDG Desktop Portal file picker backend
Picker mode for file/folder/save dialogs
Built-in help modal (F1)
IPC control via garfieldctl
Address bar for direct path editing

Quick Start Guide

Get up and running with garfield in a few steps. This guide covers installation, launching, and essential keybindings.

1. Installation

Install garfield using the unified installer or build from source:

terminal

$ curl -fsSL https://gar.musicsian.com/install.sh | bash -s -- --component=garfield # Install via script

$ cd ~/.local/src/gardesk/garfield && cargo build --release # Or build from source

2. Launch

Run garfield from a terminal or application launcher:

terminal

$ garfield # Open home directory

$ garfield /path/to/directory # Open specific directory

$ garfield ~/Documents # Example: open Documents

3. Essential Keybindings

Key	Action
Up/Down or k/j	Navigate files
Enter	Open file/directory
Backspace	Go to parent directory
Ctrl+C / Ctrl+X	Copy / Cut
Ctrl+V	Paste
Delete	Move to trash
F2	Rename
Ctrl+T	New tab
Ctrl+Tab / Ctrl+Shift+Tab	Next / previous tab
Ctrl+1/2/3	List/Grid/Column view
H	Toggle hidden files
Ctrl+Z / Ctrl+Y	Undo / Redo
F1	Show help
q or Escape	Quit

4. View Modes

Switch between view modes with keyboard shortcuts or toolbar buttons:

Ctrl+1 - List view with columns (name, size, date)
Ctrl+2 - Grid view with icons/thumbnails
Ctrl+3 - Column view (macOS Finder-style)
H - Toggle hidden files

5. Split Panes

Create split layouts for side-by-side file management:

Ctrl+Shift+H - Split horizontally
Ctrl+Shift+V - Split vertically
Ctrl+Shift+Arrow - Focus adjacent pane
Ctrl+Shift+W - Close focused pane

Configuration

garfield works out of the box with sensible defaults. User configuration is primarily through bookmarks.

Bookmarks

Bookmarks are stored as a plain text file with one path per line:

~/.config/garfield/bookmarks

/home/user/Projects
/home/user/Music
/mnt/external
/var/log

Managing Bookmarks

Ctrl+D - Add current directory as bookmark
Drag folder to sidebar - Add bookmark via drag-and-drop
Drag bookmark on sidebar - Reorder bookmarks

XDG Places

The sidebar automatically includes standard XDG directories:

Home (~)
Desktop
Documents
Downloads
Trash

Trash Location

garfield uses the Freedesktop trash specification:

~/.local/share/Trash/files/ - Trashed files
~/.local/share/Trash/info/ - Metadata (.trashinfo files)

Overview

garfield is a graphical file manager for the gardesk desktop suite. It provides a modern, multi-paned interface with tabbed navigation, multiple view modes, and comprehensive file operations.

Architecture

The garfield workspace consists of three crates:

garfield - Main file manager application
garfieldctl - Command-line control client
garfield-ipc - Shared IPC protocol library

Key Modules

app.rs - Event loop and state management
core/ - File system operations
ui/ - GUI components (sidebar, toolbar, views)

View Modes

garfield supports three distinct view modes, each optimized for different use cases.

Mode	Key	Best For
List	Ctrl+1	Detailed file info (size, date)
Grid	Ctrl+2	Visual browsing with icons
Column	Ctrl+3	Hierarchical navigation

Keyboard Navigation

Key	Action
Up/Down or k/j	Move selection up/down
Left/Right or h/l	Grid nav or parent/enter
Enter	Open file/directory
Backspace	Go to parent directory
Home or g	Go to first entry
End or G	Go to last entry
Page Up/Down	Page-based navigation
~	Go to home directory
/	Go to root directory
r or F5	Refresh current directory
Ctrl+Shift+F	Create new file
Ctrl+Shift+D	Duplicate selected
Ctrl+L	Focus address bar

History Navigation

garfield maintains navigation history per tab (up to 100 entries).

Key	Action
Alt+Left	Go back in history
Alt+Right	Go forward in history

The toolbar also includes back/forward buttons for mouse navigation.

Tabs

Open multiple directories in separate tabs within each pane.

Key	Action
Ctrl+T	New tab
Ctrl+W	Close active tab
Ctrl+Tab	Next tab
Ctrl+Shift+Tab	Previous tab
Alt+1 to Alt+9	Jump to tab N
Middle-Click (tab)	Close clicked tab

Split Panes

Create split layouts for side-by-side browsing. Panes form a binary tree structure allowing arbitrary layouts.

Key	Action
Ctrl+Shift+H	Split horizontally
Ctrl+Shift+V	Split vertically
Ctrl+Shift+W	Close focused pane
Ctrl+Shift+Arrow	Focus adjacent pane
Double-click divider	Equalize split sizes

Copy/Cut/Paste

Key	Action
Ctrl+C	Copy selected files
Ctrl+X	Cut selected files
Ctrl+V	Paste files

Features

Full recursive directory copy
Cross-filesystem move support (copy + delete fallback)
Conflict resolution dialog for existing files
Multi-file operations with progress tracking

Trash & Delete

Key	Action
Delete	Move to trash
Shift+Delete	Delete permanently (with confirmation)

Freedesktop Trash

Trash follows the Freedesktop specification with full metadata:

Original path stored in .trashinfo metadata
Deletion timestamp recorded
Files can be restored from trash

Rename

Press F2 to start inline rename on the selected file.

Inline Editing

Key	Action
F2	Start rename
Enter	Confirm rename
Escape	Cancel rename
Left/Right	Move cursor
Backspace	Delete before cursor
Delete	Delete after cursor

The filename is pre-selected without extension for files with extensions.

Selection

garfield supports multi-selection with keyboard and mouse modifiers.

Action	Effect
Click	Select single item
Ctrl+Click	Toggle item in selection
Shift+Click	Extend selection to item
Shift+Up/Down	Extend selection with arrows
Ctrl+A	Select all items

Undo/Redo

garfield maintains a history of file operations (up to 100 levels).

Key	Action
Ctrl+Z	Undo last operation
Ctrl+Y	Redo undone operation

Supported Operations

Copy
Move/Cut
Trash
Rename
Create Directory

Bookmarks

Quick-access shortcuts to frequently visited directories.

Action	How
Add bookmark	Ctrl+D
Add via drag	Drag folder to sidebar
Reorder	Drag bookmark up/down
Navigate	Click bookmark

Bookmarks are saved to ~/.config/garfield/bookmarks.

Sidebar

The sidebar provides quick access to XDG places and user bookmarks.

Key	Action
Ctrl+B	Toggle sidebar visibility

XDG Places

Home
Desktop
Documents
Downloads
Trash

Mounted Volumes

The sidebar auto-detects mounted volumes from /media, /mnt, and ~/.local/media and displays them as a separate section below XDG places and bookmarks.

Conflict Resolution

When pasting files that already exist, garfield shows a conflict dialog with options:

Option	Effect
Skip	Don't overwrite, keep existing
Replace	Delete existing, paste new
Keep Both	Rename new file (e.g., "file (1).txt")
Apply to All	Use same choice for remaining conflicts

File Picker Portal

garfield includes garfield-portal, a D-Bus service implementing the org.freedesktop.impl.portal.FileChooser interface. This routes system file picker dialogs (from GTK, Qt, and other applications) through garfield.

How It Works

garfield-portal registers on the D-Bus session bus
When an application requests a file dialog, garfield-portal spawns garfield in picker mode
The user selects files using the full garfield interface
Selected paths are returned to the requesting application

Picker Mode CLI Flags

Flag	Description
--picker, -p	Enable file picker mode
--directory, -d	Directory-only selection
--multiple, -m	Allow multiple selection
--filter, -f	File filter patterns (semicolon-separated, e.g. ".rs;.toml")
--title, -t	Custom dialog title
--save	Save mode (single selection with filename input)
--save_filename	Suggested filename for save mode
--parent_window	X11 window ID for transient-for hint

Running the Portal

terminal

$ garfield-portal # Start as D-Bus service

$ garfield-portal --foreground # Run in foreground for debugging

garfield-portal is typically run as a systemd user service and starts automatically when applications request file dialogs.

IPC Protocol

garfield exposes a JSON-based IPC protocol over Unix socket for scripting and external control.

Socket Location

$ echo $XDG_RUNTIME_DIR/garfield.sock # Default socket path

$ ls -la ${XDG_RUNTIME_DIR:-/tmp}/garfield.sock # Check if running

garfieldctl Commands

Command	Arguments	Description
open	<PATH> [--new-tab]	Open directory
current-dir	-	Get current directory
status	-	Get app status (tabs, selection)
quit	-	Close garfield

Examples

$ garfieldctl open /home/user/Documents # Navigate to Documents

$ garfieldctl open /tmp --new-tab # Open in new tab

$ garfieldctl current-dir # Query current directory

$ garfieldctl status # Get app status

JSON Protocol

Request format

{"command": "open", "path": "/home/user", "new_tab": false}
{"command": "current_dir"}
{"command": "status"}
{"command": "quit"}

Response format

// Success
{"success": true, "data": {"current_dir": "/home/user"}}

// Status response
{"success": true, "data": {
  "current_dir": "/home/user/Documents",
  "tab_count": 3,
  "selection_count": 2
}}

// Error
{"success": false, "error": "Directory not found"}

File/Folder Picker

The IPC protocol also supports file picker dialogs for other applications:

// File picker
{
  "command": "file_picker",
  "title": "Select Files",
  "start_dir": "/home/user",
  "filters": ["*.rs", "*.txt"],
  "multiple": true
}

// Folder picker
{
  "command": "folder_picker",
  "title": "Select Directory",
  "start_dir": "/home/user"
}

Releases

v0.1.0 Latest

Source (.tar.gz)

Back to home

garfield

Features

Quick Start Guide

1. Installation

2. Launch

3. Essential Keybindings

4. View Modes

5. Split Panes

Configuration

Bookmarks

Managing Bookmarks

XDG Places

Trash Location

Overview

Architecture

Key Modules

View Modes

List View

Columns

Navigation

Grid View

Navigation

Icon Size

Column View

How It Works

Navigation

Keyboard Navigation

History Navigation

Tabs & Panes

Tabs

Split Panes

File Operations

Copy/Cut/Paste

Features

Trash & Delete

Freedesktop Trash

Rename

Inline Editing

New Folder

Selection

Undo/Redo

Supported Operations

Bookmarks

Sidebar

XDG Places

Mounted Volumes

Conflict Resolution

Context Menu

File Actions

Directory Actions

Sort Options

File Picker Portal

How It Works

Picker Mode CLI Flags

Running the Portal

Common Workflows

Batch File Operations

Quick Directory Switching

Recovering from Mistakes

Bookmark Workflow

Address Bar Navigation

IPC Protocol

Socket Location

garfieldctl Commands

Examples

JSON Protocol

File/Folder Picker

Troubleshooting

garfield won't start

garfieldctl: connection refused

Bookmarks not saving

Trash not working

Move operation fails across filesystems

Rendering issues

Debug logging