lashman/driftwood
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Rewrite README with better header and project framing

Browse Source
This commit is contained in:
lashman
2026-03-01 13:12:45 +02:00
parent 58d8b44866
commit 09ef0f48e0
1 changed files with 130 additions and 88 deletions
Download Patch File Download Diff File Expand all files Collapse all files

218
README.md
View File

@@ -1,36 +1,56 @@
# <img src="https://img.shields.io/badge/CC0-1.0-blue" alt="License: CC0-1.0" /> Driftwood <div align="center">
### A friendly, modern AppImage manager for Linux desktops # :evergreen_tree: Driftwood
Driftwood makes it easy to find, install, organize, update, and keep safe all **Your apps. Your computer. No middleman.**
your AppImage apps - without needing to use the terminal. It's built for people
who just want their apps to work, and it fits right in with the GNOME desktop.
If you've ever downloaded an AppImage file and wondered "now what do I do with A friendly, modern AppImage manager for Linux desktops -
this?", Driftwood is for you. built by the community, owned by no one.
<br />
![License: CC0-1.0](https://img.shields.io/badge/license-CC0--1.0-bb4444?style=flat-square)
![Built with Rust](https://img.shields.io/badge/built%20with-Rust-d4652a?style=flat-square)
![GTK4 + libadwaita](https://img.shields.io/badge/GTK4-libadwaita-4a86cf?style=flat-square)
![WCAG 2.2 AAA](https://img.shields.io/badge/WCAG%202.2-AAA-228833?style=flat-square)
![No Telemetry](https://img.shields.io/badge/telemetry-none-778899?style=flat-square)
<br />
*No accounts. No tracking. No data harvested. No profit motive.*
*Just a tool that helps you manage your apps, and gets out of the way.*
</div>
--- ---
## :sparkles: What is Driftwood? ## :sparkles: What is Driftwood?
**Driftwood is a graphical app manager for AppImages.** AppImages are portable **Driftwood is a graphical app manager for AppImages.** AppImages are portable
Linux applications that come as a single file - no installation needed. But Linux applications that come as a single file - no installation needed, no
managing them by hand (making them show up in your app menu, checking for package manager required, no root access, no corporate app store standing between
updates, knowing if they're safe) can be confusing, especially if you're new to you and the software you want to run.
Linux.
Driftwood handles all of that for you with a clean, easy-to-use interface. But managing AppImages by hand can be confusing. Making them show up in your app
menu, checking for updates, knowing if they're safe - that's a lot of work,
especially if you're new to Linux.
Driftwood handles all of that for you with a clean, easy-to-use interface. It
runs entirely on your machine - nothing is sent anywhere, nothing is collected,
nothing is monetized.
--- ---
## :raising_hand: Who is this for? ## :raising_hand: Who is this for?
- **New Linux users** who want a simple way to manage AppImage apps - **People new to Linux** who want a simple, welcoming way to manage their apps
- **Anyone who downloads AppImages** and wants them organized, updated, and - **Anyone who downloads AppImages** and wants them organized, updated, and
integrated into their desktop integrated into their desktop without friction
- **Privacy-conscious users** who want to know what libraries their apps bundle - **People who care about privacy** and want to know exactly what their apps
and whether any have known security issues contain and whether any bundled libraries have known security issues
- **Power users** who want a full CLI alongside the graphical interface - **People who believe software should be accessible to everyone** - Driftwood
meets WCAG 2.2 AAA accessibility standards
- **Power users** who want a full command-line interface alongside the GUI
--- ---
@@ -42,7 +62,7 @@ app. It has three main views:
| View | What it does | | View | What it does |
|------|-------------| |------|-------------|
| **Installed** | Shows all your AppImages in a grid or list with status badges | | **Installed** | Shows all your AppImages in a grid or list with status badges |
| **Catalog** | Browse and discover new AppImage apps to download | | **Catalog** | Browse and discover new AppImage apps from the community |
| **Updates** | See which apps have newer versions and update them | | **Updates** | See which apps have newer versions and update them |
Click any app to see its full details - version info, security status, disk Click any app to see its full details - version info, security status, disk
@@ -57,30 +77,31 @@ usage, screenshots, and more.
- **Automatic scanning** - Driftwood finds all AppImage files in your chosen - **Automatic scanning** - Driftwood finds all AppImage files in your chosen
folders (like `~/Applications` or `~/Downloads`) folders (like `~/Applications` or `~/Downloads`)
- **Grid and list views** - See your apps as cards with icons, or as a detailed - **Grid and list views** - See your apps as cards with icons, or as a detailed
list list - whichever you prefer
- **Search and sort** - Find apps by name, sort by name, size, or when you added - **Search and sort** - Find apps by name, sort by name, size, or when you added
them them
- **Tags** - Label your apps with custom tags and filter by them - **Tags** - Label your apps with custom tags and filter by them
- **Selection mode** - Select multiple apps at once for batch actions - **Selection mode** - Select multiple apps at once for batch actions
- **Drag and drop** - Drop an AppImage file onto the window to add it - **Drag and drop** - Drop an AppImage file onto the window to add it
### :globe_with_meridians: App Catalog (Store) ### :globe_with_meridians: App Catalog
- **Browse apps** - Discover AppImage apps from the community catalog - **Browse community apps** - Discover AppImage apps shared by developers and
communities - no walled garden, no curation fees, no gatekeeping
- **Category filters** - Browse by Audio, Games, Graphics, Development, and more - **Category filters** - Browse by Audio, Games, Graphics, Development, and more
- **Featured apps** - A rotating carousel of highlighted apps - **Featured apps** - A rotating carousel of highlighted apps
- **Search** - Find apps by name across the entire catalog - **Search** - Find apps by name across the entire catalog
- **App details** - See descriptions, screenshots, star counts, and download - **App details** - See descriptions, screenshots, star counts, and download
numbers numbers
- **One-click install** - Download and add apps right from the catalog - **One-click install** - Download and add apps directly from the catalog
### :arrow_up: Updates ### :arrow_up: Updates
- **Check for updates** - Scan all your apps for newer versions with one click - **Check for updates** - Scan all your apps for newer versions with one click
- **Update all at once** - Or update apps one by one - **Update all at once** - Or update apps individually, your choice
- **Release notes** - See what changed in each new version - **Release notes** - See what changed in each new version before you decide
- **Automatic backups** - Optionally save old versions before updating, so you - **Automatic backups** - Optionally save old versions before updating, so you
can go back if something breaks can roll back if something breaks
- **Multiple update sources** - Works with GitHub Releases, GitLab Releases, - **Multiple update sources** - Works with GitHub Releases, GitLab Releases,
zsync delta updates, and OCS feeds zsync delta updates, and OCS feeds
@@ -92,10 +113,14 @@ usage, screenshots, and more.
- **Autostart** - Set apps to launch automatically when you log in - **Autostart** - Set apps to launch automatically when you log in
- **Custom launch options** - Add command-line arguments or environment variables - **Custom launch options** - Add command-line arguments or environment variables
per app per app
- **Undo everything** - Remove any app from your menu just as easily - **Fully reversible** - Remove any app from your menu just as easily as you
added it. Every change Driftwood makes to your system is tracked and can be
undone
### :shield: Security ### :shield: Security
Your apps shouldn't be a black box. Driftwood helps you see what's inside.
- **Vulnerability scanning** - Extracts the shared libraries bundled inside each - **Vulnerability scanning** - Extracts the shared libraries bundled inside each
AppImage and checks them against the OSV.dev vulnerability database AppImage and checks them against the OSV.dev vulnerability database
- **CVE details** - Shows the severity (Critical, High, Medium, Low), CVSS - **CVE details** - Shows the severity (Critical, High, Medium, Low), CVSS
@@ -113,35 +138,35 @@ usage, screenshots, and more.
- **FUSE detection** - Checks whether your system can mount AppImages and tells - **FUSE detection** - Checks whether your system can mount AppImages and tells
you exactly what to install if it can't you exactly what to install if it can't
- **Guided FUSE setup** - A step-by-step wizard that shows you the right install - **Guided FUSE setup** - A step-by-step wizard that shows you the right install
command for your distribution command for your distribution - no searching forums, no guesswork
- **Wayland compatibility** - Detects whether you're running Wayland or X11 and - **Wayland compatibility** - Detects whether you're running Wayland or X11 and
flags any compatibility concerns flags any compatibility concerns
- **Fallback launching** - If FUSE isn't available, Driftwood can extract and run - **Fallback launching** - If FUSE isn't available, Driftwood can extract and run
AppImages directly AppImages directly - you're never locked out of your own software
### :broom: Cleanup and Disk Management ### :broom: Cleanup and Disk Management
- **Duplicate finder** - Detects when you have multiple copies of the same app - **Duplicate finder** - Detects when you have multiple copies of the same app
or different versions taking up space, and shows how much space you'd save or different versions taking up space, and shows how much you'd save
- **Disk footprint** - Shows config, cache, and data folders each app has created - **Disk footprint** - Shows config, cache, and data folders each app has created
on your system on your system - no hidden clutter
- **Cleanup wizard** - A guided walkthrough that finds orphaned desktop entries, - **Cleanup wizard** - A guided walkthrough that finds orphaned desktop entries,
leftover caches, and duplicates, then lets you choose what to remove leftover caches, and duplicates, then lets you choose what to remove
- **Orphan cleanup** - Finds and removes menu entries for AppImages that no - **Orphan cleanup** - Finds and removes menu entries for AppImages that no
longer exist on disk longer exist on disk
### :1234: Dashboard ### :bar_chart: Dashboard
- **System overview** - Quick health check showing FUSE status, Wayland status, - **System overview** - A quick health check showing FUSE status, Wayland status,
total apps, storage used, and apps needing updates total apps, storage used, and apps needing updates
- **At-a-glance stats** - See everything about your AppImage setup in one place - **At-a-glance stats** - Everything about your AppImage setup in one place
### :gear: Preferences ### :gear: Preferences
- **Appearance** - Follow your system's light/dark theme, or force one - **Appearance** - Follow your system's light/dark theme, or pick one
- **Scan directories** - Choose which folders Driftwood watches for AppImages - **Scan directories** - Choose which folders Driftwood watches for AppImages
- **Update settings** - Configure automatic update checking, backup behavior, - **Update settings** - Configure automatic update checking, backup behavior,
and retention periods and how long to keep old versions
- **Security settings** - Enable automatic scanning, notifications, and set a - **Security settings** - Enable automatic scanning, notifications, and set a
GitHub token for higher API rate limits GitHub token for higher API rate limits
- **Catalog settings** - Toggle automatic metadata enrichment and removable media - **Catalog settings** - Toggle automatic metadata enrichment and removable media
@@ -149,26 +174,31 @@ usage, screenshots, and more.
### :lock: Sandboxing ### :lock: Sandboxing
- **Firejail support** - Launch apps inside a Firejail sandbox for extra security - **Firejail support** - Launch apps inside a Firejail sandbox for extra
isolation
- **Per-app profiles** - Each app can have its own sandbox configuration - **Per-app profiles** - Each app can have its own sandbox configuration
- **Profile management** - Use local, community, or default Firejail profiles - **Profile management** - Use local, community, or default Firejail profiles
### :accessibility: Accessibility ### :wheelchair: Accessibility
Driftwood is built to meet WCAG 2.2 AAA accessibility standards: Software that only works for some people doesn't really work. Driftwood is built
to meet WCAG 2.2 AAA accessibility standards:
- **Full keyboard navigation** - Every feature is reachable without a mouse - **Full keyboard navigation** - Every single feature is reachable without a
mouse
- **Screen reader support** - All buttons, images, and status changes are - **Screen reader support** - All buttons, images, and status changes are
announced to screen readers like Orca announced to screen readers like Orca
- **Focus management** - Clear focus indicators (3px outlines) on all interactive - **Focus management** - Clear, visible focus indicators (3px outlines) on all
elements interactive elements
- **44px minimum target sizes** - All buttons meet the AAA touch target standard - **44px minimum target sizes** - All buttons meet the AAA touch/click target
standard
- **High contrast support** - Enhanced borders and colors when your system uses - **High contrast support** - Enhanced borders and colors when your system uses
high contrast mode high contrast mode
- **No timing requirements** - Nothing in the app requires fast reactions - **No timing requirements** - Nothing in the app requires fast reactions or
races against a clock
- **Semantic roles** - Headings, alerts, status regions, and live announcements - **Semantic roles** - Headings, alerts, status regions, and live announcements
are all properly marked up are all properly marked up for assistive technology
- **Automated testing** - Includes an AT-SPI audit tool that walks the live - **Automated testing** - Ships with an AT-SPI audit tool that walks the live
accessibility tree and checks for violations accessibility tree and checks for violations
### :keyboard: Keyboard Shortcuts ### :keyboard: Keyboard Shortcuts
@@ -189,7 +219,8 @@ Driftwood is built to meet WCAG 2.2 AAA accessibility standards:
### :desktop_computer: Command Line Interface ### :desktop_computer: Command Line Interface
Every feature is also available from the terminal: Every feature is also available from the terminal. The GUI and CLI share the same
database, so they always stay in sync.
```sh ```sh
driftwood scan # Find AppImages in your configured folders driftwood scan # Find AppImages in your configured folders
@@ -227,27 +258,27 @@ driftwood purge # Remove ALL Driftwood system modifications
## :penguin: Which Linux distributions does it work on? ## :penguin: Which Linux distributions does it work on?
Driftwood works on any Linux distribution that has GTK 4.16+ and libadwaita 1.6+ Driftwood works on any Linux distribution that has GTK 4.16+ and libadwaita 1.6+.
available. In practice, that means most modern distributions released from 2024 In practice, that means most modern distributions released from 2024 onward.
onward.
| Distribution | Status | Notes | | Distribution | Status | Notes |
|-------------|--------|-------| |-------------|--------|-------|
| **Ubuntu 24.04+** | Works | GTK4 and libadwaita available in default repos | | **Ubuntu 24.04+** | :white_check_mark: Works | GTK4 and libadwaita in default repos |
| **Fedora 40+** | Works | Excellent GTK4 support out of the box | | **Fedora 40+** | :white_check_mark: Works | Excellent GTK4 support out of the box |
| **Arch Linux** | Works | Rolling release, always has the latest GTK4 | | **Arch Linux** | :white_check_mark: Works | Rolling release, always has the latest |
| **Manjaro** | Works | Same packages as Arch | | **Manjaro** | :white_check_mark: Works | Same packages as Arch |
| **openSUSE Tumbleweed** | Works | Rolling release with current GTK4 | | **openSUSE Tumbleweed** | :white_check_mark: Works | Rolling release with current GTK4 |
| **Debian Testing/Sid** | Works | Stable Debian may have older GTK versions | | **Debian Testing/Sid** | :white_check_mark: Works | Stable may have older GTK versions |
| **Linux Mint 22+** | Works | Based on Ubuntu 24.04 | | **Linux Mint 22+** | :white_check_mark: Works | Based on Ubuntu 24.04 |
| **Pop!_OS 24.04+** | Works | Based on Ubuntu with COSMIC/GNOME | | **Pop!_OS 24.04+** | :white_check_mark: Works | Based on Ubuntu |
| **elementary OS 8+** | Works | Uses GTK4-based Pantheon | | **elementary OS 8+** | :white_check_mark: Works | GTK4-based Pantheon desktop |
| **Gentoo** | Works | Build GTK4 and libadwaita from source | | **Gentoo** | :white_check_mark: Works | Build from source |
| **Alpine** | Works | GTK4 available in community repos | | **Alpine** | :white_check_mark: Works | GTK4 in community repos |
| **NixOS** | :white_check_mark: Works | Package GTK4 + libadwaita via Nix |
**Desktop environment**: Driftwood is designed for GNOME but works on any desktop **Desktop environment**: Driftwood is designed for GNOME but works on any desktop
that supports GTK4 applications (KDE Plasma, Cinnamon, XFCE, Budgie, etc.). It that supports GTK4 applications (KDE Plasma, Cinnamon, XFCE, Budgie, Sway, etc.).
looks best on GNOME and GNOME-based desktops because it uses libadwaita for It looks best on GNOME and GNOME-based desktops because it uses libadwaita for
styling. styling.
--- ---
@@ -260,32 +291,31 @@ styling.
|------------|---------|-----------| |------------|---------|-----------|
| **GTK** | 4.16 or newer | The toolkit that draws the interface | | **GTK** | 4.16 or newer | The toolkit that draws the interface |
| **libadwaita** | 1.6 or newer | GNOME's design library for modern-looking apps | | **libadwaita** | 1.6 or newer | GNOME's design library for modern-looking apps |
| **SQLite** | 3 | A small database engine (stores your app library) | | **SQLite** | 3 | A small, local database engine (stores your app library) |
| **gettext** | any | Handles translations for different languages | | **gettext** | any | Handles translations for different languages |
### Optional (but recommended) ### Optional (but recommended)
| Package | What it does | | Package | What it does |
|---------|-------------| |---------|-------------|
| **libfuse2** or **libfuse3** | Lets AppImages mount themselves (most need this to run) | | **libfuse2** or **libfuse3** | Lets AppImages mount themselves (most AppImages need this to run) |
| **firejail** | Runs apps in a security sandbox | | **firejail** | Runs apps in a security sandbox for extra isolation |
| **appimageupdate** | Enables fast delta updates (downloads only what changed) | | **appimageupdate** | Enables fast delta updates (downloads only what changed, not the whole file) |
### For building from source ### For building from source
You'll also need:
| Package | What it is | | Package | What it is |
|---------|-----------| |---------|-----------|
| **Rust 1.75+** and **Cargo** | The programming language and build tool | | **Rust 1.75+** and **Cargo** | The programming language and build tool |
| **Meson** | Build system (only needed for system-wide installation) | | **Meson** | Build system (only for system-wide installation) |
| **libgtk-4-dev** | GTK4 development headers | | **libgtk-4-dev** | GTK4 development headers |
| **libadwaita-1-dev** | libadwaita development headers | | **libadwaita-1-dev** | libadwaita development headers |
| **libsqlite3-dev** | SQLite development headers | | **libsqlite3-dev** | SQLite development headers |
| **libglib2.0-dev-bin** | Provides `glib-compile-resources` and `glib-compile-schemas` | | **libglib2.0-dev-bin** | Provides `glib-compile-resources` and `glib-compile-schemas` |
> Package names may vary between distributions. On Fedora, use `-devel` instead > Package names vary between distributions. On Fedora, use `-devel` instead
> of `-dev` (for example, `gtk4-devel` instead of `libgtk-4-dev`). > of `-dev` (for example, `gtk4-devel` instead of `libgtk-4-dev`). On Arch,
> the packages are `gtk4`, `libadwaita`, and `sqlite`.
--- ---
@@ -314,50 +344,56 @@ After installing, Driftwood will appear in your application menu.
## :package: Packaging ## :package: Packaging
Ready-made packaging files are included: Packaging files are included so anyone can build packages for their distribution:
| Format | Location | Notes | | Format | Location | Notes |
|--------|----------|-------| |--------|----------|-------|
| **Flatpak** | `build-aux/app.driftwood.Driftwood.json` | Flatpak manifest | | **Flatpak** | `build-aux/app.driftwood.Driftwood.json` | Flatpak manifest |
| **Arch Linux (AUR)** | `packaging/PKGBUILD` | For makepkg | | **Arch Linux (AUR)** | `packaging/PKGBUILD` | For makepkg |
| **AppImage** | `packaging/build-appimage.sh` | Self-contained build script | | **AppImage** | `packaging/build-appimage.sh` | Build script |
If you package Driftwood for a distribution not listed here, let us know - we'd
love to include it.
--- ---
## :open_file_folder: Where Driftwood stores things ## :open_file_folder: Where Driftwood Stores Things
Driftwood keeps everything local. Nothing leaves your machine.
| What | Location | | What | Location |
|------|----------| |------|----------|
| App database | `~/.local/share/driftwood/driftwood.db` | | App database | `~/.local/share/driftwood/driftwood.db` |
| Cached icons | `~/.local/share/driftwood/icons/` | | Cached icons | `~/.local/share/driftwood/icons/` |
| Desktop entries it creates | `~/.local/share/applications/driftwood-*.desktop` | | Desktop entries | `~/.local/share/applications/driftwood-*.desktop` |
| Installed icons | `~/.local/share/icons/hicolor/` | | Installed icons | `~/.local/share/icons/hicolor/` |
| Autostart entries | `~/.config/autostart/` | | Autostart entries | `~/.config/autostart/` |
| Settings | GSettings (`app.driftwood.Driftwood`) | | Settings | GSettings (`app.driftwood.Driftwood`) |
| Backups | `~/.local/share/driftwood/backups/` | | Backups | `~/.local/share/driftwood/backups/` |
Everything Driftwood does to your system is tracked in its database, and you can Every modification Driftwood makes to your system is recorded in its database.
undo all of it with `driftwood purge` or by uninstalling apps through the UI. You can undo all of it at any time with `driftwood purge` or through the UI.
Your system, your rules.
--- ---
## :test_tube: Accessibility Testing ## :test_tube: Accessibility Testing
Driftwood includes an automated accessibility audit tool that uses AT-SPI (the Driftwood ships with an automated accessibility audit tool that uses AT-SPI (the
Linux accessibility bus) to walk the live widget tree and check for WCAG 2.2 Linux accessibility bus) to walk the live widget tree and check for WCAG 2.2
violations: violations:
```sh ```sh
# Run the full AAA-level audit (builds and launches the app automatically) # Full AAA-level audit (builds and launches automatically)
python3 tools/a11y-audit.py --level aaa python3 tools/a11y-audit.py --level aaa
# Attach to an already-running instance # Attach to an already-running instance
python3 tools/a11y-audit.py --no-launch --level aaa python3 tools/a11y-audit.py --no-launch --level aaa
# Run at AA level only # AA level only
python3 tools/a11y-audit.py --level aa python3 tools/a11y-audit.py --level aa
# Show detailed live region inventory # Verbose output with live region inventory
python3 tools/a11y-audit.py --level aaa --verbose python3 tools/a11y-audit.py --level aaa --verbose
``` ```
@@ -378,18 +414,24 @@ integration.
--- ---
## :handshake: Contributing ## :raised_hands: Contributing
Driftwood is a community project. There's no company behind it, no investors,
no roadmap driven by profit - just people building something useful together.
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to contribute code, See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to contribute code,
translations, or bug reports. translations, bug reports, or ideas. Every contribution matters, and everyone
who helps is a co-owner of this project.
--- ---
## :page_facing_up: License ## :page_facing_up: License
**CC0-1.0 (Public Domain)** **CC0-1.0 - Public Domain**
This project is released into the public domain under the CC0 1.0 Universal Driftwood belongs to everyone. It is released into the public domain under the
license. You can copy, modify, distribute, and use it for any purpose, even [CC0 1.0 Universal](LICENSE) license. You can copy, modify, distribute, and use
commercially, without asking permission. See [LICENSE](LICENSE) for the full it for any purpose - personal, educational, commercial, anything - without
legal text. asking permission, without paying anyone, without restrictions.
Knowledge and tools should be shared freely. This is ours, and it's yours.