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

docs: add Installation and Personalization sections; fix wiki index

Browse Source 
- docs/fish-config.md: add §10 Installation (clone, sentinel guard,
  config-update usage) and §11 Personalization (secrets.fish /
  local.fish examples); update TABLE OF CONTENTS
- docs/split-wiki.py: strip trailing thematic break from DESCRIPTION
  body so index.md no longer renders a double --- separator
- Regenerate docs/wiki/ with 11-installation.md and
  12-personalization.md; all nav bars updated
This commit is contained in:
Rootiest
2026-06-08 16:46:48 -04:00
parent 8e32196a79
commit 345d0086a5
14 changed files with 194 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/fish-config.md
+88
View File
@@ -104,6 +104,8 @@ The configuration is split across:
7. Customization
8. Fisher Plugins
9. Viewing This Manual
10. Installation
11. Personalization
---
@@ -1494,3 +1496,89 @@ 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/split-wiki.py
+3 -1
View File
@@ -92,7 +92,9 @@ def main() -> None:
numbered_sections.append(s)
# ── Write index.md ──────────────────────────────────────────────────────
intro_body = "\n\n".join(intro_parts)
intro_body = "\n\n".join(intro_parts).rstrip()
# Strip any trailing thematic break that the source adds before the ToC.
intro_body = re.sub(r"\n+---\s*$", "", intro_body)
toc = build_full_toc(numbered_sections)
index_content = f"# Fish Shell Configuration\n\n{intro_body}\n\n---\n\n{toc}\n"
(out_dir / "index.md").write_text(index_content)
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)
**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)
---
docs/wiki/10-installation.md
+38
View File
@@ -0,0 +1,38 @@
# 10. 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. Viewing This Manual](9-viewing-this-manual.md) | **10. Installation** | [11. Personalization](11-personalization.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/11-personalization.md
+52
View File
@@ -0,0 +1,52 @@
# 11. 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. Viewing This Manual](9-viewing-this-manual.md) | [10. Installation](10-installation.md) | **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/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)
**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)
---
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)
**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)
---
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)
**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)
---
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)
**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)
---
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)
**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)
---
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)
**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)
---
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)
**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)
---
docs/wiki/9-viewing-this-manual.md
+3 -1
View File
@@ -1,6 +1,6 @@
# 9. 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. 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. Viewing This Manual** | [10. Installation](10-installation.md) | [11. Personalization](11-personalization.md)
---
@@ -66,3 +66,5 @@ push to main that changes docs/fish-config.md.
help config fish-deps
The keyword is matched case-insensitively against section headings.
---
docs/wiki/index.md
+2 -2
View File
@@ -41,8 +41,6 @@ The configuration is split across:
---
---
## Table of Contents
- [1. Configuration Variables](1-configuration-variables.md)
@@ -54,3 +52,5 @@ The configuration is split across:
- [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)