# Dot-Zsh Personal cross-platform shell and workstation bootstrap for: - Arch Linux - Ubuntu / Debian-family Linux - Fedora - macOS - WSL The repo is built around a small bootstrap path and a fuller `just`-based workflow. --- ## Layout ```text . ├── Bins/ # Pinned binary versions (nvim, eza, ...) ├── Commands/ # just modules ├── Scripts/ # install/setup scripts ├── Zsh/ # stowed shell files ├── Justfile # main just entrypoint └── Makefile # lightweight bootstrap entrypoint ``` ### Key folders #### `Zsh/` Stowed into `$HOME`. - `.zshrc` - `.zshenv` - `.zsh_aliases` - `.zsh_prompt` - `.zsh_completion` - `.zsh_secrets` - `.zsh_secrets.example` #### `Scripts/` Main install logic. - `base.sh` — system/base packages and common tools - `setup.sh` — full setup flow - `node.sh`, `go.sh`, `rust.sh`, `python.sh`, `r.sh`, `cpp.sh` - `bin/install.sh` — install pinned repo-managed binaries - `bin/update.sh` — update pinned binary versions #### `Commands/` Modular `just` commands. - `Commands/Setup/mod.just` - `Commands/Lang/mod.just` - `Commands/Bin/mod.just` #### `Bins/` `versions.json` is the source of truth for pinned binary versions and per-platform asset mappings. --- ## Core workflow ### Bootstrap only Use `make setup` when you want the lightweight bootstrap path: ```bash make setup ``` This currently does: 1. run `Scripts/base.sh` 2. remove old `Zsh` stow links 3. stow `Zsh/` into `$HOME` It is intentionally small. ### Full setup Use `just setup all` for the full machine setup: ```bash just setup all ``` This runs the full flow in `Scripts/setup.sh`: 1. base system setup 2. node / pnpm / yarn / bun 3. go / gvm 4. rust 5. python / pyenv / miniforge 6. r 7. secret-file reconciliation 8. backup of conflicting unmanaged dotfiles 9. stow `Zsh/` ### Other useful commands ```bash just setup base just setup stow just setup clean just setup update just lang node just lang go just lang rust just lang python just lang r just lang cpp just bin show just bin install-all just bin install nvim just bin list nvim just bin update nvim ``` If `fzf` is available, `just bin update ` can use interactive selection. --- ## Secrets model This repo now treats shell secrets as repo-managed local dotfiles instead of tracked plaintext config. ### Source of truth ```text Zsh/.zsh_secrets ``` That file is intended to be stowed to: ```text $HOME/.zsh_secrets ``` ### Important notes - `.zsh_secrets` is ignored by git - `.zsh_secrets.example` exists as a template/reference - setup tries to reconcile an existing `$HOME/.zsh_secrets` safely - if conflicting unmanaged dotfiles already exist, setup backs them up before stowing Backup location: ```text ~/.dotzsh-pre-stow-backup// ``` --- ## Binary management This repo no longer stores shipped binaries in git. Instead: - pinned versions live in `Bins/versions.json` - installs go into `~/.local/bin` - updates happen through `just bin update ` Current managed binaries include: - `nvim` - `eza` Platform behavior: - Linux: install from pinned release assets - macOS: install from pinned asset when supported, or use Homebrew formula fallback when configured --- ## Shell behavior ### Prompt Prompt logic lives in: ```text Zsh/.zsh_prompt ``` It adds: - git branch - git dirty/clean indicator - conda / direnv context - repo-scoped project markers - language version hints - separator rule between prompts ### Completion Completion logic lives in: ```text Zsh/.zsh_completion ``` It adds: - custom first-word command completion - recently used commands shown first - used commands visually marked with `*` - wrapper completion bindings for lazy-loaded tools like `gvm`, `conda`, `go`, `node`, `npm`, and `npx` ### Lazy loading Several language managers are intentionally lazy-loaded to keep shell startup lighter. Examples: - `nvm` - `gvm` - `pyenv` - `conda` `openchamber` auto-start is restricted to WSL sessions. --- ## Install size Measured practical installed footprint on Linux is roughly: - Ubuntu: about `1.96 GB` - Arch: about `1.84 GB` - Fedora: about `1.77 GB` So the setup is best thought of as: ```text ~1.8 GB to ~2.0 GB total ``` ### Largest components Measured Ubuntu component breakdown: - Rust: about `1.5 GB` - Python: about `1.1 GB` - Go: about `635 MB` - Node: about `235 MB` - `~/.local`: about `128 MB` - R wrapper/user area under `~/.programming/r`: very small (`~20 KB` in that measurement) Important nuance: - `~/.programming/r` is intentionally small because it mainly holds wrappers and user-library location - the actual R runtime may still come from the distro package manager or Rig, depending on platform - so not all R-related disk usage appears under `~/.programming/r` ### Measured paths Representative measured path sizes from Linux test runs: ```text Ubuntu ~/.programming ~3.17 GB ~/.local ~133 MB /usr/local ~13 MB Arch ~/.programming ~3.17 GB ~/.local ~133 MB Fedora ~/.programming ~3.17 GB ~/.local ~133 MB ``` Those path totals are larger than the final container image delta because some space is shared/overlapping across package layers and installed tooling. --- ## Notes by platform ### Linux - full setup has been exercised in container tests on Ubuntu, Arch, and Fedora x86_64 ### macOS - supports Homebrew-based package install flow - uses `/bin/zsh` for shell-change target - handles existing dotfiles and secret symlink reconciliation more carefully ### WSL - WSL-specific logic is used where needed - `openchamber` is only auto-started in WSL --- ## First-run recommendation If you are starting clean: ```bash make setup just setup all ``` If you only want shell files re-linked: ```bash just setup clean just setup stow ``` If you only want to refresh pinned binaries: ```bash just bin install-all ``` --- ## Current philosophy This repo aims to be: - owned rather than magical - reproducible rather than ad hoc - modular rather than one giant dotfile blob - explicit about pinned binaries and local secrets It is not trying to be the smallest possible install. It is trying to be a repeatable personal workstation setup.