{"id":26167523,"url":"https://github.com/open-technology-foundation/rtfm","last_synced_at":"2026-04-28T05:38:10.257Z","repository":{"id":280375174,"uuid":"941779443","full_name":"Open-Technology-Foundation/rtfm","owner":"Open-Technology-Foundation","description":"A smart command-line utility that searches for documentation about commands across multiple help systems.","archived":false,"fork":false,"pushed_at":"2025-09-17T01:34:45.000Z","size":121,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-17T03:20:16.366Z","etag":null,"topics":["bash","manuals"],"latest_commit_sha":null,"homepage":"https://yatti.id/","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Open-Technology-Foundation.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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":"2025-03-03T03:16:04.000Z","updated_at":"2025-09-17T01:34:48.000Z","dependencies_parsed_at":"2025-03-03T04:24:29.360Z","dependency_job_id":"8293971d-f5cf-4ed3-b3e6-3e565bec5d7d","html_url":"https://github.com/Open-Technology-Foundation/rtfm","commit_stats":null,"previous_names":["open-technology-foundation/rtfm"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Open-Technology-Foundation/rtfm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Open-Technology-Foundation%2Frtfm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Open-Technology-Foundation%2Frtfm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Open-Technology-Foundation%2Frtfm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Open-Technology-Foundation%2Frtfm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Open-Technology-Foundation","download_url":"https://codeload.github.com/Open-Technology-Foundation/rtfm/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Open-Technology-Foundation%2Frtfm/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28020071,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-25T02:00:05.988Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["bash","manuals"],"created_at":"2025-03-11T17:38:34.140Z","updated_at":"2026-04-28T05:38:10.226Z","avatar_url":"https://github.com/Open-Technology-Foundation.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# rtfm - Read The Fucking Manuals\n\nA unified Linux documentation lookup tool that consolidates help information from multiple sources into a single, easy-to-use interface.\n\n## Overview\n\n`rtfm` solves the common problem of fragmented documentation by searching across all available help systems and presenting the results in one place. Instead of remembering whether to use `man`, `info`, `help`, or `tldr`, just use `rtfm`.\n\n## Features\n\n- **Multi-source documentation search** in priority order:\n  1. Bash builtin help\n  2. Man pages (from all directories in `manpath`)\n  3. Info pages\n  4. TLDR pages (simplified examples)\n  5. Command --help (automatic fallback for scripts)\n- **Smart color detection**: Automatically disables ANSI colors when redirecting to files or pipes\n- **Color control**: Respects standard environment variables (`NO_COLOR`, `FORCE_COLOR`, `CLICOLOR_FORCE`)\n- **Fast O(1) lookups**: Pre-built indices enable instant searches\n- **Update detection**: Warns when new man pages are installed\n- **Secure updates**: SHA256 checksum verification with automatic rollback\n- **Enhanced formatting**: Optional markdown rendering with `md2ansi`\n- **Smart fallback**: Automatically detects and runs `--help` for text-based scripts\n- **Clean pagination**: Integrated with `less` for easy navigation\n- **Security hardened**: Input validation, PATH lockdown, privilege checks\n\n## Installation\n\n### Quick Install\n\n```bash\n# One-liner installation\nwget https://raw.githubusercontent.com/Open-Technology-Foundation/rtfm/main/rtfm \u0026\u0026 chmod +x rtfm \u0026\u0026 sudo ./rtfm --install\n```\n\n### Step-by-Step Install\n\n```bash\n# Download the script\nwget https://raw.githubusercontent.com/Open-Technology-Foundation/rtfm/main/rtfm\n\n# Make it executable\nchmod +x rtfm\n\n# Install rtfm and dependencies\nsudo ./rtfm --install\n```\n\nThis installs:\n- `rtfm` executable to `/usr/local/bin/rtfm`\n- Documentation indices to `/usr/local/share/rtfm/*.list`\n- `md2ansi` for enhanced markdown formatting\n- `tldr` pages for simplified command examples\n- Pre-generated documentation indices for your system\n\n## Bash Completion\n\nrtfm includes bash completion for tab-completing command names and options.\n\n### System-wide Installation\n\n```bash\n# Copy to system completion directory (all users)\nsudo cp rtfm.bash_completion /etc/bash_completion.d/rtfm\n```\n\n### User-specific Installation\n\n```bash\n# Add to your ~/.bashrc\necho 'source /usr/local/share/rtfm/rtfm.bash_completion' \u003e\u003e ~/.bashrc\n\n# Reload your shell\nsource ~/.bashrc\n```\n\n### Usage\n\nOnce installed, tab completion works for:\n\n```bash\n# Complete options\nrtfm --\u003cTAB\u003e\n# Shows: --help --install --quiet --rebuild-lists --update --verbose --version\n\n# Complete command names from all documentation sources\nrtfm rs\u003cTAB\u003e\n# Shows: rsync, rsh, rstart, ...\n\nrtfm decl\u003cTAB\u003e\n# Completes to: declare\n```\n\n## Usage\n\n### Basic Lookup\n\n```bash\nrtfm \u003ccommand\u003e\n```\n\n### Examples\n\n```bash\n# Look up rsync documentation (finds man page + tldr examples)\nrtfm rsync\n\n# Get help for bash's declare builtin\nrtfm declare\n\n# View comprehensive GNU coreutils documentation\nrtfm coreutils\n\n# Find all documentation for the find command\nrtfm find\n\n# Get help for a custom script (fallback to --help)\nrtfm my-script\n```\n\n### Administrative Commands\n\n```bash\n# Update rtfm and all dependencies\nsudo rtfm --update\n\n# Rebuild documentation indices after installing new packages\nsudo rtfm --rebuild-lists\n\n# Display help\nrtfm --help\n\n# Show version\nrtfm --version\n```\n\n### Options\n\n| Option | Description |\n|--------|-------------|\n| `-r, --rebuild-lists` | Rebuild command lists from documentation sources (requires sudo) |\n| `--install, --update` | Install or update rtfm and dependencies from GitHub |\n| `-v, --verbose` | Verbose output during operations (default) |\n| `-q, --quiet` | Suppress informational messages (warnings still shown) |\n| `-V, --version` | Display version information |\n| `-h, --help` | Show help message |\n| `--` | End of options; next argument is the command name |\n\n## Color Output\n\nrtfm automatically detects terminal capabilities and adjusts ANSI color output accordingly:\n\n### Automatic Behavior\n\n- **Terminal (TTY)**: Colors enabled by default\n  ```bash\n  rtfm ls  # Colorful output in terminal\n  ```\n\n- **Redirected to file**: Colors automatically disabled\n  ```bash\n  rtfm ls \u003e/tmp/ls.txt  # Clean text, no ANSI codes\n  ```\n\n- **Piped to commands**: Colors automatically disabled\n  ```bash\n  rtfm ls | grep -i directory  # Clean text for processing\n  ```\n\n### Environment Variables\n\nControl color output explicitly using standard environment variables:\n\n| Variable | Effect | Example |\n|----------|--------|---------|\n| `NO_COLOR` | Disable all colors (any value) | `NO_COLOR=1 rtfm ls` |\n| `FORCE_COLOR` | Force colors even when redirected | `FORCE_COLOR=1 rtfm ls \u003efile.txt` |\n| `CLICOLOR_FORCE` | Force colors (alternative to FORCE_COLOR) | `CLICOLOR_FORCE=1 rtfm ls` |\n\n### Examples\n\n```bash\n# Disable colors explicitly\nNO_COLOR=1 rtfm ls\n\n# Force colors when redirecting (useful for HTML conversion)\nFORCE_COLOR=1 rtfm ls \u003e/tmp/ls-colored.txt\n\n# Clean text for scripting\nrtfm ls 2\u003e/dev/null | awk '/SYNOPSIS/ {print}'\n```\n\n### Color Detection Mechanism\n\nColor detection happens at multiple levels:\n\n1. **Main headers** (BUILTIN, MAN, INFO, TLDR, COMMAND HELP): Processed by `md2ansi`\n   - Detects stdout TTY status automatically\n   - When not a TTY, uses `TERM=dumb` to disable colors\n\n2. **Man pages**: Uses `GROFF_NO_SGR=1` when colors disabled\n   - Prevents SGR (Select Graphic Rendition) escape sequences\n\n3. **Error messages** (stderr): Independent TTY detection\n   - Diagnostic output can be colored even when stdout is redirected\n   - Useful for scripts: `rtfm ls \u003e/tmp/out.txt` shows colored warnings\n\n## How It Works\n\n### Documentation Sources\n\nrtfm searches these locations in priority order:\n\n1. **Bash Builtins** (`/usr/local/share/rtfm/builtin.list`)\n   - Generated from `compgen -b`\n   - Covers commands like `cd`, `alias`, `declare`, etc.\n\n2. **Man Pages** (`/usr/local/share/rtfm/man.list`)\n   - Searches all directories from `manpath`\n   - Includes both compressed (.gz) and uncompressed pages\n   - Automatically detects new installations\n\n3. **Info Pages** (`/usr/local/share/rtfm/info.list`)\n   - GNU project documentation\n   - Often more detailed than man pages\n\n4. **TLDR Pages** (`/usr/local/share/rtfm/tldr.list`)\n   - Community-maintained simplified examples\n   - Great for quick command usage references\n\n5. **Command --help** (automatic fallback)\n   - For executable scripts without formal documentation\n   - Detects if script contains `--help` option\n   - Only runs if script is a text file (not binary)\n\n### Update Detection\n\nrtfm monitors man page directories and warns when new pages are installed:\n\n```\nrtfm: ▲ New man pages detected. Run 'sudo rtfm --rebuild-lists' to update the index.\n```\n\nThis ensures your documentation index stays current without manual intervention.\n\n### Security Features\n\n- **Input validation**: Whitelists safe characters, blocks shell metacharacters and path traversal\n- **PATH lockdown**: Locked to `/usr/local/bin:/usr/bin:/bin` to prevent command injection\n- **SHA256 checksums**: Verifies integrity of downloaded files during updates\n- **Secure temp files**: Uses `mktemp` for unpredictable temp file names (prevents symlink attacks)\n- **Automatic rollback**: Restores previous version if update fails\n- **Privilege checks**: Uses `can_sudo()` to verify permissions before system changes\n\n## Architecture\n\n### Fast Lookups with Pre-built Indices\n\nInstead of scanning the filesystem every time, rtfm uses pre-built indices (`.list` files) for O(1) lookups:\n\n- `builtin.list` - Bash builtins (from `compgen -b`)\n- `man.list` - All man pages from manpath directories\n- `info.list` - GNU info pages\n- `tldr.list` - TLDR simplified examples\n\nThese indices are created during installation and can be rebuilt with `sudo rtfm --rebuild-lists`.\n\n### Install/Update System\n\nThe `--install` and `--update` flags create a secure temporary installer script:\n1. Generate unpredictable temp file via `mktemp` (self-cleaning on EXIT)\n2. Clone rtfm, md2ansi, and tldr from GitHub to `.tmp` directories\n3. Verify SHA256 checksums (if sha256sum available)\n4. Back up existing installations to `.bak`\n5. Atomically move verified repositories to final locations\n6. Roll back to `.bak` on failure\n7. Rebuild all documentation indices\n\n### Output Pipeline\n\nDocumentation is concatenated with page breaks and piped through:\n- `md2ansi` for markdown formatting (TLDR content and headers)\n  - Automatically detects TTY and adjusts color output\n  - Respects `NO_COLOR` and `FORCE_COLOR` environment variables\n- `less -RFSX` for pagination with color support\n\n## File Locations\n\n- **Executable**: `/usr/local/bin/rtfm`\n- **Documentation indices**: `/usr/local/share/rtfm/*.list`\n- **Bash completion**: `/usr/local/share/rtfm/rtfm.bash_completion`\n- **Manpage**: `/usr/local/share/man/man1/rtfm.1`\n- **Repository**: `/usr/local/share/rtfm/` (reference/documentation)\n- **TLDR pages**: `/usr/local/share/tldr/`\n- **md2ansi**: `/usr/local/share/md2ansi/`\n\n## Dependencies\n\n### Required\n- **bash** (5.2+): Script execution environment\n- **grep**: Searching through lists\n- **less**: Paginated viewing\n- **man**: Man page system\n- **info**: GNU info system\n\n### Optional (Installed Automatically)\n- **git**: For installation/updates\n- **tldr**: Simplified command examples\n- **md2ansi**: Enhanced markdown formatting\n- **sha256sum**: Checksum verification (recommended)\n- **file**: For detecting script types in --help fallback\n\n## Troubleshooting\n\n### rtfm not finding a command\n\n```bash\n# Rebuild the documentation indices\nsudo rtfm --rebuild-lists\n```\n\n### Installation fails\n\n```bash\n# Check if you have sudo access\ngroups | grep -E 'sudo|admin|wheel'\n\n# Install git manually if needed\nsudo apt-get install git\n```\n\n### Checksum verification fails\n\n```bash\n# Install sha256sum for security\nsudo apt-get install coreutils\n\n# Or skip verification (not recommended)\n# The installer will warn but continue\n```\n\n### Colors appear in redirected files\n\n```bash\n# This should not happen with latest version\n# If it does, use NO_COLOR to disable:\nNO_COLOR=1 rtfm ls \u003e/tmp/file.txt\n\n# Or check md2ansi version:\nmd2ansi --version  # Should be 0.9.6-bash or later\n```\n\n### Bash completion not working\n\n```bash\n# Verify completion file exists\nls -la /usr/local/share/rtfm/rtfm.bash_completion\n\n# Source it manually to test\nsource /usr/local/share/rtfm/rtfm.bash_completion\n\n# Verify completion is registered\ncomplete -p rtfm\n# Should output: complete -F _rtfm rtfm\n\n# If not installed system-wide, add to ~/.bashrc:\necho 'source /usr/local/share/rtfm/rtfm.bash_completion' \u003e\u003e ~/.bashrc\n```\n\n## Development\n\n### Code Standards\n\nThis project follows strict Bash coding standards:\n\n- **Bash Coding Standard (BCS)** - Full compliance with comprehensive Bash 5.2+ standard\n  - Bottom-up function organization (messaging → validation → business logic → main)\n  - Proper variable expansion (`\"$var\"` without unnecessary braces)\n  - Single quotes for static strings, double quotes only when needed\n  - Case statements following one-word literal exception (`case $1 in`)\n- **ShellCheck validation** - Zero warnings (compulsory)\n- **Security-first design** - PATH lockdown, input validation, checksum verification\n- **Proper error handling** - `set -euo pipefail` with comprehensive die() function\n- **2-space indentation** - Consistent formatting throughout\n\n### Testing\n\n```bash\n# Lint all shell scripts\nshellcheck rtfm rtfm.bash_completion update-checksums.sh\n\n# Test basic functionality\nrtfm --help\nrtfm --version\nrtfm echo\n\n# Test color detection\nrtfm ls                      # Should have colors in TTY\nrtfm ls \u003e/tmp/test.txt       # Should be clean text\nNO_COLOR=1 rtfm ls           # Should have no colors\nFORCE_COLOR=1 rtfm ls \u003e/tmp/test.txt  # Should have colors\n\n# Test bash completion\nsource rtfm.bash_completion\ncomplete -p rtfm             # Should show: complete -F _rtfm rtfm\n\n# Test rebuilding indices (requires sudo)\nsudo rtfm --rebuild-lists\n```\n\n### Contributing\n\n1. Fork the repository\n2. Make your changes following the Bash Coding Standard (BCS)\n3. Run `./update-checksums.sh` before committing\n4. Ensure `shellcheck rtfm` passes with no warnings\n5. Submit a pull request\n\n## Version History\n\n### v1.2.1 (Current) - FHS Migration \u0026 Bug Fix\n\n- Migrated to FHS-compliant installation structure (`/usr/local/share/`)\n- Fixed `info()` function incorrectly included in function exports during install/update\n- Improved BCS compliance, security hardening, and documentation\n\n### v1.2.0 - Smart Color Detection \u0026 Code Quality\n\n**Color Output Features:**\n- ✅ **Automatic TTY detection** - ANSI colors automatically disabled when output is redirected to files or pipes\n- ✅ **Environment variable support** - Respects `NO_COLOR`, `FORCE_COLOR`, and `CLICOLOR_FORCE` standard variables\n- ✅ **md2ansi integration** - Uses `TERM=dumb` to disable colors in markdown formatting when appropriate\n- ✅ **Man page color control** - Sets `GROFF_NO_SGR=1` to prevent SGR escape sequences when colors disabled\n- ✅ **Independent stderr colors** - Error/warning messages check TTY separately for better UX\n\n**Architecture Improvements:**\n- ✅ **Manpage** - Added `rtfm.1` man page with full feature documentation\n- ✅ **Bash completion** - Renamed to `rtfm.bash_completion` with optimized completion function\n\n**Security Improvements:**\n- ✅ **Secure temp files** - Replaced hardcoded temp path with `mktemp` to prevent symlink attacks\n- ✅ **Self-cleaning installer** - EXIT trap automatically removes temp script after installation\n- ✅ **PATH security lockdown** - Locked to `/usr/local/bin:/usr/bin:/bin`\n\n**BCS Compliance:**\n- ✅ **100% BCS compliance** - Systematic code review and refactoring\n- ✅ **Bottom-up function organization** - Proper dependency order (messaging → validation → business logic → main)\n- ✅ **Variable expansion cleanup** - Removed ~55 unnecessary braces\n- ✅ **String quoting standardization** - Static strings use single quotes\n- ✅ **ShellCheck compliance** - Zero warnings across all shell scripts\n- ✅ **Standard shopts** - Added `inherit_errexit shift_verbose extglob nullglob` to all scripts\n- ✅ **Script markers** - All scripts end with `#fin` marker per BCS standard\n\n**Documentation \u0026 Usability:**\n- Rewrote `show_help()` with 8 comprehensive sections (added ENVIRONMENT)\n- Completely rewrote README.md with color detection and bash completion documentation\n- Added comprehensive inline documentation\n- Added manpage (`rtfm.1`) with full feature documentation\n\n**Result:** Clean text output when redirected, colored output in terminals, with full user control via environment variables\n\n### v1.1.0\n- Added checksum verification for secure updates\n- Implemented automatic rollback on failed updates\n- Enhanced security with input validation\n- Added smart --help fallback for scripts\n\n### v1.0.0\n- Initial release\n- Multi-source documentation search\n- Pre-built indices for fast lookups\n- Integrated pagination\n\n## License\n\nGNU General Public License v3.0 - see [LICENSE](LICENSE) for details.\n\n## Links\n\n- [GitHub Repository](https://github.com/Open-Technology-Foundation/rtfm)\n- [md2ansi](https://github.com/Open-Technology-Foundation/md2ansi)\n- [tldr](https://github.com/Open-Technology-Foundation/tldr)\n- [NO_COLOR Standard](https://no-color.org/)\n\n## Related Projects\n\n- **man**: Traditional Unix manual pages\n- **info**: GNU documentation system\n- **tldr**: Simplified community-driven man pages\n- **cheat**: Interactive cheat sheets\n- **bro pages**: Crowd-sourced examples\n\n---\n\n**rtfm** - Because reading the manual shouldn't require a manual.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopen-technology-foundation%2Frtfm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopen-technology-foundation%2Frtfm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopen-technology-foundation%2Frtfm/lists"}