Skip to content

Latest commit

 

History

History
453 lines (337 loc) · 43.2 KB

shells.md

File metadata and controls

453 lines (337 loc) · 43.2 KB

Unified Shells Guide: Zsh, Bash, Fish, Nushell & PowerShell (pwsh)

This guide documents the shell architecture across Linux, macOS, and Windows in the NREDF dotfiles ecosystem, detailing feature parity, keybindings, aliases, functions, and configuration mechanics for Zsh, Bash, Fish, Nushell (nu), and PowerShell (pwsh).

None of the five is the default login shell — install and try any of them without disturbing your existing setup: fish or nu at a prompt starts an interactive session, and reload -s fish (or -s nu) hot-swaps the current one. Fish has no Windows build at all (Linux/macOS only); the other four run everywhere.


Shell Feature Parity Matrix

All five shells share a unified experience designed around modern developer ergonomics, with a small number of documented exceptions — see "Known Parity Exceptions" below.

Capability Zsh Bash Fish Nushell PowerShell (pwsh)
Prompt Engine Oh-My-Posh (OneDark-Pro) Oh-My-Posh (OneDark-Pro) Oh-My-Posh (OneDark-Pro) Oh-My-Posh (OneDark-Pro) Oh-My-Posh (OneDark-Pro)
History Sync & Search Atuin (Ctrl+r) Atuin (Ctrl+r) Atuin (Ctrl+r) Atuin (Ctrl+r) Atuin (Ctrl+r, UpArrow)
Fuzzy Finding fzf (Ctrl+t, Alt+c) fzf (Ctrl+t, Alt+c) fzf (Ctrl+t, Alt+c) fzf (Ctrl+t, Alt+c, Ctrl+r) fzf (Ctrl+t, Alt+c)
Directory Navigation zoxide hooked to cd, z, zi zoxide hooked to cd, z, zi zoxide hooked to cd, z, zi zoxide z, zi only — not hooked to cd (zoxide has no nushell cd integration upstream) zoxide hooked to cd, z, zi
Syntax Highlighting fast-syntax-highlighting ble.sh (Bash Line Editor) Built in Built in PSReadLine
Inline Autosuggestions zsh-autosuggestions ble.sh inline suggestions Built in Built in PSReadLine (HistoryAndPlugin)
Tab Completion Engine Carapace (carapace-bin + fzf-tab) Carapace (bash-ble with descriptions) Carapace + fzf-powered Ctrl+Space widget Carapace native completion menu only — no fzf-powered widget (see exceptions) Carapace (native menu + fzf modal)
Auto-Pairing Quotes zsh-autopair ble.sh auto-complete N/A (fish doesn't need it) N/A (nu doesn't need it) Custom PSReadLine chord (", ')
Plugin Manager Sheldon Git-cloned ble.sh None required None required None required (100% native CLI tooling)
Environment Sync reload (supports -c, -d, -f, -p, -s) reload (supports -c, -d, -f, -p, -s) reload (supports -c, -d, -f, -p, -s) reload (supports -c, -d, -f, -p, -s) reload (supports -c, -d, -f, -p, -s)
Startup Profiling reload -p / NREDF_PROFILE_STARTUP=1 reload -p / NREDF_PROFILE_STARTUP=1 reload -p / NREDF_PROFILE_STARTUP=1 reload -p / NREDF_PROFILE_STARTUP=1 reload -p / NREDF_PROFILE_STARTUP=1
SSH TOTP wrapper (nredf_ssh) nredf_ssh (shares bash's implementation via common/) — full ssh-getopt destination parsing (grouped flags, -p/-F attached or separate, --), -F honored, first-hop ProxyJump lookup nredf_ssh — see Zsh nredf_ssh — first-argument destination only (no getopt clustering or -F support yet) nredf-ssh — same simpler destination detection as Fish nredf_ssh — full ssh-getopt parsing + -F + ProxyJump (matches Bash/Zsh); falls back to plain ssh with a stderr note when sshpass isn't installed (the common case on Windows — no first-party build)
Aqua GitHub-token wizard (nredf_aqua_token_setup) --set/--keyring/--env/--skip/--reset/--status + startup prompt, timed via read -t Same as Zsh (shares common/) Same flags; prompt timeout shells out to timeout/gtimeout if installed (see exceptions) Same flags; same timeout/gtimeout fallback as Fish Same flags; prompt timeout via [Console]::KeyAvailable polling — no external timeout binary needed
Remote multiplexer auto-attach (zellij) Attaches over SSH/WSL per shell.yaml, skips inside zellij/VS Code/non-interactive (shares common/) Same as Zsh Same behavior, own port Same behavior, own port Same behavior; reads WSL_DISTRO_NAME/WSL_INTEROP live instead of a chezmoi-baked NREDF_WSL (no chezmoi template in that part of pwsh's load chain — see Aliases.ps1.tmpl)
Local overrides ~/.config/zsh/{aliases,rc,functions/} ~/.config/bash/{aliases,rc,functions/} ~/.config/fish/{aliases,rc} + fish's own native functions/ autoload ~/.config/nushell/: two files only, env.local.nu, config.local.nu (see exceptions) ~/.config/pwsh/{aliases.ps1,modules.ps1,functions/}

Shell Implementations & Initialization

1. Zsh Architecture

  • Dotfiles: .zshenv.tmpl, .zprofile.tmpl, .zshrc.tmpl
  • Plugin Management: Managed by Sheldon via ~/.config/sheldon/plugins.toml
    • Loads Oh-My-Zsh core libraries (completion.zsh, functions.zsh, history.zsh, misc.zsh, spectrum.zsh, termsupport.zsh, theme-and-appearance.zsh)
    • Curated plugins: npm, rvm, extract, colored-man-pages, colorize, cp, git-extras, systemadmin, fzf-tab, fzf-zsh-completions, zsh-completions, zsh-autopair, calc, zsh-autosuggestions, fast-syntax-highlighting
    • Lazy Loading: Plugins are lazy-loaded on the first prompt display via add-zsh-hook precmd to guarantee sub-millisecond shell startup.
  • Completion Engine: Managed by Carapace (carapace-bin) cached for 24 hours via _nredf_refresh_cached_shell_snippet, with custom declarative specs in ~/.config/carapace/specs/.

2. Bash Architecture

  • Dotfiles: .bash_profile.tmpl, .bashrc.tmpl, .blerc.tmpl
  • Engine: Modern Bash 4.4+ / 5.x with ble.sh (Bash Line Editor)
    • On macOS, automatically detects and invokes Homebrew Bash (/opt/homebrew/bin/bash or /usr/local/bin/bash), bypassing Apple's legacy Bash 3.2.
    • ble.sh sources at the top of .bashrc (--attach=none) and attaches at the very end (ble-attach), providing syntax highlighting, fish-like autosuggestions, vim-mode support, and menu completion in standard Bash.
  • Completion Engine: Managed by Carapace (carapace-bin) running after system bash_completion and cached for 24 hours via _nredf_refresh_cached_shell_snippet, with custom declarative specs in ~/.config/carapace/specs/.

3. Fish Architecture

  • Dotfiles: home/dot_config/fish/config.fish.tmpl
  • Framework: home/dot_local/share/nredf/shell/fish/ — rc.tmpl is a single, self-contained entry point (fish has no sibling shell to share a "common" rc with the way bash/zsh do), ported 1:1 from the bash function files since fish is dynamically scoped the same way bash is.
  • Completion Engine: Managed by Carapace (carapace-bin) cached for 24 hours via _nredf_refresh_cached_shell_snippet, with the same declarative specs in ~/.config/carapace/specs/.
  • Local overrides: ~/.config/fish/aliases, ~/.config/fish/rc, plus fish's own native ~/.config/fish/functions/*.fish autoload (nothing this framework implements).

4. Nushell Architecture

  • Dotfiles: thin stubs that just source one canonical tree, deployed to every path nu might actually read — ~/.config/nushell/{env,config}.nu (deployed on every OS, not just Linux) plus the OS-native fallback: ~/Library/Application Support/nushell/{env,config}.nu (macOS) or ~/AppData/Roaming/nushell/{env,config}.nu (Windows; Linux has no separate native path, XDG is its native path). Nu resolves its config directory from the real process environment before it reads any of its own files, and — confirmed live — prioritizes $XDG_CONFIG_HOME/nushell over its OS-native default the instant XDG_CONFIG_HOME is set, on every OS, not only Linux. Since every other shell in this repo already exports XDG_CONFIG_HOME, launching nu from (or with an environment inherited from) any of them makes nu read ~/.config/nushell even on macOS/Windows; launching nu with no such prior shell in the chain falls back to the OS-native path instead. Both locations get the same stub content so either path works.
  • Framework: home/dot_local/share/nredf/shell/nushell/ — env.nu.tmpl (env vars only, safe for non-interactive nu -l) and config.nu.tmpl (interactive-only setup), mirroring nu's own env.nu/config.nu convention instead of bash's single common rc.
  • Completion Engine: Managed by Carapace (carapace-bin), which also stands in for the fzf-powered Ctrl+Space widget nu can't have (see "Known Parity Exceptions" below).
  • Local overrides: exactly two files, env.local.nu and config.local.nu, seeded empty by chezmoi and never overwritten again — see "Known Parity Exceptions" below for why nu can't get bash's fuller cascade.
  • Environment model: nu's def is not dynamically scoped — a function only mutates the caller's $env if declared def --env, and every function in a chain that needs to reach top-level $env must be --env, all the way up. Every state-mutating command in the nu port follows a "compute in a plain def, assign in a thin --env wrapper" shape for this reason.

5. PowerShell (pwsh) Architecture

  • Dotfiles:
    • Entry points: home/Documents/PowerShell/
      • Target for PowerShell 7+: Documents\PowerShell\Microsoft.PowerShell_profile.ps1
      • Target for Windows PowerShell 5.1: Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1 (dot-sources PowerShell 7 profile)
      • Linux/macOS: ~/.config/powershell is symlinked directly to ~/Documents/PowerShell
    • Framework: home/dot_local/share/nredf/shell/pwsh/
      • Deployed to ~/.local/share/nredf/shell/pwsh/ on all platforms, matching the location of all other shells.
  • Module Architecture:
    • Defaults.ps1: XDG paths, Aqua paths, Python paths, UTF-8 output encoding, default formatting.
    • Modules.ps1: Zero external PowerShell modules required; hooks local overrides if configured.
    • Aliases.ps1: Cross-platform command parity with Bash/Zsh.
    • PSReadLine.ps1: Keybindings, prediction source (HistoryAndPlugin), native fzf integration, smart auto-pairing quotes.
    • Functions/: one file per function (glob-bundled into Functions.bundle.ps1.tmpl, same mechanism as the other shells' functions/) — Functions.ps1 itself holds reload, sudo, md5, sha256; NREDF_DailySync.ps1, NREDF_Bw.ps1 and the rest are their own files.
    • Profile.ps1: High-performance startup orchestration with snippet caching (NREDF_RefreshCachedShellSnippet) for Oh-My-Posh, Atuin, Zoxide, and Carapace completions (including custom specs in ~/.config/carapace/specs/).

6. Custom Completions (Carapace)

  • Specs: home/dot_config/carapace/specs/ holds one YAML spec per command carapace-bin doesn't know: the NREDF functions (reload, yy, nredf_ssh, nredf_aqua_token_setup, nredf-daily-sync) and CLI tools without a builtin completer (mise, kubectx, kubens, lsd, lazydocker, lazyjournal, zellij).
  • Aliases: bash can't complete an alias through its target, so every alias in home/.chezmoidata/aliases.yaml whose target needs it (k, kctx/ctx, kns/ns, lzg/lg, lzd, lzj/lj, ll/la/tree, pst) has its own thin spec that bridges to the target with $carapace.bridge.CarapaceBin([target]). A spec's aliases: field does not help here: it only names subcommand aliases and never registers a top-level command.
  • Cobra bridges: home/dot_config/carapace/choices/ makes carapace ask flux, oras, stern, velero and yq for their own completions (the same files carapace --choice flux/cobra@bridge writes).
  • Cache lag: bash, zsh, fish and PowerShell only complete command names that were listed in carapace's init snippet, which is cached for 24 hours. A new spec or choice therefore appears only after reload -c (or the next daily refresh); edits to an existing spec apply immediately. Nushell's snippet is a generic external completer, so it picks up new specs at once.

⌨️ Shell Keyboard Shortcuts

1. Zsh Keyboard Shortcuts

Shortcut Function Description
Tab Completion Menu Interactive tab completion with descriptions via fzf-tab
Shift + Tab Backward Cycle Cycle backward through completion candidates in fzf-tab
Ctrl + Space fzf Tab Completion Open interactive fzf completion modal with descriptions
Ctrl + r Atuin Search Interactive fuzzy search across full command history
Ctrl + t Fzf File Search Fuzzy search files in CWD and insert selected path at cursor
Alt + c / Option+c Fzf CD Fuzzy search subdirectories and immediately cd into selection
→ (Right Arrow) Autosuggestion Accept Accept full ghost-text autosuggestion
Ctrl + e Autosuggestion / EOL Accept autosuggestion or jump to end of line
Ctrl + a Beginning of Line Move cursor to beginning of command line
Ctrl + u Backward Kill Line Clear line before cursor
Ctrl + k Forward Kill Line Clear line after cursor
Ctrl + w Backward Kill Word Delete word before cursor
Ctrl + l Clear Screen Clear terminal screen

Note

On macOS, Option+c produces ç or © by default. NREDF binds ç and © to fzf-cd-widget in Zsh so directory fuzzy jumping works without changing Terminal settings.


2. Bash Keyboard Shortcuts (with ble.sh)

Shortcut Function Description
Tab Menu Completion Open interactive ble.sh completion menu with Carapace descriptions
Shift + Tab Backward Cycle Cycle backward through completion candidates
Ctrl + Space fzf Tab Completion Open fzf fuzzy modal with completion candidates and descriptions
Ctrl + r Atuin Search Interactive fuzzy history search via __atuin_history
Ctrl + t Fzf File Search Fuzzy search files with live bat syntax preview
Alt + c / Option+c Fzf CD Fuzzy search directories with live lsd tree preview
→ (Right Arrow) ble.sh Complete Accept highlighted completion candidate or inline autosuggestion
Ctrl + x Ctrl + e Edit in $EDITOR Open current command in Neovim/Vim, save to execute
Ctrl + c Cancel / Interrupt Abort current input or running process
Ctrl + l Clear Screen Clear terminal screen and redraw prompt

3. Fish Keyboard Shortcuts

Shortcut Function Description
Tab Fish Pager Native completion menu with Carapace descriptions
Ctrl + Space fzf Tab Completion Open interactive fzf completion modal with descriptions (commandline-based, ported from bash's READLINE_LINE widget)
Ctrl + r Atuin Search Interactive fuzzy search across full command history
Ctrl + t Fzf File Search Fuzzy search files in CWD and insert selected path at cursor
Alt + c / Option+c Fzf CD Fuzzy search subdirectories and immediately cd into selection
Ctrl + l Clear Screen Clear terminal screen

Note

On macOS, Option+c produces ç or © by default, same as zsh/bash — NREDF binds both to the fzf widget in fish too.


4. Nushell Keyboard Shortcuts

Shortcut Function Description
Tab Reedline Menu Native completion menu fed by Carapace — nu's only completion-picking UI (see "Known Parity Exceptions" below)
Ctrl + r Fzf History Search fzf --nushell's Ctrl+R history widget
Ctrl + t Fzf File Search fzf --nushell's Ctrl+T file-insert widget
Alt + c Fzf CD fzf --nushell's Alt+C directory-jump widget
Ctrl + l Clear Screen Clear terminal screen

Note

There is no Ctrl+Space fuzzy tab-completion widget in nu — Reedline (nu's line editor) has no primitive to replace the edit buffer with an external filter's output, which is what that widget depends on in every other shell here. See "Known Parity Exceptions" below.


5. PowerShell Keyboard Shortcuts (PSReadLine & fzf)

Shortcut Function Description
Tab MenuComplete Interactive terminal completion menu with Carapace descriptions
Shift + Tab TabCompletePrevious Cycle backward through completion candidates
Ctrl + Space fzf Tab Completion Open fzf fuzzy modal with completion candidates and descriptions
Ctrl + r / ↑ Atuin History Search Full-screen interactive history search powered by Atuin
Ctrl + t fzf File Search Fuzzy search files with bat syntax preview
Alt + c / Option+c fzf CD Fuzzy search directories with lsd tree preview and jump
Ctrl + d ViExit Exit session if buffer is empty
Alt + d ShellKillWord Delete next word forward
Alt + Backspace ShellBackwardKillWord Delete previous word backward
Alt + q SaveInHistory Stash current line in history and clear buffer for a quick command
" or ' SmartInsertQuote Automatically insert paired quotes and place cursor inside
→ (Right Arrow) Prediction Accept Accept predictive IntelliSense suggestion from history/plugins

Unified Aliases & Functions

NREDF guarantees that common development commands behave identically regardless of your current shell or operating system, across all five shells:

Command Target Tool Description
ls lsd Modern file listing with icons and colors — shadows Nushell's own structured ls builtin, see below
ll lsd -lFh --git Long format listing with Git status flags and human-readable sizes
la lsd -lAFh --git Detailed listing including hidden files and Git status
tree lsd --tree Recursive tree view with icons
cat bat --paging=never Syntax-highlighted output with OneDark-Pro theme, gated on bat
vim / vi nvim Neovim editor, gated on nvim
du dust Modern disk usage analyzer, gated on dust — not aliased in Nushell, see below
df duf Modern disk free space viewer, gated on duf
lzg / lg lazygit Terminal UI for Git
lzd lazydocker Terminal UI for Docker and Docker Compose
lzj / lj lazyjournal Terminal UI for multi-source log viewing & filtering
k kubectl Kubernetes CLI shorthand
kctx / ctx kubectx Fast Kubernetes context switcher
kns / ns kubens Fast Kubernetes namespace switcher
.. cd .. Go up one directory
... cd ../.. Go up two directories
.... cd ../../.. Go up three directories
root sudo -E "HOME=$HOME" su -m Root shell that preserves your $HOME — gated on su, so not on Windows
aptall apt update/full-upgrade/autoremove/autoclean One-shot Debian/Ubuntu system update — gated on apt, so only where it exists
yy Custom Function Open Yazi file manager; changes terminal working directory on exit
cd <path> zoxide Smart jump (falls back to standard cd if path exists) — not in Nushell, see below
z <query> zoxide query Jump directly to highest ranked directory matching query
zi zoxide query -i Interactive fuzzy search directory selection

Note

Nushell's cd is never replaced by zoxide (zoxide has no nushell-target cd integration upstream) — z/zi still work identically to every other shell here. Nushell's own ls/du/help are structured builtins (they return tables consumed in pipelines); ls is shadowed by the lsd alias here anyway, same as every other shell, but du deliberately is not — see "Known Parity Exceptions" below. help isn't aliased to tldr in any shell here (not just Nushell): it's a real, actively-used builtin/function in bash, fish and PowerShell too, not only nu's structured-table case, so aliasing it would shadow all three — run tldr <command> directly instead. cat/vim/vi/df are not nu builtins, so they get the same requires-gated behavior as every other shell (hand-written def --wrapped fallbacks in Nushell's case, since a requires-gated group can't be plain data-driven there — see .chezmoidata/aliases.yaml).

PowerShell also has its own which/touch fallback functions (filling a real Windows gap: neither binary exists there) and md5/sha1/sha256 convenience wrappers around Get-FileHash (Functions/Functions.ps1). These aren't in the table above because they're functions, not aliases to another tool, and Unix shells already have real touch/hashing tools natively — see "Known Parity Exceptions" below.


Helper Functions

Real functions (not aliases to another binary), implemented once with identical names and behavior in bash/zsh, fish, Nushell and PowerShell. Each one checks its own tool dependency at call time and prints a clear message on stderr instead of failing silently if it's missing — none of them do any work at shell startup.

Function Requires Does
mkcd <dir> — mkdir -p a directory, then cd into it
extract <archive>... / x ouch Extract any archive format ouch recognizes (zip/tar/tar.gz/tar.zst/7z/rar/...)
compress <out> <files...> ouch Compress files into an archive, format inferred from <out>'s extension
fif <pattern> rg, fzf ripgrep for a pattern, fzf to pick a match (bat preview centered on the line), open $EDITOR there
fe [query] fd, fzf fd for files, fzf (bat preview) to pick one, open in $EDITOR
fbr git, fzf fzf-pick a local or remote branch, git switch to it
flog git, fzf Browse git log --oneline --graph, previewing the selected commit with delta (falls back to plain git show)
fkill [signal] fzf fzf-pick one or more processes (via procs, falling back to ps/Get-Process), kill them
path — Print $PATH, one entry per line
ports — List listening TCP ports (ss/lsof/netstat on Unix, Get-NetTCPConnection on Windows)
nredf_bench_startup (nredf-bench-startup in Nu, NREDF_BenchStartup in PowerShell) hyperfine Benchmark interactive startup time of every installed shell

Note

In zsh, oh-my-zsh's extract/x (sheldon, lazy-loaded on the first precmd) and its systemadmin plugin's path alias are defined after this file loads, so they win for interactive zsh sessions instead of the versions above — same output for path, but zsh's extract/x is OMZ's own implementation rather than the ouch-based one every other shell gets. Fixing this would mean editing sheldon's plugin list or its lazy-load hook, both existing files outside this change — see "Known Parity Exceptions" below. fif/fe/fbr/flog/fkill/mkcd/compress/ports/nredf_bench_startup are unaffected (OMZ defines none of them).


Local, Machine-Specific Overrides

None of the following files are chezmoi-managed or committed to this repo — they live only on your machine, are yours to create, and chezmoi apply never touches or overwrites them. ~/.config/nredf/README.md is a shorter, on-disk version of this same section.

~/.config/nredf/local.yaml — paths and simple aliases

The same declarative format .chezmoidata/paths.yaml and .chezmoidata/aliases.yaml use internally. If this file exists, every shell reads and merges it in at chezmoi apply time (it is re-read on every apply, so editing it and re-applying picks up changes immediately). chezmoi deploys a copy-and-edit starting point at ~/.config/nredf/local.yaml.example — copy it to local.yaml in the same directory:

# ~/.config/nredf/local.yaml
nredf_paths_local:
  - var: MY_TOOL_HOME # exported as $MY_TOOL_HOME if not already set
    base: HOME # $HOME, or any other var already set by then (e.g. XDG_CONFIG_HOME)
    parts: [".local", "my-tool"] # joined onto base with "/"

nredf_aliases_local:
  - names: ["myalias", "ma"] # one or more names for the same command
    command: "echo hello world" # a single target command; no pipes/flow control

Both lists are optional and additive — they never replace the built-in entries. Two things this format deliberately can't express, by design:

  • A requires/existence gate on a local alias. Bash/zsh/fish/PowerShell would happily support one, but Nushell's alias/def can't be conditionally defined inside an if block (see below), so gating isn't offered here at all, to keep one file behaving the same on every shell. Everything in nredf_aliases_local is defined unconditionally.
  • A pipeline, condition, or anything needing real control flow. command is a single command line, substituted as-is (bash/fish: alias; nu: alias; PowerShell: Set-Alias or a one-line wrapper function).

For either of those, use the per-shell cascade below instead. A malformed local.yaml fails chezmoi apply loudly with a YAML parse error pointing at the bad line, rather than silently dropping your entries.

Per-shell aliases, rc and local-functions directory

For anything local.yaml can't express — conditional aliases, real functions, arbitrary startup code — every shell loads its own files from its own ~/.config/<shell>/ directory, not from ~/.config/nredf/ at all. This is consistent across every shell including PowerShell (via XDG_CONFIG_HOME, set on Windows too — deliberately not $PROFILE's directory, which is Documents\PowerShell\ on Windows but ~/.config/powershell/ on Linux/macOS). There is deliberately no shared "all shells" or "bash+zsh" tier: a function's syntax is never portable across shells anyway, and local.yaml above already covers the one thing that genuinely was shareable (simple aliases/paths).

Shell Aliases Startup code Functions directory
Bash ~/.config/bash/aliases ~/.config/bash/rc ~/.config/bash/functions/*.bash
Zsh ~/.config/zsh/aliases ~/.config/zsh/rc ~/.config/zsh/functions/*
Fish ~/.config/fish/aliases ~/.config/fish/rc ~/.config/fish/functions/*.fish — fish's own native autoload, nothing this framework implements
Nushell not supported ~/.config/nushell/env.local.nu, ~/.config/nushell/config.local.nu not supported
PowerShell ~/.config/pwsh/aliases.ps1 ~/.config/pwsh/modules.ps1 (module imports) ~/.config/pwsh/functions/*.ps1

~/.config/<shell>/ is deliberately where each shell's local files live: it's already where you'd look for shell-specific config, and fish in particular already autoloads its functions/ directory as a native feature — putting a second, framework-specific mechanism anywhere else would only duplicate or collide with what the shell already does itself.

Every file in the table above except the functions directories is pre-seeded by chezmoi (create_: written once, empty except for a header comment and a commented-out example, never overwritten again) — there's nothing to create, just open and edit. Each functions/ directory instead has its own README.md with a matching example, since anything real dropped there gets sourced (or, for fish, autoloaded) on every shell startup.

~/.config/aquaproj-aqua/machine.yaml — local aqua packages

aqua already supports a second, machine-local config file layered on top of the repo's aqua.yaml: if ~/.config/aquaproj-aqua/machine.yaml exists, every shell's startup appends it to AQUA_GLOBAL_CONFIG automatically (see nredf_aqua.bash/.fish/.nu/Defaults.ps1). Same packages: format as home/dot_config/aquaproj-aqua/aqua.yaml — add your own tools there without touching this repo.

~/.config/mise/config.local.toml — local mise tools

mise natively loads config.local.toml alongside config.toml in the same directory (confirmed: mise config ls lists both). Add your own [tools] there; it's merged with home/dot_config/mise/config.toml.tmpl's pinned versions with no chezmoi involvement at all.


The Unified reload Command

Each of the five shells provides a high-performance reload function with identical arguments (in Nushell, its typed named flags are generated from the same option set, so reload --help documents itself):

Usage: reload [options]

Options:
  -c, --cache       Delete 'Last Run Cache' and init script snippets
  -d, --downloads   Delete aqua pkgs (archives + binaries, keeps bin/ symlinks)
  -f, --full        Full refresh: clear caches + chezmoi / aqua / sheldon
  -l, --last-run    Delete only 'Last Run Cache'
  -p, --profile     Toggle startup profiling (or one-shot if combined with other options)
  -s, --shell NAME  Reload directly into a different shell (e.g. zsh, bash, fish, nu, pwsh)
  -h, --help        Show usage help

-l removes only the last-run stamps and keeps the cached init snippets, the sheldon cache and the zsh completion dump. -c and -f clear those as well; use one of them to pick up a tool upgrade immediately. Nushell's *.nu snippets are truncated rather than deleted, because nu's source needs each file to exist when config.nu is parsed.

Examples

  • Fast shell refresh:

    reload
  • Measure shell startup latency:

    reload -p

    Prints step-by-step millisecond timings for Oh-My-Posh, Atuin, plugins, and custom functions.

  • Switch to Fish or Nushell from Bash/Zsh:

    reload -s fish
    reload -s nu
  • Force clean rebuild of all CLI packages & cached scripts:

    reload -f

Yazi CWD Wrapper (yy)

Running standard yazi leaves the shell in whatever directory you started in. NREDF includes the yy function in all five shells:

yy

When you navigate to a directory inside Yazi and quit with q, your shell automatically changes its working directory to the directory you were viewing in Yazi!


Automated Daily Maintenance & Hot-Reloading

NREDF decouples all periodic maintenance and network-heavy upgrade tasks from interactive shell startup. Interactive shells start in milliseconds without waiting on network checks, git pulls, or package managers.

1. Native Background Schedulers

Daily maintenance is scheduled natively per operating system via chezmoi:

  • macOS (launchd): com.nredf.daily-sync.plist (managed via home/private_Library/private_LaunchAgents/com.nredf.daily-sync.plist.tmpl).
  • Linux (systemd --user): nredf-daily-sync.timer & nredf-daily-sync.service in ~/.config/systemd/user/. The timer is Persistent=true, so a run missed while the machine was off happens at the next boot.
  • Windows (Task Scheduler): NREDF-DailySync registered with StartWhenAvailable to catch up after sleep.

2. What Daily Maintenance Executes

The unified payload (nredf-daily-sync on POSIX, NREDF_DailySync on PowerShell) runs once daily in the background with low CPU and I/O priority:

  1. Package Upgrades: Homebrew (brew update && brew upgrade && brew cleanup -s on macOS).
  2. Chezmoi Upgrade: Upgrades the chezmoi binary.
  3. Dotfiles Remote Sync: Fetches upstream dotfiles changes, fast-forwards Git, and runs chezmoi apply --refresh-externals --force. A scheduled run has no terminal to unlock a password safe, so it first checks the one your secrets reference: Bitwarden must report unlocked from bw status (after restoring BW_SESSION from the keychain, as shell startup does), 1Password must pass op whoami, and a KeePassXC reference always needs its database password. If that check fails, the apply is skipped with a log line and the other steps still run. Run bwu and then reload -f to catch up. PowerShell only pre-checks Bitwarden; for the other two it detects a locked safe from the failed apply's output.
  4. Aqua Tools: Updates Aqua (aqua update-aqua), ensures tool links (aqua install -a -l), and vacuums packages unused for >30 days (aqua vacuum -d 30).
  5. Mise Tools: Installs missing or newly-pinned mise tools (mise install --yes).
  6. Zsh Plugins: Updates Sheldon plugin locks (sheldon lock --update). Not on PowerShell.
  7. tldr Pages: Refreshes the tldr page cache (tldr --update).
  8. oh-my-posh Session Caches: Deletes *.omp.cache files older than 7 days from the oh-my-posh cache directory. Every shell gets a new POSH_SESSION_ID, so these files otherwise pile up forever.

All runs are logged to ${XDG_STATE_HOME:-~/.local/state}/nredf/daily-sync.log (macOS/Linux) and $LOCALAPPDATA\nredf\daily-sync.log (Windows). reload -f (or nredf-daily-sync --verbose) also prints that output to the terminal.

3. How Running Shells Pick Up Updates

If you have open terminals when the background sync completes:

  • New & Upgraded Binaries: CLI tools in /opt/homebrew/bin or ~/.local/share/aquaproj-aqua/bin are immediately accessible in your existing shell.
  • Dotfiles, Aliases & Functions: Because running shells maintain their own in-memory environment, run reload to hot-reload the current session in place.
  • Manual Full Sync: To trigger a complete maintenance cycle and reload on demand, run reload -f.

Known Parity Exceptions

"Five-shell parity" (AGENTS.md) means every command, alias and completion is either implemented identically everywhere, or its gap here is deliberate, understood, and won't silently regress. These are the current gaps:

Item Affected shell(s) Why Resolution
ls aliased to lsd Nushell Every other shell here aliases ls to lsd, and nu gets the same alias for muscle-memory parity — but nu's own ls is a structured builtin returning a table, and the lsd-backed wrapper returns plain text instead, same as the external-ls-based shells. Accepted trade-off; scripts/pipelines inside nu that need structured output use ^ls (or another structured command) explicitly instead of the shadowed ls.
du not aliased to dust Nushell Unlike ls, nu's own du is a structured builtin actively used in pipelines (returns a directory-size table) — aliasing over it would break that, not just change formatting. Not implemented; bash/zsh/fish/PowerShell get du→dust, nu users run dust directly.
help never aliased to tldr All five shells Not just nu's case: bash's help builtin, fish's doc-browser help function, and PowerShell's Get-Help-wrapping help function are all real, actively-used commands, not dead weight to shadow. Not implemented anywhere; run tldr <command> directly instead of help <command>.
which/touch fallback functions, md5/sha1/sha256 hash wrappers Only in PowerShell which/touch fill a genuine Windows gap (neither binary exists there); md5/sha1/sha256 are convenience wrappers around Get-FileHash for verifying legacy vendor checksums. Unix shells already have real touch (and usually which) natively, and these are functions, not aliases to another CLI tool. Not ported; out of scope for the alias table (see the "New helper functions" carve-out — these are functions, tracked separately from alias parity).
Ctrl+Space fzf-tab completion widget Nushell Reedline (nu's line editor) has no primitive to replace the edit buffer with an external filter's output — every other shell's widget depends on exactly that. Not implemented. Carapace's native Reedline completion menu (Tab) is nu's substitute.
zoxide --cmd cd (replacing cd itself) Nushell zoxide itself has no nushell cd integration — an upstream gap, not this repo's. z/zi aliases only; cd is never overridden in nu.
Same-session cached tool-init refresh (atuin/zoxide/mise/carapace/fzf) Nushell nu's source requires the target file to exist on disk before the file that sources it is even parsed — true even inside a runtime if path exists guard. A cache regenerated this session can only be sourced starting the next shell start. Chezmoi seeds an empty placeholder (create_/empty_) for each cache file so a cold source never fails outright; a stale-but-present cache is used for the rest of the current session and refreshes for the next one.
oh-my-posh's nu integration doesn't use the cached-snippet mechanism at all Nushell Unlike every other tool here, oh-my-posh init nu prints nothing (confirmed: empty stdout and stderr on success) — it writes directly into nu's own vendor-autoload directory (~/.local/share/nushell/vendor/autoload/, one of $nu.vendor-autoload-dirs), which nu sources automatically on its own next startup. config.nu just re-runs the generator on the same 24h throttle, with no cache file or source line of its own — the same one-restart lag applies, but because nu only rescans vendor-autoload at its own next startup, not because of the source restriction above.
Fuller local-override files (aliases, rc, a local-functions directory) Nushell Same source-needs-the-file-to-already-exist restriction rules out conditionally sourcing a maybe-missing file at all. Exactly two chezmoi-seeded files, env.local.nu and config.local.nu (seeded empty, never overwritten again) — one for env vars, one for interactive config, matching nu's own env.nu/config.nu split.
Directory-glob fallback when the function bundle is absent Nushell The fallback loop would itself need to source a runtime-determined file list — same restriction again. The generated bundle is nu's only load path, not a fast path with a fallback the way bash/zsh/fish have.
Caller-name auto-detection for the throttle gate and mkdir-based lock (_nredf_last_run, _nredf_create_lock) Fish, Nushell Neither has an equivalent of bash's FUNCNAME/zsh's funcstack. Both take an explicit key argument at every call site instead of inferring one.
Kitty terminal shell-integration Nushell Kitty ships integration scripts for bash/zsh/fish only — no nushell target exists upstream. Not implemented; not something this repo can fix.
dircolors/LS_COLORS integration Nushell nu's own ls builtin has its own color theming ($env.config.color_config) and never reads LS_COLORS, unlike the external-ls-based ls/ll/la aliases every other shell here uses. Not implemented; low value for nu specifically, not a gap in the external-ls sense the other shells have.
Prompt-with-timeout for the aqua GitHub-token setup wizard Fish, Nushell Neither fish's read nor nu's input has a timeout flag at all (unlike bash's read -t). Shells out to timeout/gtimeout if one is installed; otherwise falls back to an untimed prompt, still gated on being a real interactive tty so it can never block a non-interactive shell.
zcompile-equivalent bundle byte-caching Fish, Nushell Neither has a bytecode-cache mechanism comparable to zsh's zcompile. Accepted as a minor, unavoidable cold-start cost; the cached-snippet mechanism still covers the genuinely expensive parts (tool inits).
oh-my-posh tooltips (git details while typing git/lg/lzg/lazygit) Bash, Nushell oh-my-posh only implements tooltips for zsh, fish and PowerShell; bash and nu's line editors have no hook for re-rendering the right prompt on each keystroke. Not implemented. The tooltip only adds detail: branch and status stay in the main prompt in every shell, and the kube context stays on line two instead of becoming a tooltip for the same reason.
PowerShell automatically restoring $env:SSH_AUTH_SOCK PowerShell, Nushell on native Windows Pre-existing gap, unrelated to the fish/nu work above — flagged here so it isn't mistaken for a new one. On native Windows, nredf-set-ssh-agent returns immediately: its Unix-socket logic (id, chmod, ssh-agent -a) cannot run there, and a Unix SSH_AUTH_SOCK would override the OpenSSH named pipe. WSL is unaffected. Out of scope for this document; PowerShell users configure SSH agent forwarding another way for now. With SSH_AUTH_SOCK unset, Windows OpenSSH uses its \\.\pipe\openssh-ssh-agent pipe.

FAQ & Troubleshooting

Q1: How are runtime versions (Node.js, Python, Ruby, Go) managed?

NREDF uses mise as the polyglot runtime and tool manager across all platforms and shells. mise activate is automatically hooked and cached during shell startup, allowing directory-based tool switching (.tool-versions, mise.toml).

Q2: PowerShell shows script execution error on Windows

Error: File ... cannot be loaded because running scripts is disabled on this system. Resolution: Run this command once in PowerShell:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Q3: How do I test shell startup performance?

Run reload -p. The output will display exact timing metrics for each component (PowerShell shown; Bash/Zsh/Fish/Nu report their own equivalent steps):

  [+   2ms] NREDF_BwRestoreSession
  [+   4ms] oh-my-posh init
  [+   8ms] PowerShell modules
  [+   6ms] Atuin init
  [+   4ms] zoxide init
  [+   3ms] carapace completions
  [+   5ms] mise activate
  [+   3ms] inshellisense init
  [+  35ms] Total PowerShell profile startup time

Run reload -p a second time to turn off persistent profiling.