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.
Signposts, not copies
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 --globalreads - ~/.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.
The rule behind the map
script/setup walks the top level of the repository and does one of two things with what it finds.
- A file becomes a signpost named
~/.<name>. That is howBrewfilebecomes~/.Brewfile. - A folder, which means
configandssh, becomes a real folder,~/.configor~/.ssh. Inside it goes one signpost for each thing git tracks directly inside the repository's folder.
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
The old one is renamed with a date stamp, then the signpost takes its place. Nothing is lost.
The signpost is already correct
Setup reports “unchanged” and moves on. Running it twice changes nothing.
~/.ssh holds a private key
If ~/.ssh contains an id_… key file, something else manages SSH on this Mac. Setup leaves the whole folder alone.
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 file | Adds to | What goes in it |
|---|---|---|
~/.gitconfig-user | config/git/config | Your name, email and signing key. Required, and the only file you create by hand. |
~/.ssh/config-local | ssh/config | Hosts only this Mac knows about. Setup creates it empty. It is read first, so it wins. |
~/.zshrc.local | config/zsh/.zshrc | Shell 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.
-
~/.config
Settings
Written by a person. The entries this repository owns are signposts into its
config/folder, tracked in git. -
~/.cache
Throwaway
Things the shell worked out once and saved to go faster, such as the completion index. Safe to delete at any time.
-
~/.local/share
Yours
Data worth keeping that is not a setting: shell history, installed plugins, saved tmux sessions.