diff --git a/docs/fish-config.index b/docs/fish-config.index index 5528880..5b3cbcf 100644 --- a/docs/fish-config.index +++ b/docs/fish-config.index @@ -288,9 +288,30 @@ personalize=# 10. PERSONALIZATION secrets-file=## secrets.fish local-config=## local.fish -# ── Section 11: Viewing This Manual ────────────────────────── -viewing=# 11. VIEWING THIS MANUAL -manual=# 11. VIEWING THIS MANUAL +# ── Section 11: Troubleshooting ────────────────────────────── +troubleshooting=# 11. TROUBLESHOOTING +troubleshoot=# 11. TROUBLESHOOTING +faq=# 11. TROUBLESHOOTING +uninstall=## Uninstalling / Reverting to Backup +revert=## Uninstalling / Reverting to Backup +fish-version=## Fish Version Requirement +version-req=## Fish Version Requirement +disable-logging=## Disable Session Logging +disable-greeting=## Change or Disable the Greeting +change-greeting=## Change or Disable the Greeting +secrets-trouble=## Secrets and Machine-Local Configuration +local-trouble=## Secrets and Machine-Local Configuration +return-sentinel=## Tool Init Does Nothing (Return Sentinel) +tool-init=## Tool Init Does Nothing (Return Sentinel) +missing-deps=## Missing Dependencies +vi-mode=## Vi Mode Keybindings +vi-trouble=## Vi Mode Keybindings +emacs-mode=## Vi Mode Keybindings +minimal-trouble=## Minimal Mode / Disabling Opinionated Features + +# ── Section 12: Viewing This Manual ────────────────────────── +viewing=# 12. VIEWING THIS MANUAL +manual=# 12. VIEWING THIS MANUAL ov=## In the terminal man-page=## As a man page manpage=## As a man page @@ -298,3 +319,5 @@ jump=## In the terminal html=## The documentation website browser=## The documentation website site=## The documentation website + + diff --git a/docs/manual/00-table-of-contents.md b/docs/manual/00-table-of-contents.md index 74d43ad..2291ec4 100644 --- a/docs/manual/00-table-of-contents.md +++ b/docs/manual/00-table-of-contents.md @@ -42,6 +42,16 @@ sidebar: 8. Fisher Plugins 9. Installation 10. Personalization - 11. Viewing This Manual + 11. Troubleshooting + 11.1 Uninstalling / Reverting to Backup + 11.2 Fish Version Requirement + 11.3 Disable Session Logging + 11.4 Change or Disable the Greeting + 11.5 Secrets and Machine-Local Configuration + 11.6 Tool Init Does Nothing (Return Sentinel) + 11.7 Missing Dependencies + 11.8 Vi Mode Keybindings + 11.9 Minimal Mode / Disabling Opinionated Features + 12. Viewing This Manual --- diff --git a/docs/manual/11-troubleshooting.md b/docs/manual/11-troubleshooting.md new file mode 100644 index 0000000..25068e4 --- /dev/null +++ b/docs/manual/11-troubleshooting.md @@ -0,0 +1,233 @@ +--- +title: Troubleshooting +manTitle: 11. TROUBLESHOOTING +sidebar: + order: 15 +helpKeywords: +- troubleshooting +- troubleshoot +- faq +- help +- uninstall +- revert +--- + +## Uninstalling / Reverting to Backup + +The installation step backs up any existing config to `~/.config/fish.bak`. +To revert: + + rm -rf ~/.config/fish + mv ~/.config/fish.bak ~/.config/fish + +If no backup exists, remove the directory and let Fish regenerate a default +config on next launch: + + rm -rf ~/.config/fish + fish -c 'fish_config theme choose "Fish default"' + +Clean up files generated outside the config directory: + + rm -f ~/.local/bin/paru ~/.local/bin/yay # AUR log wrappers + rm -f ~/.local/share/man/man1/fish-config.1 # man page symlink + rm -f ~/.config/fish/.logging_disabled # C5 sentinel + +Erase universal variables set by this config: + + for v in (set -Un | string match '__fish_config*') + set -Ue $v + end + for v in __done_min_cmd_duration __done_notification_urgency_level + set -Ue $v + end + for v in (set -Un | string match 'sponge_*') + set -Ue $v + end + +The `~/.terminal_history/` log directory contains your session logs. Remove +it only if you do not want to keep them. + +## Fish Version Requirement + +This config requires Fish 4.x or newer. Check your version: + + fish --version + +Run `fish-deps` to see a status report — an outdated Fish shows ⚠ with an +upgrade message. + +Upgrading Fish by distribution: + + # Arch / AUR + pacman -S fish # or paru -S fish + + # Ubuntu / Debian (PPA) + sudo apt-add-repository ppa:fish-shell/release-4 + sudo apt update && sudo apt install fish + + # Fedora + sudo dnf install fish + + # macOS + brew install fish + +For other systems or building from source, see https://fishshell.com. + +## Disable Session Logging + +Disable all logging and capture (scrollback, tmux/zellij pane logs, AUR +helper wrappers, Kitty watcher): + + set -U __fish_config_op_logging off + +Or toggle it interactively: run `config-settings` and flip the Logging row. + +This takes effect immediately in all running shells — no restart needed. The +sentinel file, wrapper removal, and pipe-pane teardown happen automatically. + +Re-enable: + + set -Ue __fish_config_op_logging + +See Section 7, "C5 — Logging and Capture" for the full component breakdown. + +## Change or Disable the Greeting + +This config suppresses the distro greeting (e.g. CachyOS fastfetch) by +default. To let the distro greeting through: + + set -U __fish_config_op_greeting off + +To set a custom greeting, define fish_greeting in your local.fish: + + # in $__fish_user_dots_path/local.fish + function fish_greeting + echo "Hello, world!" + end + +The first-run welcome banner runs exactly once. To re-trigger it (e.g. for +testing): + + set -Ue __fish_config_first_run_complete + +See Section 7, "C6 — Greeting and First-Run UI" for details. + +## Secrets and Machine-Local Configuration + +Machine-specific config goes in `$__fish_user_dots_path/local.fish` (defaults +to `~/.config/.user-dots/fish/local.fish`). Secrets go in `secrets.fish` in +the same directory. + +If local.fish is not loading, verify the path: + + echo $__fish_user_dots_path + test -f "$__fish_user_dots_path/local.fish"; and echo exists; or echo missing + +Change the path via variable or TUI: + + set -U __fish_user_dots_path /new/path/to/dots/fish + +Or run `config-settings`, navigate to the Paths page, and edit "Dots path". + +The `user-dots` convenience symlink in the config directory tracks this path. +Disable it with: + + set -U __fish_user_dots_symlink false + +See Section 10, "Personalization" for the full local.fish / secrets.fish +layout. + +## Tool Init Does Nothing (Return Sentinel) + +Symptom: you ran a tool's setup command (e.g. +`starship init fish >> ~/.config/fish/config.fish`) and nothing changed. + +Cause: config.fish ends with a `return` guard. Any lines appended after it +are never executed. + +Fix: create a dedicated conf.d file instead of appending to config.fish: + + # ~/.config/fish/conf.d/mytool.fish + mytool init fish | source + +All existing integrations (starship, zoxide, direnv) already have conf.d/ +files. See Section 9, "Return Sentinel" for background. + +## Missing Dependencies + +Run `fish-deps` (defaults to `fish-deps status`) to see what is installed +and what is missing. Common symptoms and their missing tools: + + Symptom Missing tool + ───────────────────────────────────────────────────── + ls output has no icons or colors eza (or lsd) + cd does not remember directories zoxide + cat shows no syntax highlighting bat + fzf keybindings do nothing fzf + Starship prompt not appearing starship + +Install missing dependencies interactively: + + fish-deps install + +Or install everything missing and update what is installed: + + fish-deps sync + +See Section 6, "Dependency Catalog" for the full list grouped by tier +(required, integrations, recommended). + +## Vi Mode Keybindings + +This config enables Vi mode by default (via C3 overrides), replacing the +standard Emacs-style bindings. If Vi mode interferes with your workflow, +override it in local.fish: + + # in $__fish_user_dots_path/local.fish + fish_default_key_bindings + +This restores Emacs-style bindings without disabling the rest of C3 +(bang-bang, autopair, starship prompt, pager settings, etc.). + +To disable the entire C3 category (Vi mode and all other key/environment +overrides): + + set -U __fish_config_op_overrides off + +See Section 7, "C3 — Key and Environment Overrides" for the full list of +what C3 controls. + +## Minimal Mode / Disabling Opinionated Features + +Disable all opinionated features at once: + + set -U __fish_config_opinionated 0 + +This turns off all six categories (aliases, auto-exec, overrides, +integrations, logging, greeting) — leaving a clean shell with only PATH, +XDG variables, and local.fish sourcing. + +Disable a single category: + + set -U __fish_config_op_aliases off # C1 — command shadows + set -U __fish_config_op_autoexec off # C2 — startup side-effects + set -U __fish_config_op_overrides off # C3 — key/env overrides + set -U __fish_config_op_integrations off # C4 — terminal integrations + set -U __fish_config_op_logging off # C5 — logging and capture + set -U __fish_config_op_greeting off # C6 — greeting + +Keep one category active under a master disable: + + set -U __fish_config_opinionated 0 + set -U __fish_config_op_aliases 1 # only C1 stays on + +Re-enable everything: + + set -Ue __fish_config_opinionated + +Or use the interactive TUI: `config-settings`. + +See Section 7, "Opinionated Components (Minimal Mode)" for the full +component reference tables. + +--- diff --git a/docs/manual/11-viewing-this-manual.md b/docs/manual/12-viewing-this-manual.md similarity index 98% rename from docs/manual/11-viewing-this-manual.md rename to docs/manual/12-viewing-this-manual.md index 854f86d..e080ce9 100644 --- a/docs/manual/11-viewing-this-manual.md +++ b/docs/manual/12-viewing-this-manual.md @@ -1,8 +1,8 @@ --- title: Viewing This Manual -manTitle: 11. VIEWING THIS MANUAL +manTitle: 12. VIEWING THIS MANUAL sidebar: - order: 15 + order: 16 helpKeywords: - viewing - manual