Add README and shell polish
This commit is contained in:
MangoPig
337
README.md
337
README.md
@@ -0,0 +1,337 @@
|
||||
# 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
|
||||
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 <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
|
||||
|
||||
```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/<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:
|
||||
|
||||
```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.
|
||||
|
||||
Reference in New Issue
Block a user