dotfiles

Overview

These dotfiles exist because of two separate problems that compounded each other.

The first is accessibility. I lost sight in my right eye at age two due to retinoblastoma and have worked with monocular vision my entire life. A monochrome terminal is a wall of text. With monocular vision you cannot rely as much on the spatial depth cues that binocular vision provides - the subtle sense of layers that helps the brain pre-parse where sections begin and end. Colour takes over that job. The profile defines a consistent colour system in 02-colours: cyan borders and command names, magenta section headers, green for success, yellow for dates, red for errors. Every colour was chosen to remain distinguishable under common deuteranopia and protanopia simulations and tested on both dark and light terminal themes. The cmds function prints a full colour-coded command reference grouped by topic, saves the cursor position first so clast can snap everything back to exactly where you were without scrolling.

The second problem is context switching. I work across three machines: a MacBook Air running zsh, a Lenovo laptop running Linux with bash and a Windows gaming PC running PowerShell 7. Every time I switched machines I had to remember different commands for the same operations: pbcopy on macOS, xclip on Linux, Set-Clipboard on Windows. ipconfig getifaddr en0 on macOS, hostname -I on Linux. The goal of the naming convention is that copy, paste, localip, dns-flush, gs, gaa, gc, gp, dcu, dcd and every other alias mean exactly the same thing and behave exactly the same way on all three platforms. The implementation differs per platform, the name never does.

The architecture is 59 numbered topic files per platform, one per area of concern. The zshrc, bashrc and PowerShell profile loaders are each five lines: a glob that sources every numbered file in order. Number ordering is deliberate - 02-colours defines the ANSI variables that 06-functions uses in the welcome banner and cmds. 23-kubernetes defines kc as kubectl before 37-kotlin loads, which is why the Kotlin compile shortcuts are ktc and ktcr rather than kc. The topic files cover PATH and environment, git, mirroring, navigation shortcuts, SSH, network diagnostics, security and crypto, databases, JSON, file sync, Homebrew, GitHub CLI, nvm, editors, shell tools, tmux, Docker, Kubernetes, cloud platforms, Terraform, Helm, Vagrant, Ansible, and 30+ language toolchains from Python, Node, Go and Rust through Kotlin, Scala, Haskell, Elixir, VHDL, Zig and Ada to Flutter, Android ADB, NVIDIA CUDA, game engines, CAD tools, FFmpeg, Blender and Adobe.

nvm is lazy-loaded via stub functions that replace themselves on first call. Sourcing nvm.sh on every shell start costs roughly 200ms on the MacBook Air. The stubs intercept the first call to node, npm, npx or any nvm command, run unset -f to clear all stubs, source the real nvm.sh, then call through with the original arguments. Every subsequent call goes directly to nvm. The 200ms cost is paid once per session, not on every new tab.

Starship is the prompt, initialised last at topic file 59-starship so all aliases and environment variables from the previous 58 files are already loaded. One shared/starship.toml covers all three platforms - changing it once updates the prompt on every device. Modules are enabled only for the languages covered by the topic files.

Every git push fans out to GitHub, GitLab and Codeberg simultaneously via multiple remote.origin.pushurl entries - no CI required. A global pre-push hook auto-registers new repos on both platforms on the first push so mirroring is never something to remember. A fifth platform, Gitea, receives five repos via GitHub Actions using SSH push because the Gitea community server's ELB blocks HTTPS push from non-AWS IPs. A git() wrapper deduplicates the repeated output lines produced by a multi-URL push using awk '!seen[$0]++'. sync-meta reads GitHub repo metadata and writes it to GitLab and Codeberg via their APIs so descriptions, topics and homepage URLs stay in sync.

CI runs ShellCheck on every shell file and markdownlint on every markdown file on every push via GitHub Actions. An engineering journal of nine entries documents every significant decision: why the profile was split from one 275-line file to 59 topic files, the colour and accessibility choices, every alias conflict and how it was resolved, the nvm lazy-loading mechanism, the mirror architecture and why push URLs beat GitHub Actions for mirroring, how Windows PowerShell files were verified without a PowerShell interpreter using static analysis, why doc/ was renamed to journal/ and how the Starship prompt was added and configured.

Key highlights

• ·59 numbered topic files per platform covering 30+ language toolchains, DevOps, cloud, hardware, media and productivity tools - loader is five lines
• ·Identical alias names on macOS (zsh), Linux (bash) and Windows (PowerShell 7) - same muscle memory on every machine, platform differences hidden inside the function body
• ·Accessibility-first colour scheme designed for monocular vision: cyan, magenta, green and yellow chosen to be distinguishable under deuteranopia and protanopia simulations
• ·Every git push fans out to GitHub, GitLab and Codeberg via push URLs; a global pre-push hook auto-registers new repos on both platforms on first push
• ·nvm lazy-loaded via stub functions - saves ~200ms on every shell start, paid once per session at first use
• ·One shared/starship.toml prompt config for all three platforms, initialised last at topic file 59 after all aliases and environment variables are loaded
• ·ShellCheck and markdownlint CI on every push via GitHub Actions
• ·Engineering journal of 9 entries documenting every major decision: the modular refactor, colour choices, alias conflicts, nvm lazy loading, mirror architecture, Windows static analysis and Starship setup

Technologies