Manage dotfiles with clear ownership

A dotfiles repository versions the configuration files you shaped earlier in this course — .zprofile, .zshrc, .gitconfig, .ssh/config. Track the ones you understand and actively maintain, not everything hiding in your home directory.

A dotfiles repository should make ownership obvious. For every file the repo manages, two questions need answers written down: which destination does it own, and how does it get there? List each managed destination and whether setup copies, links, or generates it:

| Repo file      | Destination     | Method   |
| -------------- | --------------- | -------- |
| zsh/zprofile   | ~/.zprofile     | symlink  |
| zsh/zshrc      | ~/.zshrc        | symlink  |
| git/gitconfig  | ~/.gitconfig    | copy     |
| ssh/config     | ~/.ssh/config   | generate |

Symlinks keep the file editable in one place. Copies suit files that drift per machine. Generated files handle templates with machine-specific values.

Never replace silently

The dangerous moment is installation on a machine that already has configuration. Before changing a destination, compare it and preserve an existing file:

test -e ~/.zshrc && diff -u ~/.zshrc dotfiles/zshrc || true

Empty diff: safe to link. Any output: the existing file has something your repo does not, and you decide what to keep before anything is overwritten.

Prefer an explicit installer that stops on conflict:

install_link() {
  local src="$1" dest="$2"
  if [ -e "$dest" ] && [ ! -L "$dest" ]; then
    print -u2 "conflict: $dest exists, resolve manually"
    return 1
  fi
  ln -sf "$src" "$dest"
}

The realistic disaster this prevents: you run a clever installer on your old Mac, it “helpfully” force-links everything, and the .zshrc carrying two years of local fixes is gone. Stopping on conflict turns that into a message instead of a loss.

Keep secrets out

Dotfiles repositories tend to become public, sometimes years after creation. Do not commit tokens, host-specific identifiers, shell history, or the contents of Keychain. History files are a classic leak: they contain every command you typed, including the ones with passwords in them.

Remember that Git preserves deleted files in history — committing a secret and removing it next commit removes nothing. If it happens, revoke the credential; don’t just delete the line.