docs: bootstrap vault, roadmap and research

2026-10-17 21:14:19 +03:00
parent 749afadcd4
commit 8fa0632d69
34 changed files with 1508 additions and 0 deletions
@@ -0,0 +1,77 @@
+---
+type: research
+status: analyzed
+confidence: high
+created: 2026-10-17
+question: What exactly makes ranger great, what makes it slow and fragile, and what must a Rust successor keep or fix?
+tags: [research, ranger, file-manager]
+---
+
+# Ranger deep dive
+
+## Research question
+Ranger is the most feature-complete terminal file manager but famously slow in specific
+scenarios. We need a precise keep/fix list before writing a single line of viexp.
+
+## Findings
+
+### Project state (Oct 2026)
+Python + curses, Miller-columns UI. 17.4k stars, ~900 open issues, last tag v1.9.4 (Nov 2024),
+commits still trickling. Maintainers openly state they lack manpower (issue #1717).
+
+### Architecture
+- Config = 4 files with **different merge semantics**: `rc.conf` merges, `rifle.conf` replaces,
+  `scope.sh` replaces (~700-line bash), `commands.py` merges (Python subclassing).
+- Preview pipeline = external `scope.sh`; communicates via exit codes:
+  `0` = stdout preview, `1` = none, `2` = fixed-height text, `5` = image written to cache dir.
+- Plugins = Python monkeypatching with full interpreter access ("Plugins have full access to
+  your computer!"). Ecosystem: ranger-devicons, ranger-zoxide, ranger-fzf-filter, etc.
+- Image protocols: w3m, ueberzug, urxvt, kitty, sixel, iterm2, terminology.
+
+### Why it is slow (root causes)
+| Cause | Evidence |
+|-------|----------|
+| Synchronous UI loop — directory listing + `stat` of every file run inline | issue #1173: 100k files = multi-second uninterruptible hang (open since 2018) |
+| No async I/O anywhere; threading refactor stalled | issue #1025 literally labeled `wants-async` |
+| `statvfs` on **every status-bar refresh** → 4–10 s j/k lag on sshfs/NFS/CryFS/s3fs | issue #1025; vifm stays fast in identical setups |
+| Python interpreter startup ~1 s cold | issue #1717 |
+| Every preview spawns scope.sh + a chain of external binaries | architecture |
+
+### Pain points (user-verified)
+1. ueberzug unmaintained and X11-only; ueberzugpp fixes exist but are bolted on
+   (ranger #3188, #3158, #2995; ueberzugpp #122 fractional-scaling bug on Sway/Hyprland).
+2. Network mounts unusable without manual `setlocal` hacks or `F` (freeze_files).
+3. `:flat` broken past ~30k files (#379).
+4. No built-in trash — ArchWiki documents `map DD shell gio trash` as the workaround.
+5. Config fragmentation: four files, four formats, four merge behaviors.
+
+### What users love (must keep)
+Vim keys, Miller columns, `:bulkrename` via `$EDITOR` (the killer feature), rifle-style
+ordered opener menu (`r`), preview breadth (20+ types), tabs/bookmarks/marks, `:filter`,
+`--choosefile/--choosedir` + cd-on-exit, per-path options (`setlocal`).
+
+## Keep / Fix table
+
+| Keep | Fix |
+|------|-----|
+| Miller 3-pane layout, vim key vocabulary | Native binary startup (no interpreter) |
+| `:bulkrename` via `$EDITOR` | Async dir loading / stat / preview — UI never blocks |
+| Rifle-style opener rules + chooser menu | No `statvfs` per frame; poll with timeout+backoff |
+| Exit-code preview contract (scope.sh idea) | First-class trash (`gio trash`-compatible) + undo |
+| Preview breadth with caching | Native kitty/sixel/ueberzug++ graphics, Wayland-safe |
+| `setlocal` per-path options | One config format (TOML) with documented merge semantics |
+| `--choosefile/--choosedir`, cd-on-exit | Virtual scrolling for 100k+ entry dirs |
+| `F` freeze escape hatch | Automatic freeze on network/fuse mounts |
+
+## Outcome
+Direct input to [[decisions/ADR-002-extension-architecture|ADR-002]] (extension model),
+ADR-004 (preview protocols) and the roadmap's async requirements (Sprint 8).
+
+## Sources
+- https://github.com/ranger/ranger — README, wiki, examples/plugins
+- https://wiki.archlinux.org/title/Ranger
+- Issues: #1717 (startup), #1173 (100k files), #1025 (network lag), #379 (`:flat`),
+  #3188 / #3158 / #2995 (ueberzug family)
+- https://github.com/seebye/ueberzug (unmaintained notice), https://github.com/jstkdng/ueberzugpp
+- Community: r/commandline "Is yazi overhyped?", r/linux FM threads, x-cmd six-FM comparison,
+  https://mqdir.com/blog/file-management/nnn-vs-yazi