rootiest/fish-config
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: move Viewing This Manual to last position (§11)

Browse Source 
Reorder sections so Installation (§9) and Personalization (§10) precede
Viewing This Manual (§11). Update TABLE OF CONTENTS and regenerate wiki;
old 9-viewing-this-manual.md replaced by 11-viewing-this-manual.md.
This commit is contained in:
Rootiest
2026-06-08 16:48:37 -04:00
parent 345d0086a5
commit f444bfa464
13 changed files with 261 additions and 101 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/fish-config.md
+90 -90
View File
@@ -103,9 +103,9 @@ The configuration is split across:
6. Dependency Catalog
7. Customization
8. Fisher Plugins
9. Viewing This Manual
10. Installation
11. Personalization
9. Installation
10. Personalization
11. Viewing This Manual
---
@@ -1432,7 +1432,93 @@ calls fisher update as its first step.
---
# 9. VIEWING THIS MANUAL
# 9. INSTALLATION
This configuration is managed as a git repository. To deploy on a new machine:
mv ~/.config/fish ~/.config/fish.bak # back up any existing config
git clone https://git.rootiest.dev/rootiest/fish-config.git ~/.config/fish
Then open a new Fish shell. Fisher and all plugins install automatically on
first launch and the Catppuccin Mocha theme is applied.
## Return Sentinel
config.fish ends with a return sentinel guard. Any lines appended after it by
a tool's setup command (starship init fish | source, zoxide init fish | source,
etc.) will have no effect. All integrations are managed via conf.d/ files.
If a new tool's shell integration appears to do nothing, check whether its
setup command appended an init line below the sentinel and create a dedicated
conf.d/<tool>.fish instead.
## Updating
Pull the latest changes from the upstream repository without needing a
configured git remote:
config-update Fetch and apply the latest commits from upstream
config-update --dry-run Preview available changes without applying them
config-update --force Stash local changes, pull, then restore the stash
The remote URL (https://git.rootiest.dev/rootiest/fish-config.git) is
hard-coded, so this works on a fresh clone with no origin configured. All
git output is suppressed. Run exec fish after a successful update to reload.
---
# 10. PERSONALIZATION
Sensitive credentials and machine-specific settings are kept out of version
control in a private directory at ~/.config/.user-dots/fish/. Two files are
sourced automatically by config.fish if they exist:
~/.config/.user-dots/fish/
├── secrets.fish API keys, tokens, passwords, personal identifiers
└── local.fish Machine-specific paths and environment variables
fish_variables (auto-managed by fish) is excluded from this repo via
.gitignore. Do not commit it.
## secrets.fish
Store anything you would not commit to a public repo: API keys, auth tokens,
passwords, and personal identifiers.
set -gx MY_NAME "Your Name"
set -gx MY_EMAIL "you@example.com"
set -gx GPG_RECIPIENT "you@example.com"
set -gx GITHUB_TOKEN ghp_yourTokenHere
set -gx OPENAI_API_KEY sk-proj-yourKeyHere
set -gx GITEA_TOKEN yourGiteaTokenHere
set -gx GITEA_CHOSEN_LOGIN your.gitea.instance
set -gx KOPIA_PASSWORD yourKopiaPassword
## local.fish
Store paths and variables specific to one machine — things that would be
wrong on any other system.
# CDPATH — directories searched by cd
set -gx CDPATH . /home/youruser/projects /home/youruser
# Path to your shared .gitignore boilerplate
set -gx GITIGNORE_BOILERPLATE ~/.config/git/gitignore_boilerplate
# SSH shortcuts
abbr -a sshr 'ssh you@your-server.local'
abbr -a sshw 'ssh you@work-server.example.com'
# Docker context shortcuts
abbr -a dcr 'docker context use my-remote-server'
abbr -a dcw 'docker context use work-server'
Both files are sourced at the end of config.fish with an existence check so
the public config works cleanly on any machine without the private repo.
---
# 11. VIEWING THIS MANUAL
## With ov (recommended)
@@ -1496,89 +1582,3 @@ push to main that changes docs/fish-config.md.
help config fish-deps
The keyword is matched case-insensitively against section headings.
---
# 10. INSTALLATION
This configuration is managed as a git repository. To deploy on a new machine:
mv ~/.config/fish ~/.config/fish.bak # back up any existing config
git clone https://git.rootiest.dev/rootiest/fish-config.git ~/.config/fish
Then open a new Fish shell. Fisher and all plugins install automatically on
first launch and the Catppuccin Mocha theme is applied.
## Return Sentinel
config.fish ends with a return sentinel guard. Any lines appended after it by
a tool's setup command (starship init fish | source, zoxide init fish | source,
etc.) will have no effect. All integrations are managed via conf.d/ files.
If a new tool's shell integration appears to do nothing, check whether its
setup command appended an init line below the sentinel and create a dedicated
conf.d/<tool>.fish instead.
## Updating
Pull the latest changes from the upstream repository without needing a
configured git remote:
config-update Fetch and apply the latest commits from upstream
config-update --dry-run Preview available changes without applying them
config-update --force Stash local changes, pull, then restore the stash
The remote URL (https://git.rootiest.dev/rootiest/fish-config.git) is
hard-coded, so this works on a fresh clone with no origin configured. All
git output is suppressed. Run exec fish after a successful update to reload.
---
# 11. PERSONALIZATION
Sensitive credentials and machine-specific settings are kept out of version
control in a private directory at ~/.config/.user-dots/fish/. Two files are
sourced automatically by config.fish if they exist:
~/.config/.user-dots/fish/
├── secrets.fish API keys, tokens, passwords, personal identifiers
└── local.fish Machine-specific paths and environment variables
fish_variables (auto-managed by fish) is excluded from this repo via
.gitignore. Do not commit it.
## secrets.fish
Store anything you would not commit to a public repo: API keys, auth tokens,
passwords, and personal identifiers.
set -gx MY_NAME "Your Name"
set -gx MY_EMAIL "you@example.com"
set -gx GPG_RECIPIENT "you@example.com"
set -gx GITHUB_TOKEN ghp_yourTokenHere
set -gx OPENAI_API_KEY sk-proj-yourKeyHere
set -gx GITEA_TOKEN yourGiteaTokenHere
set -gx GITEA_CHOSEN_LOGIN your.gitea.instance
set -gx KOPIA_PASSWORD yourKopiaPassword
## local.fish
Store paths and variables specific to one machine — things that would be
wrong on any other system.
# CDPATH — directories searched by cd
set -gx CDPATH . /home/youruser/projects /home/youruser
# Path to your shared .gitignore boilerplate
set -gx GITIGNORE_BOILERPLATE ~/.config/git/gitignore_boilerplate
# SSH shortcuts
abbr -a sshr 'ssh you@your-server.local'
abbr -a sshw 'ssh you@work-server.example.com'
# Docker context shortcuts
abbr -a dcr 'docker context use my-remote-server'
abbr -a dcw 'docker context use work-server'
Both files are sourced at the end of config.fish with an existence check so
the public config works cleanly on any machine without the private repo.
docs/wiki/1-configuration-variables.md
+1 -1
View File
@@ -1,6 +1,6 @@
# 1. CONFIGURATION VARIABLES
**Sections:** [Index](index.md) | **1. Configuration Variables** | [2. Path Setup](2-path-setup.md) | [3. Key Bindings](3-key-bindings.md) | [4. Abbreviations](4-abbreviations.md) | [5. Functions Reference](5-functions-reference.md) | [6. Dependency Catalog](6-dependency-catalog.md) | [7. Customization](7-customization.md) | [8. Fisher Plugins](8-fisher-plugins.md) | [9. Viewing This Manual](9-viewing-this-manual.md) | [10. Installation](10-installation.md) | [11. Personalization](11-personalization.md)
**Sections:** [Index](index.md) | **1. Configuration Variables** | [2. Path Setup](2-path-setup.md) | [3. Key Bindings](3-key-bindings.md) | [4. Abbreviations](4-abbreviations.md) | [5. Functions Reference](5-functions-reference.md) | [6. Dependency Catalog](6-dependency-catalog.md) | [7. Customization](7-customization.md) | [8. Fisher Plugins](8-fisher-plugins.md) | [9. Installation](9-installation.md) | [10. Personalization](10-personalization.md) | [11. Viewing This Manual](11-viewing-this-manual.md)
---
docs/wiki/10-personalization.md
+54
View File
@@ -0,0 +1,54 @@
# 10. PERSONALIZATION
**Sections:** [Index](index.md) | [1. Configuration Variables](1-configuration-variables.md) | [2. Path Setup](2-path-setup.md) | [3. Key Bindings](3-key-bindings.md) | [4. Abbreviations](4-abbreviations.md) | [5. Functions Reference](5-functions-reference.md) | [6. Dependency Catalog](6-dependency-catalog.md) | [7. Customization](7-customization.md) | [8. Fisher Plugins](8-fisher-plugins.md) | [9. Installation](9-installation.md) | **10. Personalization** | [11. Viewing This Manual](11-viewing-this-manual.md)
---
Sensitive credentials and machine-specific settings are kept out of version
control in a private directory at ~/.config/.user-dots/fish/. Two files are
sourced automatically by config.fish if they exist:
~/.config/.user-dots/fish/
├── secrets.fish API keys, tokens, passwords, personal identifiers
└── local.fish Machine-specific paths and environment variables
fish_variables (auto-managed by fish) is excluded from this repo via
.gitignore. Do not commit it.
## secrets.fish
Store anything you would not commit to a public repo: API keys, auth tokens,
passwords, and personal identifiers.
set -gx MY_NAME "Your Name"
set -gx MY_EMAIL "you@example.com"
set -gx GPG_RECIPIENT "you@example.com"
set -gx GITHUB_TOKEN ghp_yourTokenHere
set -gx OPENAI_API_KEY sk-proj-yourKeyHere
set -gx GITEA_TOKEN yourGiteaTokenHere
set -gx GITEA_CHOSEN_LOGIN your.gitea.instance
set -gx KOPIA_PASSWORD yourKopiaPassword
## local.fish
Store paths and variables specific to one machine — things that would be
wrong on any other system.
# CDPATH — directories searched by cd
set -gx CDPATH . /home/youruser/projects /home/youruser
# Path to your shared .gitignore boilerplate
set -gx GITIGNORE_BOILERPLATE ~/.config/git/gitignore_boilerplate
# SSH shortcuts
abbr -a sshr 'ssh you@your-server.local'
abbr -a sshw 'ssh you@work-server.example.com'
# Docker context shortcuts
abbr -a dcr 'docker context use my-remote-server'
abbr -a dcw 'docker context use work-server'
Both files are sourced at the end of config.fish with an existence check so
the public config works cleanly on any machine without the private repo.
---
docs/wiki/11-viewing-this-manual.md
+68
View File
@@ -0,0 +1,68 @@
# 11. VIEWING THIS MANUAL
**Sections:** [Index](index.md) | [1. Configuration Variables](1-configuration-variables.md) | [2. Path Setup](2-path-setup.md) | [3. Key Bindings](3-key-bindings.md) | [4. Abbreviations](4-abbreviations.md) | [5. Functions Reference](5-functions-reference.md) | [6. Dependency Catalog](6-dependency-catalog.md) | [7. Customization](7-customization.md) | [8. Fisher Plugins](8-fisher-plugins.md) | [9. Installation](9-installation.md) | [10. Personalization](10-personalization.md) | **11. Viewing This Manual**
---
## With ov (recommended)
help config
ov renders the Markdown with syntax highlighting and section-based
navigation.
Space next section
^ previous section
Alt+u toggle section list sidebar
/ search forward
n / N next / previous search match
g go to line number
j interactive jump target (line, %, or 'section')
q quit
## With bat
bat --language=markdown --paging=always ~/.config/fish/docs/fish-config.md
## As a man page
config-help --man
Opens the compiled docs/fish-config.1 directly via man -l, bypassing
the pager fallback chain. The symlink and MANPATH are also configured
automatically on shell start for the standard invocation:
man fish-config
NOTE: fish-config (hyphen) is this config's man page. fish_config
(underscore) is fish's built-in browser-based configuration tool —
a completely separate command. Do not mix them up.
## In the browser (HTML)
config-help --html
Opens docs/html/index.html in the default web browser. Browser detection
queries the system's x-scheme-handler/https MIME entry (via xdg-mime) to
find the real browser binary, then falls back through known browser
binaries (firefox, chromium, vivaldi, etc.), and finally xdg-open as a
last resort. Set $fish_help_browser or $BROWSER to override.
## As a wiki
The generated Markdown wiki lives in docs/wiki/. index.md provides the
project overview and a full table of contents. Each section page has a
navigation bar at the top linking to every other section.
The wiki is auto-generated from this file by the CI pipeline on every
push to main that changes docs/fish-config.md.
## Jumping to a section
help config keybindings
help config abbreviations
help config pkg
help config logs
help config fish-deps
The keyword is matched case-insensitively against section headings.
docs/wiki/2-path-setup.md
+1 -1
View File
@@ -1,6 +1,6 @@
# 2. PATH SETUP
**Sections:** [Index](index.md) | [1. Configuration Variables](1-configuration-variables.md) | **2. Path Setup** | [3. Key Bindings](3-key-bindings.md) | [4. Abbreviations](4-abbreviations.md) | [5. Functions Reference](5-functions-reference.md) | [6. Dependency Catalog](6-dependency-catalog.md) | [7. Customization](7-customization.md) | [8. Fisher Plugins](8-fisher-plugins.md) | [9. Viewing This Manual](9-viewing-this-manual.md) | [10. Installation](10-installation.md) | [11. Personalization](11-personalization.md)
**Sections:** [Index](index.md) | [1. Configuration Variables](1-configuration-variables.md) | **2. Path Setup** | [3. Key Bindings](3-key-bindings.md) | [4. Abbreviations](4-abbreviations.md) | [5. Functions Reference](5-functions-reference.md) | [6. Dependency Catalog](6-dependency-catalog.md) | [7. Customization](7-customization.md) | [8. Fisher Plugins](8-fisher-plugins.md) | [9. Installation](9-installation.md) | [10. Personalization](10-personalization.md) | [11. Viewing This Manual](11-viewing-this-manual.md)
---
docs/wiki/3-key-bindings.md
+1 -1
View File
@@ -1,6 +1,6 @@
# 3. KEY BINDINGS
**Sections:** [Index](index.md) | [1. Configuration Variables](1-configuration-variables.md) | [2. Path Setup](2-path-setup.md) | **3. Key Bindings** | [4. Abbreviations](4-abbreviations.md) | [5. Functions Reference](5-functions-reference.md) | [6. Dependency Catalog](6-dependency-catalog.md) | [7. Customization](7-customization.md) | [8. Fisher Plugins](8-fisher-plugins.md) | [9. Viewing This Manual](9-viewing-this-manual.md) | [10. Installation](10-installation.md) | [11. Personalization](11-personalization.md)
**Sections:** [Index](index.md) | [1. Configuration Variables](1-configuration-variables.md) | [2. Path Setup](2-path-setup.md) | **3. Key Bindings** | [4. Abbreviations](4-abbreviations.md) | [5. Functions Reference](5-functions-reference.md) | [6. Dependency Catalog](6-dependency-catalog.md) | [7. Customization](7-customization.md) | [8. Fisher Plugins](8-fisher-plugins.md) | [9. Installation](9-installation.md) | [10. Personalization](10-personalization.md) | [11. Viewing This Manual](11-viewing-this-manual.md)
---
docs/wiki/4-abbreviations.md
+1 -1
View File
@@ -1,6 +1,6 @@
# 4. ABBREVIATIONS
**Sections:** [Index](index.md) | [1. Configuration Variables](1-configuration-variables.md) | [2. Path Setup](2-path-setup.md) | [3. Key Bindings](3-key-bindings.md) | **4. Abbreviations** | [5. Functions Reference](5-functions-reference.md) | [6. Dependency Catalog](6-dependency-catalog.md) | [7. Customization](7-customization.md) | [8. Fisher Plugins](8-fisher-plugins.md) | [9. Viewing This Manual](9-viewing-this-manual.md) | [10. Installation](10-installation.md) | [11. Personalization](11-personalization.md)
**Sections:** [Index](index.md) | [1. Configuration Variables](1-configuration-variables.md) | [2. Path Setup](2-path-setup.md) | [3. Key Bindings](3-key-bindings.md) | **4. Abbreviations** | [5. Functions Reference](5-functions-reference.md) | [6. Dependency Catalog](6-dependency-catalog.md) | [7. Customization](7-customization.md) | [8. Fisher Plugins](8-fisher-plugins.md) | [9. Installation](9-installation.md) | [10. Personalization](10-personalization.md) | [11. Viewing This Manual](11-viewing-this-manual.md)
---
docs/wiki/5-functions-reference.md
+1 -1
View File
@@ -1,6 +1,6 @@
# 5. FUNCTIONS REFERENCE
**Sections:** [Index](index.md) | [1. Configuration Variables](1-configuration-variables.md) | [2. Path Setup](2-path-setup.md) | [3. Key Bindings](3-key-bindings.md) | [4. Abbreviations](4-abbreviations.md) | **5. Functions Reference** | [6. Dependency Catalog](6-dependency-catalog.md) | [7. Customization](7-customization.md) | [8. Fisher Plugins](8-fisher-plugins.md) | [9. Viewing This Manual](9-viewing-this-manual.md) | [10. Installation](10-installation.md) | [11. Personalization](11-personalization.md)
**Sections:** [Index](index.md) | [1. Configuration Variables](1-configuration-variables.md) | [2. Path Setup](2-path-setup.md) | [3. Key Bindings](3-key-bindings.md) | [4. Abbreviations](4-abbreviations.md) | **5. Functions Reference** | [6. Dependency Catalog](6-dependency-catalog.md) | [7. Customization](7-customization.md) | [8. Fisher Plugins](8-fisher-plugins.md) | [9. Installation](9-installation.md) | [10. Personalization](10-personalization.md) | [11. Viewing This Manual](11-viewing-this-manual.md)
---
docs/wiki/6-dependency-catalog.md
+1 -1
View File
@@ -1,6 +1,6 @@
# 6. DEPENDENCY CATALOG
**Sections:** [Index](index.md) | [1. Configuration Variables](1-configuration-variables.md) | [2. Path Setup](2-path-setup.md) | [3. Key Bindings](3-key-bindings.md) | [4. Abbreviations](4-abbreviations.md) | [5. Functions Reference](5-functions-reference.md) | **6. Dependency Catalog** | [7. Customization](7-customization.md) | [8. Fisher Plugins](8-fisher-plugins.md) | [9. Viewing This Manual](9-viewing-this-manual.md) | [10. Installation](10-installation.md) | [11. Personalization](11-personalization.md)
**Sections:** [Index](index.md) | [1. Configuration Variables](1-configuration-variables.md) | [2. Path Setup](2-path-setup.md) | [3. Key Bindings](3-key-bindings.md) | [4. Abbreviations](4-abbreviations.md) | [5. Functions Reference](5-functions-reference.md) | **6. Dependency Catalog** | [7. Customization](7-customization.md) | [8. Fisher Plugins](8-fisher-plugins.md) | [9. Installation](9-installation.md) | [10. Personalization](10-personalization.md) | [11. Viewing This Manual](11-viewing-this-manual.md)
---
docs/wiki/7-customization.md
+1 -1
View File
@@ -1,6 +1,6 @@
# 7. CUSTOMIZATION
**Sections:** [Index](index.md) | [1. Configuration Variables](1-configuration-variables.md) | [2. Path Setup](2-path-setup.md) | [3. Key Bindings](3-key-bindings.md) | [4. Abbreviations](4-abbreviations.md) | [5. Functions Reference](5-functions-reference.md) | [6. Dependency Catalog](6-dependency-catalog.md) | **7. Customization** | [8. Fisher Plugins](8-fisher-plugins.md) | [9. Viewing This Manual](9-viewing-this-manual.md) | [10. Installation](10-installation.md) | [11. Personalization](11-personalization.md)
**Sections:** [Index](index.md) | [1. Configuration Variables](1-configuration-variables.md) | [2. Path Setup](2-path-setup.md) | [3. Key Bindings](3-key-bindings.md) | [4. Abbreviations](4-abbreviations.md) | [5. Functions Reference](5-functions-reference.md) | [6. Dependency Catalog](6-dependency-catalog.md) | **7. Customization** | [8. Fisher Plugins](8-fisher-plugins.md) | [9. Installation](9-installation.md) | [10. Personalization](10-personalization.md) | [11. Viewing This Manual](11-viewing-this-manual.md)
---
docs/wiki/8-fisher-plugins.md
+1 -1
View File
@@ -1,6 +1,6 @@
# 8. FISHER PLUGINS
**Sections:** [Index](index.md) | [1. Configuration Variables](1-configuration-variables.md) | [2. Path Setup](2-path-setup.md) | [3. Key Bindings](3-key-bindings.md) | [4. Abbreviations](4-abbreviations.md) | [5. Functions Reference](5-functions-reference.md) | [6. Dependency Catalog](6-dependency-catalog.md) | [7. Customization](7-customization.md) | **8. Fisher Plugins** | [9. Viewing This Manual](9-viewing-this-manual.md) | [10. Installation](10-installation.md) | [11. Personalization](11-personalization.md)
**Sections:** [Index](index.md) | [1. Configuration Variables](1-configuration-variables.md) | [2. Path Setup](2-path-setup.md) | [3. Key Bindings](3-key-bindings.md) | [4. Abbreviations](4-abbreviations.md) | [5. Functions Reference](5-functions-reference.md) | [6. Dependency Catalog](6-dependency-catalog.md) | [7. Customization](7-customization.md) | **8. Fisher Plugins** | [9. Installation](9-installation.md) | [10. Personalization](10-personalization.md) | [11. Viewing This Manual](11-viewing-this-manual.md)
---
docs/wiki/9-installation.md
+38
View File
@@ -0,0 +1,38 @@
# 9. INSTALLATION
**Sections:** [Index](index.md) | [1. Configuration Variables](1-configuration-variables.md) | [2. Path Setup](2-path-setup.md) | [3. Key Bindings](3-key-bindings.md) | [4. Abbreviations](4-abbreviations.md) | [5. Functions Reference](5-functions-reference.md) | [6. Dependency Catalog](6-dependency-catalog.md) | [7. Customization](7-customization.md) | [8. Fisher Plugins](8-fisher-plugins.md) | **9. Installation** | [10. Personalization](10-personalization.md) | [11. Viewing This Manual](11-viewing-this-manual.md)
---
This configuration is managed as a git repository. To deploy on a new machine:
mv ~/.config/fish ~/.config/fish.bak # back up any existing config
git clone https://git.rootiest.dev/rootiest/fish-config.git ~/.config/fish
Then open a new Fish shell. Fisher and all plugins install automatically on
first launch and the Catppuccin Mocha theme is applied.
## Return Sentinel
config.fish ends with a return sentinel guard. Any lines appended after it by
a tool's setup command (starship init fish | source, zoxide init fish | source,
etc.) will have no effect. All integrations are managed via conf.d/ files.
If a new tool's shell integration appears to do nothing, check whether its
setup command appended an init line below the sentinel and create a dedicated
conf.d/<tool>.fish instead.
## Updating
Pull the latest changes from the upstream repository without needing a
configured git remote:
config-update Fetch and apply the latest commits from upstream
config-update --dry-run Preview available changes without applying them
config-update --force Stash local changes, pull, then restore the stash
The remote URL (https://git.rootiest.dev/rootiest/fish-config.git) is
hard-coded, so this works on a fresh clone with no origin configured. All
git output is suppressed. Run exec fish after a successful update to reload.
---
docs/wiki/index.md
+3 -3
View File
@@ -51,6 +51,6 @@ The configuration is split across:
- [6. Dependency Catalog](6-dependency-catalog.md)
- [7. Customization](7-customization.md)
- [8. Fisher Plugins](8-fisher-plugins.md)
- [9. Viewing This Manual](9-viewing-this-manual.md)
- [10. Installation](10-installation.md)
- [11. Personalization](11-personalization.md)
- [9. Installation](9-installation.md)
- [10. Personalization](10-personalization.md)
- [11. Viewing This Manual](11-viewing-this-manual.md)