My development environment using GNU Stow.
Required:
- Homebrew
- GNU Stow
- Git
Auto-installed:
- Oh My Zsh + Powerlevel10k
- 80+ CLI tools (see Brewfile)
- All configurations
# Clone repository
git clone https://github.com/sefatanam/dotfiles ~/.dotfiles
# Run automated setup script
cd ~/.dotfiles && ./setup.sh
# Preview what it would do without changing anything
./setup.sh --dry-runEvery run ends with a manual-steps check β a read-only pass that reports what it
couldn't do on this machine (missing SSH signing keys, an empty ssh-agent, an includeIf
pointing at a directory that doesn't exist yet, ungitignored-but-absent local files). It
runs in --dry-run too. See Manual steps on a new machine.
setup.sh refuses to sync Homebrew packages (the slow, external-reaching step) without an
interactive confirmation β a non-interactive invocation (a script, a copy-pasted pipe, an
agent) skips it rather than silently installing/upgrading packages. Pass --yes to confirm
non-interactively; everything else (stow, git hooks, install.conf links) is idempotent and
guarded against clobbering real files, so it always runs. See ./setup.sh --help.
# Install dependencies
brew bundle --file=~/.dotfiles/brew/Brewfile
# Install Oh My Zsh + Powerlevel10k
sh -c "$(curl -fsSL https://raw.github.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"
git clone --depth=1 https://github.com/romkatv/powerlevel10k.git ${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/themes/powerlevel10k
# Setup dotfiles
cd ~/.dotfiles/stow-packages
stow -t ~ shell editor git
stow -t ~ gitinstallsgit/gitconfigas~/.gitconfigandgit/gitignoreas~/.gitignore_global. If you already have a real~/.gitconfig, back it up and remove it first β stow refuses to overwrite regular files. See git/README.md.
| Package | Links | Notable configs |
|---|---|---|
shell |
~/.zshrc, ~/.zprofile, ~/.p10k.zsh, ~/.tmux.conf, ~/.wezterm.lua, ~/.tuicrignore, ~/.config/* |
alacritty, ghostty, aerospace, workmux, herdr, bat, lazygit, tuicr |
editor |
~/.config/nvim |
Neovim |
git |
~/.gitconfig, ~/.gitignore_global |
git/README.md |
Each ~/.config/<app> entry is a symlink back to a folder of the same name in this repo
root, so editing e.g. tuicr/config.toml takes effect immediately β no restow.
zsh/.local/share/zsh/ splits aliases/functions into three tiers instead of one flat file:
| File | Committed? | For |
|---|---|---|
aliases.zsh / functions.zsh |
Yes | Broadly useful anywhere (tmux, git, npm, media tools, β¦) |
work.zsh |
Yes | Job/project-specific, but nothing secret (assumes a particular project layout) |
local.zsh |
No (gitignored) | Real network addresses, VPN routes, client/company names β anything that shouldn't be public |
local.zsh doesn't exist on a fresh clone; copy the template and fill it in:
cp zsh/.local/share/zsh/local.zsh.example zsh/.local/share/zsh/local.zshMost tools only need a ~/.config/<app> stub added under stow-packages/shell/.config/
(a symlink back to <app>/ at the repo root, same pattern as the existing ones) β stow
handles the rest.
If a tool needs more than that β a link outside the stowed tree, or a command to run after
linking β declare it in <app>/install.conf instead of hand-editing setup.sh. One directive
per line:
PLATFORM darwin # optional; restricts the whole file to one OS
LINK <src> -> <dest> # src is relative to the tool's own directory
POST <shell command> # run with CWD set to the tool's own directory
setup.sh discovers and applies every */install.conf on each run (apply_declared_installs).
lazygit/install.conf, bat/install.conf, providers/install.conf, omp/install.conf, and
claude/install.conf are the real examples β read those before writing a new one. Run ./setup-validate.sh after
adding or editing one; it exercises the LINK/POST/PLATFORM machinery against a throwaway
sandbox $HOME, not your real one.
Everything shares one RosΓ© Pine palette β Ghostty, Neovim, lazygit, tuicr, and git diffs:
| Tool | Where |
|---|---|
| delta (git pager) | git/delta-rose-pine.gitconfig β rose-pine, rose-pine-moon, rose-pine-dawn features, included from git/gitconfig |
| syntax highlighting | bat/themes/*.tmTheme β delta reads these from bat's cache; bat/install.conf runs bat cache --build after every setup.sh, or run it by hand after changing them |
| lazygit | lazygit/config.yml β theme colors plus delta as the pager |
| tuicr (review TUI) | tuicr/themes/*.toml β local themes; tuicr bundles no RosΓ© Pine. The .tmTheme files there symlink into bat/themes/ |
Switch variants by pointing [delta] features in git/gitconfig, --features/--syntax-theme
in lazygit/config.yml, and theme_dark in tuicr/config.toml at rose-pine-moon or
rose-pine-dawn. delta --show-themes and delta --show-syntax-themes preview what is
available.
On macOS lazygit reads
~/Library/Application Support/lazygit, not~/.config; that link is declared inlazygit/install.confand applied bysetup.sh.
# Install/update configs
stow -t ~ shell editor git
# Update after changes
stow -R shell editor git
# Remove configs
stow -D shell editor git- Run
p10k configurefor prompt customization - Add secrets/API keys to
zsh/private(export KEY=valuelines) β a pre-commit hook scrubs its values before every commit and a post-commit hook restores them, so the plaintext never reaches the repo. See git/README.md Β§6. - Configure AeroSpace workspace bindings as needed
- Work through whatever the manual-steps check printed (below)
Stow carries every tracked file, so the git identity setup β git/gitconfig, the
includeIf in it, and git/gitconfig.gitlab β lands automatically. What can't be
carried is anything secret (SSH keys are deliberately never committed) or anything
tied to one machine's paths. setup.sh ends by checking for exactly those and
printing only what's actually missing, so a fully set-up box prints a single β line.
| What it checks | Why it can't be automated | Fix |
|---|---|---|
Every signingkey in git/gitconfig* exists, with its private half |
Private keys must never be committed | Copy from the old machine (mode 600), or ssh-keygen -t ed25519 -f ~/.ssh/<name> and register the .pub with GitHub/GitLab |
~/.ssh/allowed_signers |
Same β contains public keys tied to your identities | One email ssh-ed25519 AAAA... line per signing key |
| ssh-agent has identities loaded | Per-session, per-machine state | ssh-add --apple-use-keychain ~/.ssh/id_ed25519 (once per key) |
Each includeIf "gitdir:β¦" directory exists |
The paths are ~-relative so they port across machines, but the directory itself still has to be there |
Clone your work repos there, or repoint the includeIf in git/gitconfig |
zsh/.local/share/zsh/local.zsh, zsh/private |
Gitignored on purpose (network details, tokens) | Copy from the template / recreate |
The keys matter most: commit.gpgsign = true is global in git/gitconfig, so until the
signing key named there exists on disk, every commit fails with gpg failed to sign the data β not just the GitLab ones.
The includeIf check is the subtle one. A missing key is loud; a missing includeIf
directory is silent β git just falls through to the default identity, and you find out
when a work commit shows up under your personal email. Write those paths ~-relative
(gitdir:~/Documents/repos/β¦, not gitdir:/Users/<name>/β¦) so they don't break on a
machine with a different username. Full SSH-signing background lives in
git/SIGNING.md.
These either aren't touched by setup.sh at all, or need a manual step it can't automate.
For the secret/machine-specific ones it does check and remind you about, see
Manual steps on a new machine.
| Path | What it is | Run it |
|---|---|---|
macos/system-override |
One-shot defaults write tweaks for a fresh Mac (mathiasbynens-style) |
zsh macos/system-override |
zsh-optimize.sh |
Recompiles and cleans the zsh config cache | ./zsh-optimize.sh (after zsh config changes) |
vscode/*.code-profile.json |
VS Code profile exports | VS Code β Profiles β Import Profile |
omp/config.yml |
Snapshot of ~/.omp/agent/config.yml; setup.sh auto-seeds it on a fresh machine but never re-exports it |
after changing omp settings: cp ~/.omp/agent/config.yml omp/config.yml |