54 lines
2.0 KiB
Markdown
54 lines
2.0 KiB
Markdown
# dotfiles repo agent guide
|
|
|
|
This repo is a collection of personal config files deployed via GNU Stow.
|
|
|
|
## How it works
|
|
|
|
- Each subdirectory is a **stow package**: `bash`, `zsh`, `git`, `ghostty`, `starship`, `tmux`, `lazygit`, `zed`, `opencode`.
|
|
- Directory structure mirrors `$HOME` (e.g. `git/.gitconfig` → `~/.gitconfig`).
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
# Deploy all packages (auto-installs stow via apt if missing)
|
|
./setup.sh
|
|
|
|
# Selective install
|
|
./setup.sh --only=git,zsh
|
|
|
|
# Preview without changes
|
|
./setup.sh --dry-run
|
|
|
|
# Remove symlinks
|
|
./uninstall.sh
|
|
./uninstall.sh --only=git # selective removal
|
|
```
|
|
|
|
All scripts accept `--verbose`, `--quiet`, `--dry-run`.
|
|
|
|
## Adding a new package
|
|
|
|
```bash
|
|
mkdir <name>
|
|
cp ~/.<configfile> <name>/
|
|
./setup.sh --only=<name>
|
|
```
|
|
|
|
## Toolchain auto-installed by setup.sh
|
|
|
|
`setup.sh` installs these tools to `~/.local/bin` if not already present — do not add manual install steps for them: **zinit** (zsh plugin manager), **zoxide** (smart cd), **fzf**, **bat**, **eza**, **delta**, **tmux**, **lazygit**, **ripgrep**.
|
|
|
|
## Theming convention
|
|
|
|
All tools are themed with **Gruvbox Dark Hard**. When adding config for a new tool, apply Gruvbox colors to keep the environment cohesive.
|
|
|
|
## Important constraints
|
|
|
|
- Default shell is **zsh** (`bash/.bashrc` does NOT exec zsh — set your default shell with `chsh`). Uses **zinit** as plugin manager (turbo mode for async loading).
|
|
- `.bashrc` sources `~/.bash_aliases`; `.zshrc` sources `~/.zsh_aliases`.
|
|
- **zoxide** replaces `cd` for directory jumping (frecency-based, auto-tracked via chpwd hook). `j` alias for `zoxide cd`.
|
|
- **Sensitive files are gitignored**: `.netrc`, SSH keys (`id_rsa*`, `known_hosts`), gradle caches.
|
|
- The `opencode/` package stows OpenCode's own config (`~/.config/opencode/`). Do not treat it as a repo instruction file — that file is `AGENTS.md` at the repo root.
|
|
- No build, test, lint, or typecheck steps — this is pure config.
|
|
- Backups of pre-existing real files are created at `~/.dotfiles-backup-YYYYMMDD-HHMMSS` before stowing.
|