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, starship, netrc.
Directory structure mirrors $HOME (e.g. git/.gitconfig → ~/.gitconfig).

Commands

# 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

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, 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: individual .netrc files, SSH keys (id_rsa*, known_hosts), gradle caches. The netrc/ package contains a tracked template (gitignore exception via !netrc/.netrc).
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.

1.9 KiB Raw Blame History