dotfiles

Personal dotfiles config and packages to bootstrap my environment. Managed with chezmoi.

Supports macOS (Homebrew) and Arch Linux (pacman).

---

Quick Start

Prerequisites

You need git and just before anything else. There is a chicken-and-egg situation here: the justfile manages setup, but just itself must be installed first.

macOS

# Install Homebrew (if not already installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install just
brew install just

Arch Linux

sudo pacman -S --needed git just

---

1. Clone this repo

git clone https://github.com/gcaracuel/dotfiles.git ~/Projects/github/gcaracuel/dotfiles
cd ~/Projects/github/gcaracuel/dotfiles

2. Install Homebrew (if needed) + chezmoi, and link this repo as the source

just init

This will:

1. Install Homebrew (macOS only, if missing)
2. Install chezmoi
3. Create the symlink: ~/.local/share/chezmoi → <this-repo>/home
4. Initialize chezmoi config (prompts for work mode)

You will be asked:

Include work packages?

To change the work mode later: chezmoi init again or chezmoi edit-config.

3. Apply

just apply

---

What it does

Step	What happens
run_once_before_00	Installs Homebrew (macOS) or validates pacman (Arch)
run_onchange_01	brew bundle — installs/uninstalls Homebrew packages
run_onchange_02	pacman -S — installs/uninstalls Arch packages
run_onchange_03	mise install — installs runtimes (node, python, rust, go, bun, ...)
run_onchange_04-07	pnpm / pip / cargo / bun global packages
run_onchange_08	VSCode extensions
run_onchange_09	kubectl krew plugins
run_once_10	Oh My Zsh
run_once_11	LazyVim starter for Neovim
run_once_99	Prints MANUAL_STEPS.md

Dotfiles in home/ are symlinked to $HOME by chezmoi.

---

Where to add/remove packages

What	File
Homebrew formulas/casks	packages/Brewfile
Homebrew work packages	packages/Brewfile.work
Arch/pacman packages	packages/packages.txt
Arch work packages	packages/packages.work.txt
Programming runtimes (node, python, rust...)	home/dot_config/mise/config.toml
pnpm global packages	packages/pnpm-packages.txt
pip packages	packages/pip-packages.txt
cargo packages	packages/cargo-packages.txt
bun packages	packages/bun-packages.txt
VSCode extensions	packages/vscode-extensions.txt
kubectl krew plugins	packages/krew-plugins.txt

After editing any file, run just apply to sync.

Uninstall detection: removing a package from its list and running just apply will uninstall it.

---

Package manager rule of thumb

• Homebrew / pacman — system CLI tools and GUI apps available on both platforms
• Mise — programming language runtimes (node, python, rust, go, bun, terraform...)
• npm / pip / cargo / bun via Mise — language-specific tooling not in brew/pacman; pnpm is used instead of npm
• .tool-versions — kept in $HOME for asdf coworker compatibility (auto-linked by chezmoi)

---

Daily workflow

just apply          # Apply all changes
just update         # git pull + apply
just diff           # Preview pending changes
just add ~/.foo     # Add a new dotfile to chezmoi
just edit ~/.foo    # Edit a managed dotfile

---

Force reinstall packages

Package install scripts only re-run when their source file changes (using run_onchange_ scripts). To force a re-run without editing files (useful for upgrading packages to latest versions or troubleshooting):

just reinstall-packages           # Force re-run ALL package managers
just reinstall brew               # Force re-run Homebrew only
just reinstall pacman             # Force re-run pacman only
just reinstall npm                # Force re-run npm globals only
just reinstall pip                # Force re-run pip/uv packages only
just reinstall cargo              # Force re-run cargo packages only
just reinstall bun                # Force re-run bun globals only
just reinstall vscode             # Force re-run VSCode extensions only
just reinstall krew               # Force re-run kubectl krew plugins only

This bumps a # force-run: timestamp in the package file, triggering chezmoi to re-run the install script.

---

Testing

Tests run in isolated Docker containers — never on the host machine.

just test           # Interactive: choose Arch or Homebrew
just test-arch      # Arch Linux container
just test-brew      # Homebrew container
just test-arch-shell  # Interactive shell in Arch container
just test-brew-shell  # Interactive shell in Brew container
just clean          # Remove test images

---

Manual steps

Some things can't be automated. After first setup, chezmoi prints MANUAL_STEPS.md. You can also view it directly:

cat MANUAL_STEPS.md

---

Future work

Fork Pi Agent extensions

The Pi Agent extensions are currently pinned to upstream SHAs in home/dot_pi/agent/settings.json:

Extension	Current upstream
pi-btw	github.com/dbachelder/pi-btw
pi-guardrails	github.com/aliou/pi-guardrails
pi-rtk-optimizer	github.com/MasuRii/pi-rtk-optimizer

To own these extensions long-term (custom modifications, controlled updates, no dependency on upstream availability):

1. Fork each repo into your own GitHub account (e.g. github.com/gcaracuel/pi-btw)
2. Update the packages entries in home/dot_pi/agent/settings.json to point at your forks
3. Pin to a commit SHA on your fork:

   "git:github.com/gcaracuel/pi-btw@<sha>"

4. To update a pinned extension after making changes to a fork, get the new SHA and update the entry, then run chezmoi apply

This approach gives you full control over extension behaviour and eliminates the risk of breaking upstream changes.