# 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` - `Commands/Git/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 bootstrap just setup stow just setup clean just setup update just git show just git editor just git editor nvim just lang node just lang go just lang rust just lang python just lang r just lang cpp just bin show just bin list just bin install-all just bin install nvim just bin releases nvim just bin list nvim # backwards-compatible shorthand for releases just bin update nvim just lang all ``` If `fzf` is available, `just bin update ` can use interactive selection. `just setup all` and `just setup base` now set the default global Git editor to VS Code (`code --wait`). If you want to switch to Neovim later, run `just git editor nvim`. --- ## 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.