Guide 3 of 7 · Where files live

Where the files live

The real files stay in one folder, ~/.dotfiles. Your home folder holds signposts that point at them, one for each tool.

Tools expect their settings in fixed places: git looks in ~/.config/git, SSH looks in ~/.ssh/config. Copying files there would mean two versions that drift apart. So script/setup creates symlinks instead.

In plain words

A symlink is a signpost. When git walks up to ~/.config/git it finds a sign that says “the real folder is in ~/.dotfiles/config/git”, follows it, and never notices the detour. Edit the file from either side and you are editing the same file.

~/ your home folder

  • ~/.Brewfile a signpost ~/.dotfiles/Brewfile the shopping list brew bundle --global reads
  • ~/.zshenv a signpost ~/.dotfiles/config/zsh/.zshenv the shell's front door

~/.config/ a real folder, shared with every other app

  • ~/.config/zsh a signpost ~/.dotfiles/config/zsh the shell
  • ~/.config/git a signpost ~/.dotfiles/config/git git
  • ~/.config/nvim a signpost ~/.dotfiles/config/nvim the editor
  • ~/.config/… seven more signposts ~/.dotfiles/config/… tmux, ghostty, gh, homebrew, karabiner, mise, starship.toml
  • ~/.config/another-app a real folder Any other app's settings. They stay here, outside the repository.

~/.ssh/ a real folder, private to this Mac

  • ~/.ssh/config a signpost ~/.dotfiles/ssh/config SSH settings
  • ~/.ssh/known_hosts, config-local real files The servers this Mac has met, and its private hosts. They stay here.
Two real folders with signposts inside them, plus two signposts in the home folder itself.

The rule behind the map

script/setup walks the top level of the repository and does one of two things with what it finds.

Then it adds ~/.zshenv, because that one file has to sit in the home folder for zsh to find it. The repository's own scaffolding is skipped, so it never shows up in your home folder: script/, test/, guides/, the Makefile and anything ending in .md or .txt.

Why one signpost per tool

Dozens of apps keep their settings in ~/.config, and most of them have nothing to do with this repository. With one signpost per tool, their files stay in your home folder. They cannot be published by accident, and removing the dotfiles cannot delete them.

Adding a tool

Git's list of tracked files is the list of what gets linked. To bring a new tool's settings into the repository, put them under config/, git add them, and run script/setup again.

What if something is already there?

A Mac that has been used for a day already has files in these places. Setup never deletes what it finds. It picks one of three polite options.

A real file or folder is in the way

~/.config/nvim new signpost ~/.config/nvim.bak.20261115… your old folder

The old one is renamed with a date stamp, then the signpost takes its place. Nothing is lost.

The signpost is already correct

~/.config/nvim unchanged

Setup reports “unchanged” and moves on. Running it twice changes nothing.

~/.ssh holds a private key

~/.ssh left exactly as it is

If ~/.ssh contains an id_… key file, something else manages SSH on this Mac. Setup leaves the whole folder alone.

Move aside, leave unchanged, or keep out. Never delete.

Coming from the older layout

Earlier versions made ~/.config and ~/.ssh signposts to the repository's whole folders, so every app was writing inside the repository. On a Mac set up that way, pull the latest changes and run script/setup once. It moves everything git does not track back out into real folders at the same paths, then links one entry at a time as above.

Four files it never touches

On a managed Mac, another tool owns ~/.profile, ~/.bashrc, ~/.zprofile and ~/.zshrc, and rewrites them from time to time. Setup neither creates nor changes any of the four. They are read as a base layer instead, which Opening a terminal explains.

What git is told to ignore

Linking one entry at a time keeps most apps out of the repository, but not all of them. ~/.config/gh still is the repository's config/gh folder, so anything the GitHub CLI saves there lands inside the repository, including its record of who is logged in. Left alone, git would offer to publish it.

So .gitignore names those files one by one. The list is short, because only an app whose folder is linked can write here.

# what apps write inside a linked folder
config/gh/hosts.yml
config/tmux/plugins
config/zsh/.zcompdump

# ssh/ holds one file of ours, and everything else is turned away
ssh/*
!ssh/config

Good to know

Anything new under config/ shows up in git status, and a test fails until someone decides what it is: tracked, or ignored by a rule of its own. Names that should not appear in a public repository go in .git/info/exclude, which is never shared. A key copied into ssh/ by mistake is ignored, so git add passes over it.

Three files that belong to one Mac

Some settings are different on every machine and must not be shared. Each tracked file has an untracked partner for exactly that.

Private fileAdds toWhat goes in it
~/.gitconfig-userconfig/git/configYour name, email and signing key. Required, and the only file you create by hand.
~/.ssh/config-localssh/configHosts only this Mac knows about. Setup creates it empty. It is read first, so it wins.
~/.zshrc.localconfig/zsh/.zshrcShell tweaks for this Mac only. Optional, and read last, so it has the final word.

Three drawers for everything else

One of the first things the shell does is name three folders. Every tool in this setup is told to use them, which keeps the home folder itself nearly empty.