Merge pull request 'docs: add Section 11 — Troubleshooting' (#83) from docs/add-troubleshooting-section into main

Reviewed-on: #83
2026-07-27 03:59:43 +00:00
parent 1b69ff9a7f 24cdfe4129
commit 0f02def439
4 changed files with 272 additions and 6 deletions
@@ -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
+
+
@@ -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

 ---
@@ -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.
+
+---
@@ -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