dotfiles

Single source of truth for nvim and zsh config, managed with GNU Stow.

Each top-level directory is a "package" whose contents mirror $HOME. Stow symlinks package contents into $HOME.

Layout

dotfiles/
  nvim/.config/nvim/...
  zsh/.zshrc .zprofile .zshenv
  herdr/.config/herdr/config.toml
  git/.gitconfig

Prerequisites

Install the underlying tools before symlinking config (Ubuntu/WSL, apt).

zsh

sudo apt update && sudo apt install zsh

# make zsh the default shell
chsh -s "$(which zsh)"

oh-my-zsh

sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

This .zshrc also expects this oh-my-zsh plugin to be installed as a custom plugin (the others in the plugins=(...) array, e.g. direnv, are built into oh-my-zsh and just need their underlying binary installed):

git clone https://github.com/zsh-users/zsh-autosuggestions \
  "${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/plugins/zsh-autosuggestions"

oh-my-posh

curl -s https://ohmyposh.dev/install.sh | bash -s

.zshrc references the catppuccin theme bundled with oh-my-posh (--config catppuccin); no extra theme file needed.

herdr

Install per https://herdr.dev.

herdr/.config/herdr/config.toml sets onboarding = false and remaps the prefix key to ctrl+a.

aven

Local-first task manager, https://aven.raine.dev. Install with the release script:

curl -fsSL https://raw.githubusercontent.com/raine/aven/main/scripts/install | bash

.zshrc aliases av to aven tui.

git

git/.gitconfig sets user.name/user.email to a specific identity, along with gh-backed credential helpers, delta as the diff/pager, and a few other defaults (default branch, diff3 conflict style, etc). Update the [user] section before adopting this on a machine with a different git identity.

Bootstrap on a new machine

Run the bootstrap script to install every tool these dotfiles need (zsh, oh-my-zsh + plugins, direnv, oh-my-posh, ripgrep/fd/build tools, neovim, rust, uv, nvm/node, herdr, aven, gh/delta/git-credential-manager, just) and symlink the configs in one go:

git clone <remote-url> ~/dotfiles
cd ~/dotfiles
./scripts/bootstrap.sh

It's interactive by default: it prints an overview up front and asks for confirmation before installing (and again before a few individual steps, e.g. changing your default shell or overwriting existing dotfiles). Pass -y to assume "yes" everywhere and run fully unattended:

./scripts/bootstrap.sh -y

Re-running it is safe; each step skips itself if already installed. A failure in one step doesn't abort the rest — failed steps are summarized at the end. Skip specific steps with SKIP=<step1>,<step2> (step names match the ones logged as the script runs, e.g. SKIP=herdr,aven). Note: herdr has no scripted installer (the script pauses so you can install it manually), and tools not covered by this repo's config (opencode, ronin) are not installed by the script and must be set up separately.

Alternatively, install prerequisites manually per the sections above, then just symlink the configs directly:

Requires just (uv tool install rust-just).

git clone <remote-url> ~/dotfiles
cd ~/dotfiles
just install

just install installs stow if missing (via apt) and symlinks all packages into $HOME.

If a target file already exists (e.g. a stock .zshrc), remove/back it up first, or run just adopt to pull the existing file into the repo instead of overwriting it (then check git diff to make sure nothing unwanted was adopted).

Adding a new package

mkdir -p dotfiles/<name>/path/to/mirror
mv ~/path/to/config dotfiles/<name>/path/to/mirror/

Add <name> to the packages variable in the justfile, then run:

just restow

Other commands

just uninstall  # remove symlinks, keep files in repo
just restow      # re-stow after editing package structure
just adopt       # pull existing target files into the repo