{"id":47516116,"url":"https://github.com/isene/RTFM","last_synced_at":"2026-04-01T07:00:42.486Z","repository":{"id":56893077,"uuid":"303690447","full_name":"isene/RTFM","owner":"isene","description":"Ruby Terminal File Manager","archived":false,"fork":false,"pushed_at":"2026-03-21T21:00:04.000Z","size":18859,"stargazers_count":53,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-22T08:42:04.316Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/isene.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2020-10-13T12:08:50.000Z","updated_at":"2026-03-21T21:00:08.000Z","dependencies_parsed_at":"2025-05-06T11:23:10.638Z","dependency_job_id":"2f517f10-55e9-48b4-8ac3-9d8d66cc84f2","html_url":"https://github.com/isene/RTFM","commit_stats":null,"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/isene/RTFM","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/isene%2FRTFM","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/isene%2FRTFM/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/isene%2FRTFM/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/isene%2FRTFM/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/isene","download_url":"https://codeload.github.com/isene/RTFM/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/isene%2FRTFM/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31269176,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T06:57:45.811Z","status":"ssl_error","status_checked_at":"2026-04-01T06:57:42.389Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-03-27T13:00:30.246Z","updated_at":"2026-04-01T07:00:42.479Z","avatar_url":"https://github.com/isene.png","language":"Ruby","funding_links":[],"categories":["\u003ca name=\"file-manager\"\u003e\u003c/a\u003eFile manager"],"sub_categories":[],"readme":"# RTFM - Ruby Terminal File Manager\n\n![Ruby](https://img.shields.io/badge/language-Ruby-red) [![Gem Version](https://badge.fury.io/rb/rtfm-filemanager.svg)](https://badge.fury.io/rb/rtfm-filemanager) ![Unlicense](https://img.shields.io/badge/license-Unlicense-green) [![Documentation](https://img.shields.io/badge/docs-comprehensive-blue)](docs/) ![Stay Amazing](https://img.shields.io/badge/Stay-Amazing-important)\n\n\u003cimg src=\"img/logo.png\" align=\"left\" width=\"150\" height=\"150\"\u003e\n\nA feature-rich terminal file manager written in pure Ruby. Browse directories with syntax-highlighted previews, inline images, remote SSH/SFTP access, comprehensive undo system, OpenAI integration, and much more.\n\nRTFM parses your LS_COLORS for consistent terminal theming and runs on any modern terminal emulator.\n\n\u003cbr clear=\"left\"/\u003e\n\n## Quick Start\n\n```bash\n# Install\ngem install rtfm-filemanager\n\n# Run\nrtfm\n\n# Or start in specific directory\nrtfm ~/Documents\n\n# Use as file picker (tag files with t, quit with q)\nrtfm --pick=/tmp/selected_files.txt\n\n# Press ? for help\n```\n\nAfter first run, use `r` command to launch RTFM and exit into your current directory.\n\n---\n\n## Screenshots\n\n| OpenAI File Analysis | Interactive AI Chat |\n|:---:|:---:|\n| ![AI analyzing a PDF](img/screenshot-ai-file.png) | ![AI chat mode](img/screenshot-ai-chat.png) |\n| **Syntax Highlighting** | **System Information** |\n| ![Ruby code highlighting](img/screenshot-syntax.png) | ![System stats (press S)](img/screenshot-system.png) |\n\n---\n\n## Table of Contents\n\n- [Key Features](#key-features)\n- [Installation](#installation)\n- [Keyboard Reference](#keyboard-reference)\n- [Remote SSH/SFTP Browsing](#remote-sshsftp-browsing)\n- [Configuration](#configuration)\n- [OpenAI Integration](#openai-integration)\n- [Plugins](#plugins)\n- [Image Display](#image-display)\n- [RTFM vs Ranger](#rtfm-vs-ranger)\n- [Documentation](#documentation)\n\n---\n\n## Key Features\n\n### File Operations\n- **Comprehensive undo system** - Undo delete, move, rename, copy, symlink, permissions, ownership\n- **Trash bin** - Optional safe deletion with restore capability\n- **Bulk operations** - Copy, move, delete multiple tagged items\n- **Bulk rename** - Pattern-based renaming (regex, templates, case conversion)\n- **Permission management** - Change permissions with undo support (`755`, `rwxr-xr-x`, `+x`, `-w`)\n- **Ownership management** - Change user:group with undo support\n\n### Display \u0026 Preview\n- **Syntax highlighting** - File content with bat/batcat\n- **Inline images** - w3m and Sixel protocols via termpix gem\n- **EXIF orientation** - Correct display of rotated images\n- **Video thumbnails** - ffmpegthumbnailer integration\n- **Archive preview** - View contents of .zip, .tar, .gz, .rar, .7z files\n- **Document preview** - PDF, LibreOffice, MS Office files\n- **LS_COLORS parsing** - Consistent terminal color theming\n\n### Remote Operations\n- **SSH/SFTP browsing** - Navigate remote directories seamlessly\n- **Interactive SSH shell** - Drop into shell sessions on remote hosts\n- **File transfer** - Download and upload files\n- **Connection caching** - Smart caching for performance\n\n### Advanced Features\n- **Git integration** - Status display for repositories\n- **Cryptographic hashing** - Directory tree verification\n- **OpenAI integration** - File descriptions and interactive chat\n- **Tab management** - Multiple tabs with duplication and renaming\n- **File picker mode** - Use RTFM as a file selector for other applications (`--pick`)\n- **Fuzzy search** - fzf integration\n- **Navi integration** - Interactive command cheatsheets\n\n### Developer Features\n- **Plugin system** - Live enable/disable plugins with built-in manager (`V` key)\n- **Example plugins** - Settings editor, git, bookmarks, notes, custom openers\n- **Ruby debug mode** - Execute arbitrary Ruby in context\n- **Command history** - Preserved across sessions\n\n---\n\n## Installation\n\n### via RubyGems (Recommended)\n\n```bash\ngem install rtfm-filemanager\n```\n\n### Full Installation with All Features\n\n#### Ubuntu/Debian:\n```bash\nsudo apt update\nsudo apt install ruby-full x11-utils xdotool bat pandoc poppler-utils \\\n  odt2txt docx2txt unzip gnumeric catdoc w3m imagemagick \\\n  ffmpegthumbnailer tar gzip bzip2 xz-utils unrar p7zip-full\n\ngem install rtfm-filemanager\n```\n\n#### ArchLinux/derivatives\n```bash\nsudo pacman -Syu ruby bat pandoc poppler odt2txt docx2txt unzip gnumeric catdoc w3m imagemagick ffmpegthumbnailer p7zip libreoffice-fresh\ngem install rtfm-filemanager\n```\n\nNote: catppt is not available in official repos, but RTFM will fall back to using LibreOffice's soffice for .ppt files. For xls2csv, use an AUR helper:\n```\nyay -Syu perl-xls2csv\n```\n\n#### macOS:\n```bash\nbrew install ruby imagemagick w3m bat pandoc poppler\n\ngem install rtfm-filemanager\n```\n\n### Dependencies\n\n**Required:**\n- Ruby 2.7+\n- rcurses gem (~\u003e 6.0)\n- termpix gem (~\u003e 0.2)\n\n**Optional (for full functionality):**\n- **ImageMagick** - Image preview (`identify`, `convert`)\n- **w3m-img** - w3m image protocol\n- **xdotool** - Image redraw on workspace switching\n- **bat/batcat** - Syntax highlighting\n- **fzf** - Fuzzy file finding\n- **pandoc** - Document conversion\n- **ffmpegthumbnailer** - Video thumbnails\n- **ruby-openai** - AI integration\n\n---\n\n## Keyboard Reference\n\nFor complete reference: `man rtfm` or press `?` in RTFM\n\n### Essential Keys\n\n| Key | Action |\n|-----|--------|\n| `?` | Show help |\n| `q` | Quit (save config) |\n| `Q` | Quit (don't save) |\n| `r` | Refresh display |\n| `V` | Plugin manager |\n\n### Navigation\n\n| Key | Action |\n|-----|--------|\n| `j` / `↓` | Move down |\n| `k` / `↑` | Move up |\n| `h` / `←` | Parent directory |\n| `l` / `→` / `ENTER` | Enter directory / open file |\n| `HOME` / `END` | First / last item |\n| `PgUp` / `PgDn` | Page up / down |\n\n### Marks \u0026 Jumping\n\n| Key | Action |\n|-----|--------|\n| `m` + letter | Set bookmark |\n| `'` + letter | Jump to bookmark |\n| `~` | Jump to home |\n| `\u003e` | Follow symlink |\n| `Ctrl-r` | Recent files/directories |\n| `Ctrl-e` | Toggle remote SSH mode |\n\n### Tagging\n\n| Key | Action |\n|-----|--------|\n| `t` | Tag/untag item |\n| `Ctrl-t` | Tag by pattern |\n| `T` | Show tagged items |\n| `u` | Untag all |\n\n### File Operations\n\n| Key | Action |\n|-----|--------|\n| `p` | Copy tagged items here |\n| `P` | Move tagged items here |\n| `s` | Create symlinks |\n| `c` | Rename item |\n| `E` | Bulk rename (patterns) |\n| `d` | Delete (→ trash if enabled) |\n| `D` | Trash browser (browse, restore, delete) |\n| `Ctrl-d` | Toggle trash on/off |\n| `U` | Undo last operation |\n\n### Permissions\n\n| Key | Action |\n|-----|--------|\n| `Ctrl-p` | Change permissions (with undo) |\n| `Ctrl-o` | Change ownership (with undo) |\n\n**Permission formats:** `755`, `rwxr-xr-x`, `rwx`, `+x`, `-w`, `+rw`\n\n### Search \u0026 Filter\n\n| Key | Action |\n|-----|--------|\n| `f` | Filter by extension |\n| `F` | Filter by regex |\n| `/` | Search and highlight |\n| `n` / `N` | Next / previous match |\n| `g` | Grep content |\n| `L` | Locate files |\n| `Ctrl-l` | Fuzzy find (fzf) |\n\n### Display\n\n| Key | Action |\n|-----|--------|\n| `-` | Toggle preview on/off |\n| `_` | Toggle image preview |\n| `b` | Toggle syntax highlighting |\n| `w` | Change pane width |\n| `B` | Cycle borders |\n| `a` | Show/hide hidden files |\n| `A` | Toggle long info (ls -l) |\n| `o` | Change sort order |\n| `i` | Invert sort |\n\n### Clipboard\n\n| Key | Action |\n|-----|--------|\n| `y` | Copy path (primary selection) |\n| `Y` | Copy path (clipboard) |\n| `Ctrl-y` | Copy image/text to clipboard |\n\n### Git / AI / System\n\n| Key | Action |\n|-----|--------|\n| `G` | Git status |\n| `H` | Directory hash |\n| `I` | OpenAI file description |\n| `Ctrl-a` | OpenAI chat |\n| `S` | System information |\n| `X` | Compare two files |\n| `e` | File properties |\n\n### Tabs\n\n| Key | Action |\n|-----|--------|\n| `]` | New tab |\n| `[` | Close tab |\n| `J` / `K` | Previous / next tab |\n| `}` | Duplicate tab |\n| `{` | Rename tab |\n| `1-9` | Switch to tab # |\n\n### Command Mode\n\n| Key | Action |\n|-----|--------|\n| `:` | Execute shell command |\n| `;` | Command history |\n| `@` | Ruby debug mode |\n| `§` | Force interactive mode (prefix) |\n| `+` | Whitelist program as interactive |\n\n**Interactive mode example:** `:§htop` - runs htop in full terminal\n\n---\n\n## Remote SSH/SFTP Browsing\n\nAccess and manage files on remote servers directly from RTFM.\n\n### Activating Remote Mode\n\n1. Press `Ctrl-e`\n2. Enter connection string:\n   ```\n   user@server.com:/path/to/directory\n   ```\n\n### Connection Formats\n\n```bash\n# Basic SSH\nuser@server.com:/path\n\n# Custom SSH key\n-i ~/.ssh/custom-key user@server.com:/path\n\n# SSH URI\nssh://user@server.com/path\n\n# With comment\nuser@server.com:/path # Production server\n```\n\n### Remote Mode Keys\n\n| Key | Action |\n|-----|--------|\n| `←` / `h` | Parent directory |\n| `→` / `ENTER` | Enter dir / show file info |\n| `D` | Download file |\n| `u` | Upload tagged files |\n| `s` | Open SSH shell |\n| `Ctrl-e` | Exit remote mode |\n\n**Visual indicator:** Red background when in remote mode\n\n### Archive Browsing\n\nPress `Enter` on any archive file (.zip, .tar.gz, .tar.bz2, .tar.xz, .rar, .7z) to browse its contents as a virtual directory.\n\n| Key | Action |\n|-----|--------|\n| `d` | Delete entry from archive |\n| `D` | Extract entry to origin directory |\n| `p` | Add pre-tagged local files into archive |\n| `t` | Tag/untag for bulk operations |\n| `LEFT` | Parent directory / exit archive |\n\n**Visual indicator:** Yellow-green background when in archive mode\n\n---\n\n## Configuration\n\nConfiguration stored in `~/.rtfm/conf`\n\n### Quick Config\n\n| Action | Command |\n|--------|---------|\n| View config | Press `C` (or interactive editor with Settings plugin) |\n| Save config | Press `W` |\n| Reload config | Press `R` |\n\n**Tip:** Install the Settings plugin for an interactive settings editor with live color preview. See [Plugins](#plugins).\n\n### Common Settings\n\n```ruby\n# ~/.rtfm/conf\n\n# Enable trash bin\n@trash = true\n\n# Toggle preview on/off\n@preview = true\n\n# Show/hide images\n@showimage = true\n\n# Show hidden files\n@lsall = \"-a\"\n\n# Show long file info\n@lslong = true\n\n# Pane width (2-7)\n@width = 5\n\n# Border style (0-3)\n@border = 2\n\n# OpenAI API key\n@ai = \"your-api-key-here\"\n\n# Directory bookmarks (persistent)\n@marks = {\"h\" =\u003e \"/home/user\", \"d\" =\u003e \"/home/user/Documents\"}\n\n# Command history (persistent)\n@history = [\"git status\", \"ls -la\"]\n\n# Interactive programs whitelist\n@interactive = \"htop,vim,emacs,nano\"\n\n# Top line background colors by path match\n@topmatch = [[\"projects\", 165], [\"\", 238]]\n```\n\n### Color Customization\n\n```ruby\n# Bottom pane\n@bottomcolor = 238\n\n# Command mode\n@cmdcolor = 24\n\n# Ruby mode\n@rubycolor = 52\n\n# OpenAI chat\n@aicolor = 17\n```\n\n---\n\n## OpenAI Integration\n\nRTFM includes built-in AI features powered by OpenAI's API for intelligent file analysis and interactive assistance.\n\n### Setup\n\n1. **Get an API key:**\n   - Sign up at https://platform.openai.com/\n   - Generate an API key from your account settings\n\n2. **Configure RTFM:**\n   Add your API key to `~/.rtfm/conf`:\n   ```ruby\n   @ai = \"sk-your-actual-api-key-here\"\n   @aimodel = \"gpt-4o-mini\"  # Optional: default model\n   @aicolor = 17             # Optional: chat pane background color\n   ```\n\nThe `ruby-openai` gem is already included as a dependency when you install RTFM.\n\n### Features\n\n#### File Description (Press `I`)\n\nGet an intelligent summary of any file or directory:\n- **Files:** Purpose, code review (for source files), library documentation lookup\n- **Directories:** Overview of structure and contents\n- **Git-aware:** Includes recent changes if in a git repository\n- **Smart analysis:** Automatically includes preview content for context\n\nExample uses:\n- Understand unfamiliar codebases quickly\n- Get code review suggestions (bugs, style, improvements)\n- Learn what libraries/APIs are being used\n- See git diff explanations in plain language\n\n#### Interactive Chat (Press `Ctrl-a`)\n\nStart a conversational AI assistant specialized in:\n- File and directory questions\n- Shell command help and suggestions\n- Terminal workflow assistance\n- Programming and scripting guidance\n\nThe chat maintains context throughout your RTFM session, so follow-up questions work naturally.\n\n### Configuration Options\n\n```ruby\n# Model selection (in ~/.rtfm/conf)\n@aimodel = \"gpt-4o-mini\"      # Fast, cost-effective (default)\n@aimodel = \"gpt-4o\"           # More capable, higher cost\n@aimodel = \"gpt-4-turbo\"      # Alternative high-end model\n\n# Chat interface color\n@aicolor = 17                 # Dark blue background (default)\n```\n\n### Cost \u0026 Privacy\n\n- API calls cost money (typically $0.001-0.01 per request with gpt-4o-mini)\n- File contents are sent to OpenAI when using `I` key\n- No data is sent unless you explicitly press `I` or `Ctrl-a`\n- Chat history persists only during your RTFM session\n\n---\n\n## Plugins\n\nRTFM has a plugin system with live enable/disable. Plugins live in `~/.rtfm/plugins/` as `.rb` files and are auto-loaded on startup.\n\n### Plugin Manager (`V` key)\n\nPress `V` to open the built-in plugin manager:\n- See all available plugins with their status (ON/OFF)\n- Press `ENTER` to toggle a plugin on or off (takes effect immediately)\n- Press `?` to view the plugin's built-in help text\n- No restart required\n\n### Example Plugins\n\nRTFM ships with five example plugins in the `examples/` directory. Copy any of them to `~/.rtfm/plugins/` to activate:\n\n```bash\ncp examples/settings.rb ~/.rtfm/plugins/\ncp examples/git.rb ~/.rtfm/plugins/\ncp examples/bookmarks.rb ~/.rtfm/plugins/\ncp examples/notes.rb ~/.rtfm/plugins/\ncp examples/opener.rb ~/.rtfm/plugins/\ncp examples/diskusage.rb ~/.rtfm/plugins/\ncp examples/dupes.rb ~/.rtfm/plugins/\n```\n\n| Plugin | Key | Description |\n|--------|-----|-------------|\n| **Settings** | `C` | Interactive editor for settings without dedicated keys (colors, trash, interactive programs, OpenAI config). Color changes apply in real-time. Overrides the default config viewer |\n| **Git** | `Ctrl-G` | Git operations menu: status, diff, commit+push, log. Output shown in right pane |\n| **Bookmarks** | `F6` | Unlimited directory bookmarks with fuzzy filtering. Add, delete, and jump to bookmarked directories. Complements the built-in single-letter marks (m/') |\n| **Notes** | `F5` | Attach text notes to any file or directory. View, edit, or delete notes. Stored in `~/.rtfm/notes/` |\n| **Opener** | `RIGHT`/`l` | Custom file openers by extension. Configure a hash of extension-to-command mappings (e.g., `.hl` files open in hyperlist) |\n| **Disk Usage** | `S` | Interactive disk usage analyzer. Extends system info with a browseable size-sorted directory view with visual bars |\n| **Dupes** | `F7` | Find duplicate files by content hash. Two-pass scan (size then SHA256) with in-place deletion of duplicates |\n\n### Writing Your Own Plugins\n\nA plugin is a simple Ruby file with metadata comments and KEYMAP bindings:\n\n```ruby\n# @name: My Plugin\n# @description: What it does\n# @key: X\n\nKEYMAP['X'] = :my_action\n\n# Optional: register help text shown by ? in plugin manager\nPLUGIN_HELP['My Plugin'] = \u003c\u003c~HELP\n  This is the help text for my plugin.\n  Shown when pressing ? in the plugin manager.\nHELP\n\ndef my_action\n  clear_image\n  @pR.update = true\n  @pR.say(\"Hello from my plugin!\")\nend\n```\n\nPlugins can also be defined in `~/.rtfm/keys.rb` for personal bindings that don't need the enable/disable mechanism.\n\n### Preview Handlers (`preview.rb`)\n\nCustom file type previews are configured separately in `~/.rtfm/preview.rb`:\n\n```ruby\n# Syntax: ext1, ext2 = command with @s placeholder\ntxt, log = bat -n --color=always @s\nmd = pandoc @s -t plain\npdf = pdftotext -f 1 -l 4 @s -\njson = jq . @s\n```\n\n### Available Variables for Plugin Authors\n\n| Variable | Description |\n|----------|-------------|\n| `@pT` | Top pane (info bar) |\n| `@pL` | Left pane (file list) |\n| `@pR` | Right pane (preview) |\n| `@pB` | Bottom pane (status) |\n| `@pCmd` | Command prompt (use `.ask(prompt, default)` for input) |\n| `@selected` | Currently selected file/dir |\n| `@tagged` | Array of tagged items |\n| `@external_program_running` | Set true when launching TUI programs |\n| `PLUGIN_HELP` | Hash to register help text (keyed by plugin name) |\n\n### Plugin Helper Functions\n\n```ruby\n# Capture command output as string\noutput = command(\"ls -la\", timeout: 5)\n\n# Run command interactively (full terminal)\nshellexec(\"grep -r pattern .\")\n\n# Read a keypress\nchr = getchr\n\n# Clear any displayed image\nclear_image\n\n# Text formatting\n\"text\".fg(112)   # foreground color (0-255)\n\"text\".bg(236)   # background color\n\"text\".b         # bold\n\"text\".u         # underline\n\"text\".r         # reverse\n```\n\n---\n\n## Image Display\n\nRTFM uses the [termpix](https://github.com/isene/termpix) gem for modern multi-protocol image display.\n\n### Supported Protocols\n\n| Terminal | Protocol | Status |\n|----------|----------|--------|\n| urxvt | w3m | ✓ Perfect |\n| xterm | Sixel | ✓ Perfect |\n| mlterm | Sixel | ✓ Perfect |\n| kitty | Kitty | ✓ Perfect |\n| foot | Sixel | ✓ Perfect |\n\n### Features\n\n- **EXIF orientation** - Phone photos display correctly\n- **Auto-detection** - Best protocol for your terminal\n- **Aspect ratio** - Images never stretched\n- **Toggle** - Press `_` to toggle image preview\n- **Copy to clipboard** - Press `Ctrl-y` on image\n\n### Terminal Compatibility\n\nBest image experience with: kitty, urxvt, xterm, mlterm, foot\n\n---\n\n## RTFM vs Ranger\n\n| Feature | RTFM | Ranger |\n|---------|------|--------|\n| **Language** | Pure Ruby | Python |\n| **Size** | ~6K lines (single file) | ~22K lines (modular) |\n| **License** | Unlicense (public domain) | GPL v3 |\n| **LS_COLORS** | Native parsing | Requires theming |\n| **Remote SSH/SFTP** | ✓ Built-in | ✗ |\n| **Undo System** | ✓ Comprehensive | Limited |\n| **Trash Bin** | ✓ With restore | ✗ |\n| **OpenAI Integration** | ✓ | ✗ |\n| **Permission/Ownership Undo** | ✓ | ✗ |\n| **Image Protocols** | Sixel + w3m | Various (ueberzug, kitty) |\n| **Tab Management** | ✓ Enhanced | ✓ Basic |\n| **Bulk Rename** | ✓ Patterns | ✓ |\n| **Plugin System** | Ruby-based | Python-based |\n| **Community** | Small | Large (16.6k stars) |\n| **Documentation** | Growing | Extensive |\n\n**Philosophy:**\n- **Ranger**: Minimalistic, \"do one thing well\"\n- **RTFM**: Feature-packed, \"jam packed with features\"\n\n**Best for:**\n- **RTFM**: Power users wanting SSH workflows, undo, AI integration, maximum features\n- **Ranger**: Users wanting clean, minimal, well-documented VIM-style navigation\n\n---\n\n## Documentation\n\n- **Man page**: `man rtfm`\n- **Interactive help**: Press `?` in RTFM\n- **GitHub**: https://github.com/isene/RTFM\n- **Changelog**: See [CHANGELOG.md](CHANGELOG.md)\n- **Issues/Bugs**: https://github.com/isene/RTFM/issues\n\n### Additional Guides\n\n- [Getting Started](docs/getting-started.md) - Installation, first run, basic operations\n- [Configuration Guide](docs/configuration.md) - Complete settings reference\n- [Remote Browsing](docs/remote-browsing.md) - SSH/SFTP workflows\n- [Plugin Development](docs/plugins.md) - Extend RTFM with custom handlers\n\n---\n\n## Screenshots\n\n![RTFM in action](img/screenshot-logo.png)\n\n**Keyboard Cheat Sheet:**\n\n![RTFM keyboard reference](img/rtfm-kb.png)\n\n---\n\n## Latest Updates\n\n### Version 8.2 Highlights\n\n- **Plugin system with live enable/disable** - Plugins in `~/.rtfm/plugins/` are auto-loaded on startup. Toggle them on and off at runtime with the plugin manager (`V` key), no restart needed. Each plugin can register help text viewable with `?`.\n- **Seven example plugins** - Settings editor, git operations, directory bookmarks, file notes, custom file openers, disk usage analyzer, and duplicate file finder. Copy from `examples/` to `~/.rtfm/plugins/` to use.\n- **Trash browser** (`D` key) - Browse trash contents with timestamps and original paths. Restore files to their original location, permanently delete individual items, or empty all trash.\n\n### Version 8.1 Highlights\n\n- **File picker mode** - `rtfm --pick=/path/to/output.txt` launches RTFM as a file selector. Browse and tag files normally with `t`, then quit with `q`. Tagged file paths are written one per line to the output file. Enables integration with email clients, upload tools, and other applications that need a file selection dialog.\n\n### Version 7.3 Highlights\n\n- **Modern image display** with termpix gem (Sixel + w3m protocols)\n- **Performance optimizations** for large images\n- **UTF-16 file support** for opening in $EDITOR\n- **Image clipboard copy** (Ctrl-y)\n- **Persistent selection** after operations\n\n### Version 7.2 - BREAKING CHANGE\n\n**Batch operations** now use consistent \"tagged OR selected\" logic:\n- Tagged items exist → operate ONLY on tagged\n- No tagged items → operate on selected\n\n**Migration:** Explicitly tag selected item with `t` if you want it included.\n\nSee [CHANGELOG.md](CHANGELOG.md) for complete version history.\n\n---\n\n## How It Works\n\nRTFM is a two-pane file manager with enhanced tab support:\n\n- **Left pane**: Directory/file list with navigation\n- **Right pane**: Preview, info, command output\n- **Top bar**: Current path and file metadata\n- **Bottom bar**: Status, prompts, commands\n- **Tab indicator**: `[2/5]` shows current tab position\n\n**Tab Features:**\n- Multiple tabs for multi-directory management\n- Duplicate tabs (`}`) to copy directory context\n- Rename tabs (`{`) for organization\n- Quick switch with number keys (1-9)\n\n**Enhanced UX:**\n- VIM-style navigation (hjkl)\n- Arrow key support\n- Persistent bookmarks and tagged items\n- Command history across sessions\n- Comprehensive undo for safety\n\n---\n\n## First Run\n\nOn first launch, RTFM:\n1. Shows welcome message\n2. Adds `r` function to your shell (~/.bashrc, ~/.zshrc)\n3. Creates `~/.rtfm/` directory\n4. Generates plugin templates\n\nThe `r` function lets you:\n- Launch RTFM with single key\n- Exit into RTFM's current directory (not launch directory)\n\n**Workflow:**\n```bash\nr              # Launch RTFM\n# Navigate to desired directory\nq              # Exit RTFM\npwd            # You're in RTFM's last directory!\nr              # Back into RTFM\n```\n\n---\n\n## Why RTFM?\n\nCreated to solve a specific problem: file managers should parse LS_COLORS natively instead of requiring separate themes.\n\n**The Origin Story:**\n\nWhile working on a [complete LS_COLORS setup](https://github.com/isene/LS_COLORS), I realized creating a matching ranger theme was redundant. File managers should respect terminal colors by default.\n\nThis became RTFM - a file manager that parses LS_COLORS automatically.\n\n**Why Rewrite?**\n\nThe old curses library was clumsy. So I created [rcurses](https://github.com/isene/rcurses) - a modern, pure Ruby curses implementation. From v5 onwards, RTFM runs on rcurses, providing:\n- Better stability\n- Cleaner code\n- More features\n- Active development\n\n---\n\n## Development\n\n### For Users\n\nBug reports and feature requests welcome at: https://github.com/isene/RTFM/issues\n\n### For Developers\n\n**Ruby Debug Mode:**\nPress `@` to enter Ruby REPL mode. Execute arbitrary Ruby code:\n```ruby\n# Examples:\nputs @selected        # Show current selection\nputs @tagged.inspect  # Show tagged items\nputs @marks          # Show bookmarks\n```\n\n**Plugin Development:**\nSee `~/.rtfm/plugins/` directory for templates and examples.\n\n**Contributing:**\nThis is a personal project built for my needs. Cool feature requests may be included. Code contributions welcome via pull requests.\n\n---\n\n## Author\n\n**Geir Isene**\n- Email: g@isene.com\n- Web: https://isene.com\n- GitHub: https://github.com/isene\n\n## License\n\n**Unlicense** - Public Domain\n\nPermission granted to use, copy, modify, distribute, and sell this software for any purpose without restriction.\n\n---\n\n## See Also\n\n- [rcurses](https://github.com/isene/rcurses) - Pure Ruby curses library\n- [termpix](https://github.com/isene/termpix) - Terminal image display gem\n- [ranger](https://github.com/ranger/ranger) - Python-based file manager\n- [LS_COLORS](https://github.com/isene/LS_COLORS) - Comprehensive terminal color setup\n\n---\n\n**Stay Amazing** ✓\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fisene%2FRTFM","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fisene%2FRTFM","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fisene%2FRTFM/lists"}