Sean (ANGRYxScotsman)
2fcd7cf878
* Add Hugo build artifacts to .gitignore Ignore docs/public/, docs/resources/, and docs/.hugo_build.lock so generated Hugo output is never accidentally committed. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * Add Hugo site infrastructure for Linutil docs Adds the Hugo configuration, theme module (hextra), layout shortcodes, i18n strings, static assets (favicons, nav logo), and archetype template needed to build the documentation site. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * Add docs site homepage Adds the root _index.md with badges, the quick-start curl command, and an important-note callout about frequent updates. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * Add user guide content pages for Linutil Rewrites all user guide sections from Winutil (Windows) content to accurate Linutil (Linux) documentation: - _index.md: overview, feature summary, quick links - getting-started.md: how to run, install options, TUI navigation, keyboard shortcuts - store/_index.md: application installation guide with category tables - tweaks/_index.md: distro-specific system setup (Arch, Fedora, Debian, Ubuntu, Alpine) - features/_index.md: security, gaming, emulators, and utilities reference - updates/_index.md: how to keep Linutil up to date - automation/_index.md: TOML config file usage and use-case examples Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * Add FAQ, known issues, and contributing guide pages - faq.md: answers for general usage, running, scripts, contributing, and updates - KnownIssues.md: documents terminal size, rendering, distro support, Nvidia, and Cargo update issues - CONTRIBUTING.md: full contributing guide based on .github/CONTRIBUTING.md, formatted for the docs site Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * Add developer reference section and architecture docs - dev/_index.md: landing page for the developer reference section - dev/architecture.md: comprehensive architecture doc covering workspace layout, data model (Tab/ListNode/Command), tab_data.toml format, task list flags, preconditions system, script embedding via include_dir!, the script execution pipeline (PTY/vt100/tui-term), TUI layout and focus state machine, config file parsing, and key dependencies Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * docgen: write walkthrough to docs/content/userguide/walkthrough.md - Rename generated file from userguide.md to walkthrough.md to better reflect that it is an auto-generated script reference/walkthrough - Update USER_GUIDE path to docs/content/userguide/walkthrough.md so cargo xtask docgen writes to the correct Hugo content location - Update automation guide link to point to ../walkthrough/ Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * docs: remove unused Winutil screenshot assets All images in docs/assets/images/ were Winutil (Windows) screenshots copied over from the Winutil docs. None are referenced by any content file. Keeping only favicon.png and navlogo.png at the assets root, which are used by hugo.toml. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * Update CNAME * updated hugo configs * docs: add preview.gif to homepage via Hugo mount Mount .github/preview.gif directly into Hugo's static pipeline using includeFiles so only the gif is exposed (no workflows or other .github files). This means any update to .github/preview.gif is automatically reflected on the site without any manual copying. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * added workflow * Delete docs/assets/navlogo.png can change this to something else * Delete navlogo.png * Update docs.yaml * Update hugo.toml * Update _index.md * fix typo --------- Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
2.8 KiB
title, toc
| title | toc |
|---|---|
| Known Issues | true |
This page tracks known issues and limitations in Linutil. If you encounter a bug not listed here, please open an issue on GitHub.
Terminal Compatibility
Minimum Terminal Size
Linutil requires a minimum terminal size to display the TUI correctly. If your terminal is too small, you will see a warning and the TUI will not load.
Workaround: Resize your terminal to be larger, or use the --size-bypass flag:
curl -fsSL https://christitus.com/linux | sh -s -- --size-bypass
Rendering Issues in Some Terminals
The TUI is built with ratatui and tested against common terminals (Alacritty, Kitty, GNOME Terminal, Konsole, etc.). Older or minimalist terminals may have rendering issues with box-drawing characters.
Workaround: Use a modern terminal emulator.
Script-Specific Issues
Scripts May Fail on Unsupported Distros
Some scripts are written for a specific distribution (e.g., Arch, Fedora). Running them on an unsupported distro may fail or produce unexpected results.
Workaround: Only run scripts listed under your distro's section in System Setup, or scripts that are explicitly distro-agnostic.
Nvidia Driver Scripts Require Manual Steps on Some Systems
The Nvidia driver installation scripts may not cover every hardware configuration. Secure Boot, older GPUs, or custom kernel setups can cause driver installation to fail.
Workaround: Refer to your distro's official Nvidia documentation for manual installation if the script fails.
Cargo Installs Require Manual Updates
If you installed Linutil via cargo install linutil_tui, updates are not automatic.
Workaround: Use the built-in Linutil Updater script inside the TUI, or run:
cargo install --force linutil_tui
Active Development
Linutil is under active development. Since scripts are contributed by the community and updated frequently, some scripts may:
- Lag behind upstream package name changes
- Temporarily break after a distro update changes a package or dependency
- Not yet cover all edge cases for every distro version
Workaround: Check open issues and recent pull requests for known fixes. Running the stable curl command always fetches the latest release:
curl -fsSL https://christitus.com/linux | sh
Reporting Bugs
When opening a bug report, please include:
- Your Linux distribution and version
- Terminal emulator being used
- The exact script or menu item that failed
- The full error output from the terminal
- Steps to reproduce the issue