Expand description
§Configuration Watch Command
The watch command monitors a TOML configuration file for changes and
automatically converts it to JSON when modifications are detected. This
enables a live-reload workflow where users can edit their configuration
and immediately see changes reflected in the running shell.
§Usage
# Watch default config location
fernctl watch
# Watch a specific file
fernctl watch --config ./my-config.toml
# Custom output location
fernctl watch --config config.toml --output theme.json
# Adjust debounce timing (milliseconds)
fernctl watch --debounce 200
# Disable desktop notifications
fernctl watch --quiet§How It Works
The watch command uses operating system facilities to efficiently monitor files for changes:
| Platform | Technology |
|---|---|
| Linux | inotify |
| macOS | FSEvents |
| Windows | ReadDirectoryChangesW |
This is more efficient than polling — the process sleeps until the OS signals that the file has changed.
§Event Flow
┌─────────────────────────────────────────────────────────────────────┐
│ Watch Loop │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────────┐│
│ │ inotify │ │ Debounce │ │ Convert & Notify ││
│ │ (or equiv) │──▶│ (100ms) │──▶│ ││
│ └──────────────┘ └──────────────┘ │ ┌─────────┐ ││
│ ▲ │ │ Parse │ ││
│ │ │ │ TOML │ ││
│ │ │ └────┬────┘ ││
│ File modified │ │ ││
│ by user │ ▼ ││
│ │ ┌─────────┐ ││
│ │ │Validate │ ││
│ │ └────┬────┘ ││
│ │ │ ││
│ │ ▼ ││
│ │ ┌─────────┐ ┌────────┐ ││
│ │ │ Write │ │ Notify │ ││
│ │ │ JSON │──▶│ User │ ││
│ │ └─────────┘ └────────┘ ││
│ └──────────────────────────┘│
└─────────────────────────────────────────────────────────────────────┘§Debouncing
Editors often trigger multiple file system events when saving a file:
- File truncated (write begins)
- Data written
- File closed
- Metadata updated
Without debouncing, we might try to parse a half-written file. The debouncer waits for events to settle before processing:
Events: ┃━━━━━━━━━━┃ ┃━━━━┃ ┃
│ truncate │ │write│ │
│ modify │ │close│ │
Time: ──────────────────────────────────────────────▶
0ms 10ms 50ms 100ms (debounce expires)
│
▼
Process file§Error Handling
The watch command is designed to be resilient — configuration errors should not crash the watcher. Instead:
| Error Type | Behavior |
|---|---|
| Parse error | Notify user, keep watching |
| Validation error | Notify user, keep watching |
| File deleted | Notify user, keep watching |
| Watch system error | Exit with error |
This allows users to fix mistakes without restarting the watcher:
$ fernctl watch
Watching ~/.config/fern/config.toml...
[14:32:01] ✓ Config reloaded
[14:32:15] ✗ Parse error at line 5 (keep editing...)
[14:32:28] ✓ Config reloaded§Desktop Notifications
When notifications are enabled (the default), the watch command sends desktop notifications via the freedesktop.org notification spec:
| Scenario | Notification |
|---|---|
| Success | “Config Reloaded” (info) |
| Warning | “Unknown Key: colour” (warning) |
| Error | “Invalid Color: #gg0000” (error) |
These appear in whatever notification daemon is running (fern-shell’s own notification center, dunst, mako, etc.).
§Integration with QuickShell
QuickShell watches the JSON file using its own FileView component.
When we write a new JSON file, QuickShell automatically reloads:
┌────────────┐ ┌─────────────┐ ┌────────────────┐
│ User │ │ fernctl │ │ QuickShell │
│ edits │──────▶ watch │──────▶│ reloads │
│ TOML │ │ writes │ │ UI updates │
└────────────┘ │ JSON │ └────────────────┘
└─────────────┘No IPC is needed — file watching on both sides creates a clean decoupled architecture.
§Exit Codes
| Code | Meaning |
|---|---|
0 | Normal exit (Ctrl+C) |
1 | Initialization error (file not found, etc.) |
2 | Watch system error |
§Programmatic Usage
use fernctl::commands::watch::{run, WatchOptions, WatchEvent};
use fernctl::adapters::{TomlConfigAdapter, FileSystemAdapter};
let config_adapter = TomlConfigAdapter::new();
let persist_adapter = FileSystemAdapter::new();
let options = WatchOptions {
debounce_ms: 100,
notify_on_success: true,
notify_on_error: true,
verbose: true,
};
// Run the watch loop (blocks until interrupted)
run(
&config_path,
&json_path,
options,
&config_adapter,
&persist_adapter,
|event| {
// Custom event handler
match event {
WatchEvent::Reloaded { warnings } => { /* ... */ }
WatchEvent::Error { error } => { /* ... */ }
}
},
)?;§Resource Usage
The watch command is designed to be lightweight:
- CPU: Near-zero when idle (event-driven, not polling)
- Memory: ~5-10 MB baseline
- File descriptors: 2-3 per watched file
It’s safe to run indefinitely in the background.
Structs§
- Watch
Options - Options for the watch command.
Enums§
- Watch
Event - Events emitted during the watch loop.
Functions§
- convert_
and_ 🔒report - Converts the config and reports the result.
- notify_
on_ 🔒error - Callback wrapper that sends errors as notifications.
- run
- Runs the configuration watch loop.
- send_
notification 🔒 - Sends a desktop notification.
- timestamp 🔒
- Returns the current time formatted for log output.
Type Aliases§
- Event
Handler - A callback function for watch events.