Portable Zsh dotfiles, shell configuration, and system package tracking for Ubuntu/Debian.
Inspired by thdxr/environment. Uses GNU Stow to manage dotfiles, modular shell scripts for Zsh configuration, and per-machine package lists for reproducible Ubuntu setups across multiple servers and workstations.
- Modular Zsh setup -- shell config split into small, composable files under
custom/ - System package tracking -- record which apt packages belong to each machine, install them reproducibly
- Multi-machine support -- shared package groups (
base,dev,network,desktop) plus per-machine overrides - Zero bloat -- no frameworks, no oh-my-zsh, no heavy plugins. Just Zsh + zplug + Starship
- Secrets separated -- tokens and machine-specific config live in
~/.zshrc.local(gitignored) - One-command bootstrap --
installscript handles dependencies and deploys dotfiles
environment/
├── home/ # Dotfiles managed with GNU Stow (symlinked to ~)
│ ├── .zshrc # Clean, modular zshrc
│ ├── .gitconfig # Git config
│ └── .config/
│ └── starship.toml # Starship prompt theme
├── custom/ # Modular shell config sourced by .zshrc (in order)
│ ├── 00-environment # PATH, env vars (Go, Bun, pnpm, fnm, etc.)
│ ├── 01-history # History settings
│ ├── 02-aliases # General aliases
│ ├── 03-git # Git shortcuts
│ ├── 04-functions # Shell functions
│ └── 05-completions # SDKMAN, Conda, Homebrew, etc.
├── packages/ # System package tracking per machine
│ ├── install # Install all tracked packages for a host
│ ├── analyze # Find installed packages not in any group
│ ├── clean # Remove orphaned dependencies
│ └── group/ # Package lists by group and machine codename
│ ├── base # Core packages (all machines)
│ ├── dev # Development tools
│ ├── network # Cloud/networking tools
│ ├── desktop # GUI packages
│ ├── baltimore/ # Laptop (x86_64)
│ └── enterprise/ # ARM dev server
├── install # Bootstrap script (installs deps + deploys dotfiles)
└── .gitignore
git clone git@github.com:ImBIOS/environment.git ~/dev/environment
~/dev/environment/install
# Edit ~/.zshrc.local with your secrets and machine-specific config
source ~/.zshrcThe install script handles everything:
- Installs system dependencies (stow, zsh, zplug, fzf, starship, fnm, bun, pnpm, uv, rustup, gh, and more)
- Deploys dotfiles to your home directory via
stow - Creates a
~/.zshrc.localtemplate for your secrets if it doesn't exist
Track and reproduce apt packages across machines.
# Install all tracked packages for current machine
~/dev/environment/packages/install
# Install for a specific machine by codename
~/dev/environment/packages/install enterprise
# Find installed packages not tracked in any group
~/dev/environment/packages/analyze
# Remove orphaned dependencies
~/dev/environment/packages/clean-
Create a group directory with its codename:
mkdir ~/dev/environment/packages/group/<codename>
-
Run
analyzeon that machine to find untracked packages -
Add the codename to the table below
| Codename | Machine | Arch | Role |
|---|---|---|---|
| baltimore | Local laptop | x86_64 | Desktop + development |
| enterprise | Oracle ARM server | aarch64 | Dev server + Docker Swarm manager |
Secrets and machine-specific config go in ~/.zshrc.local (not tracked in git). The install script creates a template if it doesn't exist.
| Tool | Purpose |
|---|---|
| Zsh | Shell |
| zplug | Zsh plugin manager |
| Starship | Cross-shell prompt |
| fzf | Fuzzy finder |
| GNU Stow | Dotfile symlinks |
| fnm | Node.js version manager |
| Bun | JavaScript runtime |
| pnpm | Node package manager |
| uv | Python package manager |
| Rustup | Rust toolchain installer |
MIT