Supports macOS, Debian/Ubuntu, and Windows 11 through WSL.
Warning
Use at your own risk.
Script will download this repository to ~/.dotfiles and will symlink the appropriate files to your home directory.
-
Windows (from an elevated PowerShell, then follow the Linux steps inside WSL):
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass; Invoke-Expression (Invoke-RestMethod -Uri "https://raw.githubusercontent.com/kylejb/dotfiles/HEAD/installer.ps1")
-
MacOS / Linux:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/kylejb/dotfiles/HEAD/installer.sh)"
Everything is configurable from this folder. The main file you'll want to change right off the bat is zsh/zshrc.symlink, which sets up a few paths that may differ on your particular machine.
dot (in bin/, on your $PATH after install) is the single front door for
managing these dotfiles:
dot -i, --install Install dotfiles (runs script/bootstrap)
dot -u, --update git pull + run all topic update.sh scripts
dot -a, --apply Refresh symlinks + re-render configs (no package install)
dot -d, --defaults Re-apply macOS defaults (macOS only)
dot -e, --edit Open the dotfiles directory in $EDITOR
dot --uninstall Remove symlinks (does NOT remove installed packages)
dot -h, --help Show usage
Run dot -u from time to time to keep your environment fresh. On Windows, run
dot inside WSL; it refuses to run in native Windows shells.
Windows runs the Linux setup inside WSL, so there is one implementation to
maintain. installer.ps1 installs WSL with Ubuntu; from there, use the normal
Linux install and dot.
On the personal profile in WSL, git signs through the 1Password app on
Windows, using op-ssh-sign-wsl.exe and ssh.exe.
This path has not been tested on a real Windows machine yet.
Each machine has a profile — personal or work — that lets tooling, git
identity, and secret handling differ per machine. Install prompts for it once
and writes the single word to ~/.config/dotfiles/profile (untracked). It is
exported as $DOTFILES_PROFILE early in zsh/zshenv.symlink, so any script or
shell can gate on it. dot -a warns if it is missing or invalid; to set it on
an existing machine, write personal or work to that file.
Helpers live in utils.sh: get_profile, is_personal, is_work. The key
rule: the work profile must never invoke 1Password (op) — work uses
local secrets only.
git/apply.sh renders config/git/config.local (the include target of
config/git/config) once per machine: personal gets the full identity plus
1Password op-ssh-sign commit signing; work gets a stub with
gpgsign = false and a TODO to fill in the work email. The file is
user-owned and never overwritten — edit it freely, or delete it and run
dot -a to regenerate, for example after changing the template or rotating the
key. Even on personal, no script ever shells out to op;
only the signer's path is written into the config.
ai/apply.sh links the shared ai/AGENTS.md to ~/.claude/CLAUDE.md and
~/.codex/AGENTS.md, and links each skill in ai/skills/ into
~/.claude/skills/. After adding or deleting a skill, run dot -a: it links
new skills and removes the links of deleted ones.
~/.claude/settings.json is not managed, because Claude Code rewrites it.
The setup scripts (installer.sh, bin/dot, script/*, */install.sh,
*/apply.sh, */update.sh, utils.sh) are POSIX sh and self-contained:
each sets DOTFILES (with a fallback) and sources utils.sh itself. This is
deliberate, not redundant — do not "centralize" it into bin/dot:
execdoes not preserve shell functions, only exported env.bin/dotexportsDOTFILES(which survivesexec) but cannot hand downutils.sh's functions (is_macos,info, …) —execreplaces the process image and drops them. Each script must sourceutils.shitself.- First-time install bypasses
dot.installer.sh(run viacurl | sh) sourcesscript/bootstrapdirectly, beforedotis on$PATH. So scripts can't assumedotset anything up.
Net effect: every script runs correctly via dot, via installer.sh,
when called internally by bootstrap, and standalone for debugging. dot is
the user-facing CLI (flags, help, platform guard); it is not the only caller.
Everything is built around "topic" areas. If you're adding a new area to your
forked dotfiles — "Java", for instance — you can add a java directory and put
files in there. Anything with an extension of .zsh will get automatically
included into your shell. Anything with an extension of .symlink will get
symlinked without extension into $HOME when you run script/bootstrap.
There are a few special files in the hierarchy.
- bin/: Anything in
bin/will get added to your$PATHand be made available everywhere. - topic/*.zsh: Any files ending in
.zshget loaded into your environment. - topic/path.zsh: Any file named
path.zshis loaded first and is expected to setup$PATHor similar. - topic/completion.zsh: Any file named
completion.zshis loaded last and is expected to setup autocomplete. - topic/install.sh: Installs packages/tools (the heavy, occasional path). Run via
script/install(and during a fulldot -i). Use this for anything that fetches/builds software. - topic/apply.sh: (Re-)renders and links config — the fast, frequent path with no package installs. Run via
dot -a/script/apply(and during a full install). Use this for templated/generated configs (seegnupg/) and symlinking config into place (seeai/,ssh/). Prefer rendering (template → generated, gitignored file) over a raw symlink whenever an app rewrites its own config or it must vary per machine. - topic/update.sh: Refreshes already-installed tools (e.g.
mise self-update,gem update). Run viascript/update/dot -u. Extension is.sh, not.zsh, to avoid being auto-loaded. - topic/*.symlink: Any file ending in
*.symlinkgets symlinked into your$HOME. This is so you can keep all of those versioned in your dotfiles but still keep those autoloaded files in your home directory. These get symlinked in when you runscript/bootstrap.
These scripts are run as sh "$script", which ignores shebang flags (a
#!/bin/sh -e shebang does not enable -e). So:
install.sh/apply.share fail-fast — put an explicitset -eline in them (not just the shebang). A half-installed package set or partially-applied config should stop loudly, not silently continue.update.shis best-effort — noset -e; independent maintenance steps (update tool A, then tool B) shouldn't abort each other.- Every runner (
script/install,script/apply,script/update) usesrun_topic_scriptsfromutils.sh: it runs each topic's script in sorted order, warns on each failure, keeps going, and exits non-zero if any failed. So one failure neither kills the batch nor passes silently. A failed install batch stopsbootstrapbefore shell and config setup.
A decent amount of code stem or are inspired by Juan Manual Orbegoso's dotfiles and Zach Holman's dotfiles.