garfield-portal
XDG Desktop Portal backend for garfield file picker.
This daemon implements the org.freedesktop.impl.portal.FileChooser interface, allowing applications to use garfield as the system file picker dialog.
How It Works
When an application (GTK, Qt, Flatpak, etc.) requests a file dialog through the portal API:
xdg-desktop-portalreceives the request- It routes the request to
garfield-portalbased on configuration garfield-portalspawnsgarfield --pickerwith appropriate options- User selects files in garfield
- Selected paths are returned to the application as
file://URIs
Building
cargo build --release -p garfield-portal
Installation
System-wide (recommended)
cd garfield-portal
./install.sh
This installs:
- Binary to
/usr/local/bin/garfield-portal - Portal config to
/usr/share/xdg-desktop-portal/portals/garfield.portal - Systemd service to
/usr/lib/systemd/user/garfield-portal.service - Portal preferences to
/usr/share/xdg-desktop-portal/gar-portals.conf
User-only
./install.sh --user
Installs to ~/.local/ directories instead.
Enable the Service
After installation:
systemctl --user daemon-reload
systemctl --user enable --now garfield-portal
Testing
Run the test script:
./test-portal.sh
Or test with real applications:
# GTK apps
GTK_USE_PORTAL=1 gedit
GTK_USE_PORTAL=1 firefox
# Qt/KDE apps
QT_QPA_PLATFORMTHEME=xdgdesktopportal dolphin
# Flatpak apps (automatically use portals)
flatpak run org.gnome.TextEditor
Configuration
Making garfield the default
For the gar desktop environment, the installer creates gar-portals.conf:
[preferred]
default=garfield;gtk
org.freedesktop.impl.portal.FileChooser=garfield
Set XDG_CURRENT_DESKTOP=gar in your session to activate this configuration.
Manual configuration
To use garfield in other desktop environments, create ~/.config/xdg-desktop-portal/portals.conf:
[preferred]
default=garfield;gtk
Then restart xdg-desktop-portal:
systemctl --user restart xdg-desktop-portal
Uninstallation
./install.sh --uninstall # System-wide
./install.sh --uninstall-user # User-only
Troubleshooting
Check installation status
./install.sh --check
View logs
journalctl --user -u garfield-portal -f
Common issues
"Portal not found": Make sure garfield-portal is running:
systemctl --user status garfield-portal
"garfield not found": The garfield binary must be in PATH for picker mode to work.
Dialog doesn't appear: Check if DISPLAY is set and garfield can connect to X11.
D-Bus Interface
The portal implements org.freedesktop.impl.portal.FileChooser:
OpenFile(handle, app_id, parent_window, title, options)- Open file dialogSaveFile(handle, app_id, parent_window, title, options)- Save file dialogSaveFiles(handle, app_id, parent_window, title, options)- Save multiple files
See the XDG Desktop Portal documentation for full details.
View source
| 1 | # garfield-portal |
| 2 | |
| 3 | XDG Desktop Portal backend for garfield file picker. |
| 4 | |
| 5 | This daemon implements the `org.freedesktop.impl.portal.FileChooser` interface, allowing applications to use garfield as the system file picker dialog. |
| 6 | |
| 7 | ## How It Works |
| 8 | |
| 9 | When an application (GTK, Qt, Flatpak, etc.) requests a file dialog through the portal API: |
| 10 | |
| 11 | 1. `xdg-desktop-portal` receives the request |
| 12 | 2. It routes the request to `garfield-portal` based on configuration |
| 13 | 3. `garfield-portal` spawns `garfield --picker` with appropriate options |
| 14 | 4. User selects files in garfield |
| 15 | 5. Selected paths are returned to the application as `file://` URIs |
| 16 | |
| 17 | ## Building |
| 18 | |
| 19 | ```bash |
| 20 | cargo build --release -p garfield-portal |
| 21 | ``` |
| 22 | |
| 23 | ## Installation |
| 24 | |
| 25 | ### System-wide (recommended) |
| 26 | |
| 27 | ```bash |
| 28 | cd garfield-portal |
| 29 | ./install.sh |
| 30 | ``` |
| 31 | |
| 32 | This installs: |
| 33 | - Binary to `/usr/local/bin/garfield-portal` |
| 34 | - Portal config to `/usr/share/xdg-desktop-portal/portals/garfield.portal` |
| 35 | - Systemd service to `/usr/lib/systemd/user/garfield-portal.service` |
| 36 | - Portal preferences to `/usr/share/xdg-desktop-portal/gar-portals.conf` |
| 37 | |
| 38 | ### User-only |
| 39 | |
| 40 | ```bash |
| 41 | ./install.sh --user |
| 42 | ``` |
| 43 | |
| 44 | Installs to `~/.local/` directories instead. |
| 45 | |
| 46 | ### Enable the Service |
| 47 | |
| 48 | After installation: |
| 49 | |
| 50 | ```bash |
| 51 | systemctl --user daemon-reload |
| 52 | systemctl --user enable --now garfield-portal |
| 53 | ``` |
| 54 | |
| 55 | ## Testing |
| 56 | |
| 57 | Run the test script: |
| 58 | |
| 59 | ```bash |
| 60 | ./test-portal.sh |
| 61 | ``` |
| 62 | |
| 63 | Or test with real applications: |
| 64 | |
| 65 | ```bash |
| 66 | # GTK apps |
| 67 | GTK_USE_PORTAL=1 gedit |
| 68 | GTK_USE_PORTAL=1 firefox |
| 69 | |
| 70 | # Qt/KDE apps |
| 71 | QT_QPA_PLATFORMTHEME=xdgdesktopportal dolphin |
| 72 | |
| 73 | # Flatpak apps (automatically use portals) |
| 74 | flatpak run org.gnome.TextEditor |
| 75 | ``` |
| 76 | |
| 77 | ## Configuration |
| 78 | |
| 79 | ### Making garfield the default |
| 80 | |
| 81 | For the gar desktop environment, the installer creates `gar-portals.conf`: |
| 82 | |
| 83 | ```ini |
| 84 | [preferred] |
| 85 | default=garfield;gtk |
| 86 | org.freedesktop.impl.portal.FileChooser=garfield |
| 87 | ``` |
| 88 | |
| 89 | Set `XDG_CURRENT_DESKTOP=gar` in your session to activate this configuration. |
| 90 | |
| 91 | ### Manual configuration |
| 92 | |
| 93 | To use garfield in other desktop environments, create `~/.config/xdg-desktop-portal/portals.conf`: |
| 94 | |
| 95 | ```ini |
| 96 | [preferred] |
| 97 | default=garfield;gtk |
| 98 | ``` |
| 99 | |
| 100 | Then restart xdg-desktop-portal: |
| 101 | |
| 102 | ```bash |
| 103 | systemctl --user restart xdg-desktop-portal |
| 104 | ``` |
| 105 | |
| 106 | ## Uninstallation |
| 107 | |
| 108 | ```bash |
| 109 | ./install.sh --uninstall # System-wide |
| 110 | ./install.sh --uninstall-user # User-only |
| 111 | ``` |
| 112 | |
| 113 | ## Troubleshooting |
| 114 | |
| 115 | ### Check installation status |
| 116 | |
| 117 | ```bash |
| 118 | ./install.sh --check |
| 119 | ``` |
| 120 | |
| 121 | ### View logs |
| 122 | |
| 123 | ```bash |
| 124 | journalctl --user -u garfield-portal -f |
| 125 | ``` |
| 126 | |
| 127 | ### Common issues |
| 128 | |
| 129 | **"Portal not found"**: Make sure `garfield-portal` is running: |
| 130 | ```bash |
| 131 | systemctl --user status garfield-portal |
| 132 | ``` |
| 133 | |
| 134 | **"garfield not found"**: The `garfield` binary must be in PATH for picker mode to work. |
| 135 | |
| 136 | **Dialog doesn't appear**: Check if `DISPLAY` is set and garfield can connect to X11. |
| 137 | |
| 138 | ## D-Bus Interface |
| 139 | |
| 140 | The portal implements `org.freedesktop.impl.portal.FileChooser`: |
| 141 | |
| 142 | - `OpenFile(handle, app_id, parent_window, title, options)` - Open file dialog |
| 143 | - `SaveFile(handle, app_id, parent_window, title, options)` - Save file dialog |
| 144 | - `SaveFiles(handle, app_id, parent_window, title, options)` - Save multiple files |
| 145 | |
| 146 | See the [XDG Desktop Portal documentation](https://flatpak.github.io/xdg-desktop-portal/) for full details. |