Filearchy

A modern, high-performance file manager built with libcosmic for the COSMIC desktop environment. Fork of cosmic-files with performance optimizations and extended functionality.

---

What's Different

Filearchy extends cosmic-files with powerful new capabilities:

	Feature	Description
	io_uring Backend	Native Linux async I/O for blazing-fast file operations
	Triglyph Search	Trigram-indexed instant search across your filesystem
	Git Integration	Status overlays, staging, diffs, and blame directly in the file view
	Command Palette	Quick actions via Ctrl+Shift+P
	Always-Visible Path	Editable address bar without click-to-reveal
	Custom Icons	Professional iconics-based icon system
	Debug Logging	SQLite-backed debug logs for troubleshooting
	Profiling Support	Built-in tracing and system metrics

---

Features

Indexed Search

Fast file search powered by Triglyph - a trigram-based indexing engine that provides near-instant search results across your filesystem.

io_uring Support

Native Linux io_uring support for high-throughput asynchronous file I/O operations, significantly reducing latency for directory traversal and file operations.

Smart File Management

• Incremental tab updates (O(1) item lookups via hash index)
• Thumbnail caching with memory-efficient generation
• Drag-and-drop with visual feedback
• Archive support (ZIP, TAR, GZIP, BZ2, XZ)

Git Integration

Optional git status overlays showing modified, staged, and untracked files directly in the file view.

Desktop Integration

• Wayland-native with full compositor integration
• Desktop icons mode for managing files on your desktop
• GVFS mounting for network shares and removable media
• XDG MIME type associations
• XDG Desktop Portal file picker support (via xdg-desktop-portal-cosmic)

---

Installation

Dependencies

Build dependencies:

# Debian/Ubuntu
sudo apt install libgtk-4-dev libadwaita-1-dev libglib2.0-dev

# Arch Linux
sudo pacman -S gtk4 libadwaita glib2

Runtime dependencies:

• gvfs (optional, for network mounts)
• A Wayland compositor (COSMIC, Hyprland, Sway, etc.)

Building from Source

git clone https://github.com/yourusername/filearchy.git
cd filearchy

# Release build
cargo build --release

# Install system-wide (recommended for keybinds)
sudo install -Dm755 target/release/filearchy /usr/local/bin/filearchy

# Or install to user directory
# install -Dm755 target/release/filearchy ~/.local/bin/filearchy

Feature Flags

Flag	Description	Default
io-uring	Enable io_uring for async file I/O	Yes
search-engine	Triglyph indexed search	Yes
git	Git status overlays	No
gvfs	GVFS mounting support	Yes
wayland	Wayland-specific features	Yes
profiling	Tracing and metrics	No

Build with specific features:

cargo build --release --features "git,profiling"

---

Usage

# Open file manager
filearchy

# Open specific directory
filearchy /path/to/directory

# Open multiple locations in tabs
filearchy ~/Documents ~/Downloads

# Debug logging
filearchy --logs recent 100
filearchy --logs follow

Keyboard Shortcuts

Shortcut	Action
Ctrl+T	New tab
Ctrl+W	Close tab
Ctrl+L	Focus location bar
Ctrl+F	Search
Ctrl+H	Toggle hidden files
Ctrl+1/2	List/Icon view
Ctrl+Shift+P	Command palette
Space	Quick preview
Ctrl+Space	Details pane
F5	Refresh

Debug Logging

# Basic warnings only
RUST_LOG=warn filearchy

# Debug filearchy modules
RUST_LOG=warn,filearchy=debug filearchy

# Debug file watcher events
RUST_LOG=warn,filearchy::app=debug filearchy

# Capture logs to file
RUST_LOG=debug filearchy 2>/tmp/filearchy.log

---

Architecture

Filearchy implements several performance optimizations over the base cosmic-files:

• Incremental Updates: File system events trigger targeted updates rather than full directory rescans
• Hash-Indexed Items: O(1) lookups for metadata updates using FxHashMap
• Async I/O: compio runtime with io_uring backend for non-blocking file operations
• Thumbnail Pipeline: Background generation with memory-mapped caching
• Optimized Event Handling: Filtered keyboard events to prevent subscription queue overflow
• Responsive List View: Text truncation instead of wrapping for narrow window widths

See docs/architecture.md for detailed technical documentation.

---

Testing

# Run unit tests
cargo test

# Run with specific features
cargo test --features "git,search-engine"

# Benchmarks
cargo bench

See TESTING.md for the full QA regression checklist.

---

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

Based on cosmic-files by System76.

---

Contributing

Contributions are welcome! Please ensure your code:

• Passes cargo clippy with no warnings
• Includes tests for new functionality
• Follows the existing code style

See docs/testing-infrastructure.md for development tooling.