Skip to content

SETUP.md

Latest commit

 

History

History
100 lines (73 loc) · 3.59 KB

SETUP.md

File metadata and controls

100 lines (73 loc) · 3.59 KB
Raw

Setup guide

How to get these dotfiles running on a fresh machine, start to finish.

How it works (30-second version)

The repo is the source of truth. Each tracked file is symlinked into $HOME, so the place a tool looks (~/.zshrc) points back at the real file in this repo. There's only one copy — editing either path edits the same file, and git status sees every change. Machine-specific or secret config lives in ~/.zshrc.local, which .zshrc sources if present but which is never committed.

See README.md for the tracked-file list.

Prerequisites

Tool Required? Why
zsh required the shell .zshrc configures (default on macOS)
oh-my-zsh required .zshrc sources it directly; shell errors without it
tmux for tmux config needed only if you want tmux.conf to do anything
Homebrew + zsh-autosuggestions optional enables inline command suggestions; skipped cleanly if absent

Everything else referenced in .zshrc (sdkman, bun, p10k, Homebrew python) is guarded — if it isn't installed, the line is silently skipped. No errors.

Install the prerequisites (macOS)

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

# Homebrew (optional, for zsh-autosuggestions)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# optional extras
brew install tmux zsh-autosuggestions

The oh-my-zsh installer creates its own ~/.zshrc. That's fine — the next step backs it up and replaces it with the symlink to this repo.

Install the dotfiles

git clone <repo-url> ~/code/personal/dotfiles
cd ~/code/personal/dotfiles
./install.sh

install.sh symlinks each tracked file into $HOME. For each one it:

  • leaves it alone if the correct symlink already exists (ok:),
  • moves any existing real file to <file>.backup first (so nothing is lost),
  • then creates the symlink (link:).

It's idempotent — safe to re-run any time (e.g. after adding a new tracked file).

Recreate your machine-local config

~/.zshrc.local is intentionally not in the repo (it holds secrets / school logins / per-host paths). Create it from the template and edit:

cp .zshrc.local.example ~/.zshrc.local
$EDITOR ~/.zshrc.local

Reload and verify

exec zsh          # restart the shell so the new config loads
zsh -n ~/.zshrc   # optional: syntax-check, prints nothing if OK

You should get a clean prompt with no errors. If ~/.zshrc.local exists, its aliases/overrides are now active.

Adding a new file to the repo later

  1. Move the real file into the repo, preserving its relative path: mv ~/.foo ~/code/personal/dotfiles/.foo
  2. Register it in install.sh:
    • lives at $HOME/<same path> → add to the FILES array;
    • lives elsewhere (e.g. VSCode under ~/Library) → add a "repo-path|absolute-target" entry to the LINKS array. Also add it to the table in README.md.
  3. Run ./install.sh to create the symlink.
  4. git add -A && git commit.

Troubleshooting

  • oh-my-zsh.sh: no such file or directory — oh-my-zsh isn't installed; run the installer above.
  • An override didn't apply — make sure it's in ~/.zshrc.local (not the repo copy) and that the file exists; the source line at the end of .zshrc only runs when the file is present.
  • install.sh says backup: — a real file was in the way and got saved as <file>.backup. Diff it against the repo version, then delete the backup once you're happy.