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

.
├── 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:

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:

just setup all

This runs the full flow in Scripts/setup.sh:

1. base system setup
2. node
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

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 <tool> 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

Zsh/.zsh_secrets

That file is intended to be stowed to:

$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:

~/.dotzsh-pre-stow-backup/<timestamp>/

---

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 <tool>

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:

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:

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:

~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:

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:

make setup
just setup all

If you only want shell files re-linked:

just setup clean
just setup stow

If you only want to refresh pinned binaries:

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.