1. General Principles: Configuration Is Code, Not Handicraft#

Three rules:

1. All configuration goes into Git. Including shell, editor, terminal, and Git’s own configuration.
2. The installation process is scripted. The first thing to do on a new machine is git clone + ./bootstrap.sh, not trying to recall “what did I install last time.”
3. Platform differences use conditional branches, not multiple copies. The same .zshrc runs on both macOS and Linux, branching via uname.

The directory structure looks roughly like this:

1
~/.dotfiles
2
├── bootstrap.sh          #One-click install entry point
3
├── install/
4
│   ├── brew.sh           #macOS: Homebrew package
5
│   ├── apt.sh            #Linux: apt package
6
│   └── links.sh          #Create symlinks
7
├── shell/
8
│   ├── .zshrc
9
│   └── aliases.zsh
10
├── config/
11
│   ├── starship.toml
12
│   ├── mise/config.toml
13
│   └── nvim/
14
└── git/.gitconfig

For the symlinking step, I recommend GNU Stow. It automatically creates links based on directory structure, which is easier to maintain than hand-writing ln -s:

1
#Link files under shell/ into ~, preserving relative structure
2
stow --target="$HOME" --verbose shell git

If you don’t want to introduce an extra dependency, a shell snippet can get the job done too. The key is idempotency—repeated execution doesn’t cause errors:

1
link() {
2
  local src="$1" dst="$2"
3
  mkdir -p "$(dirname "$dst")"
4
  #-n avoids treating existing symlinks as directories, -f overwrites old links
5
  ln -sfn "$src" "$dst"
6
}
7

8
link "$DOTFILES/shell/.zshrc"  "$HOME/.zshrc"
9
link "$DOTFILES/git/.gitconfig" "$HOME/.gitconfig"

2. Shell: zsh + starship, aliases only for high-frequency commands#

I no longer use Oh My Zsh—slow startup, black-box plugins. Now it’s a minimal .zshrc plus Starship for the prompt.

1
autoload -Uz compinit && compinit -C   #-C skips safety checks, starts twice as fast
2
setopt HIST_IGNORE_ALL_DUPS HIST_VERIFY SHARE_HISTORY
3
setopt AUTO_CD CORRECT
4

5
#History search and fuzzy finding
6
source /opt/homebrew/share/zsh-autosuggestions/zsh-autosuggestions.zsh
7
eval "$(starship init zsh)"
8
eval "$(zoxide init zsh)"
9
eval "$(mise activate zsh)"
10
eval "$(direnv hook zsh)"
11

12
bindkey '^f' fzf-file-widget   #Ctrl+F fuzzy file finder

The advantage of Starship is that the configuration is pure TOML, cross-shell compatible, and it naturally displays the language version, Git branch, and elapsed time for the current directory:

1
add_newline = false
2

3
[cmd_duration]
4
min_time = 500          #Only shows after 500ms to reduce noise
5
show_milliseconds = true
6

7
[git_status]
8
disabled = false
9

10
[nodejs]
11
symbol = " "
12
format = "via [$symbol($version )]($style)"

I only keep aliases for things I actually type every day; the rest rely on completion:

1
alias gs='git status -sb'
2
alias gp='git push'
3
alias ll='eza -lah --git'
4
alias cat='bat --style=plain'
5
alias lg='lazygit'

3. Runtime Versions: mise Manages All Languages with One Tool#

In the past I used nvm for Node, pyenv for Python, and rbenv for Ruby—three sets of logic, three sets of pitfalls. In 2026 the answer has basically converged on mise (formerly rtx), a single tool that manages all language runtimes with a unified configuration format:

1
#~/.config/mise/config.toml — global defaults
2
[tools]
3
node = "22"
4
python = "3.13"
5
go = "1.24"

Then put a .mise.toml in the project, and entering the directory switches automatically—no need to manually nvm use:

1
#project root/.mise.toml
2
[tools]
3
node = "20.19.0"
4
pnpm = "10"
5

6
[env]
7
NODE_ENV = "development"
8

9
[tasks.dev]
10
run = "pnpm dev"
11

12
[tasks.test]
13
depends = ["lint"]
14
run = "pnpm vitest run"

1
mise install     #Install all versions declared in .mise.toml
2
mise ls          #Show the currently active version
3
mise run test    #Run tasks, replacing npm scripts' layer upon layer of forwarding

There’s a tangible benefit here: version declarations go into Git, everyone on the team uses the same Node version, and CI only needs to run mise install to reproduce the local environment. “It works on my machine” is cut down by more than half.

4. Environment Variables: direnv Auto-Loads per Directory#

The biggest problem with .env files is that they’re easy to accidentally commit. direnv’s approach is to automatically inject environment variables per directory, and by default it doesn’t trust any new file—you must manually direnv allow once:

1
#project root/.envrc
2
export DATABASE_URL="postgres://localhost:5432/dev"
3
export API_KEY="dev-only-key"
4

5
#Reuse .env but keep it git-ignored
6
dotenv_if_exists .env
7

8
#Complex logic can be extracted into scripts
9
PATH_add ./bin
10
layout node

Key security point: commit .envrc into the repository, but only put non-sensitive development defaults in it. Real secrets are still read via dotenv_if_exists from the ignored .env. This way, after git clone you don’t need to ask anyone for configuration, and secrets won’t leak.

5. Task Entry Point: just Replaces Scattered Scripts#

Every project has a pile of “how to get it running” knowledge scattered across READMEs, package.json, and colleagues’ heads. just gathers them into a single Justfile:

1
# Justfile
2
set dotenv-load
3

4
default:
5
    @just --list
6

7
dev:
8
    mise run dev
9

10
test *args:
11
    pnpm vitest run {{args}}
12

13
setup:
14
    mise install
15
    pnpm install --frozen-lockfile
16
    cp -n .env.example .env || true
17
    @echo "✅ Environment ready, run just dev"

The onboarding process for a new colleague goes from “dig through docs + ask people” to two commands:

1
git clone git@github.com:team/project.git && cd project
2
just setup && just dev

6. Editor: Configuration Should Also Be Versionable#

For VS Code I use a dual-track approach of Settings Sync + in-repo .vscode/: personal preferences go through Sync, project constraints go into the repo—formatters, recommended extensions, and debug configurations are all committed to Git to ensure team consistency:

1
{
2
  "editor.formatOnSave": true,
3
  "editor.codeActionsOnSave": { "source.fixAll.biome": "explicit" },
4
  "[typescript]": { "editor.defaultFormatter": "biomejs.biome" },
5
  "typescript.tsdk": "node_modules/typescript/lib"
6
}

1
//.vscode/extensions.json — prompt to install when opening the project
2
{
3
  "recommendations": ["biomejs.biome", "vitest.explorer", "streetsidesoftware.code-spell-checker"]
4
}

For Neovim, it’s entirely Lua configuration, following the dotfiles repository:

1
-- ~/.config/nvim/lua/options.lua
2
vim.opt.number = true
3
vim.opt.relativenumber = true      --Relative line numbers, works with 5j / 3k jumps
4
vim.opt.undofile = true            --Still undoable after restart
5
vim.opt.swapfile = false
6
vim.g.mapleader = " "

7. bootstrap.sh: The Single Entry Point for a New Machine#

Everything above ultimately converges into a single script. Its value lies in being idempotent—skip what’s already installed, fill in what isn’t:

1
#!/usr/bin/env bash
2
set -euo pipefail
3

4
DOTFILES="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
5

6
case "$(uname -s)" in
7
  Darwin) brew bundle --file="$DOTFILES/install/Brewfile" ;;
8
  Linux)  sudo apt-get install -y zsh git curl ripgrep fd-find jq tmux ;;
9
esac
10

11
#Link config files
12
while IFS= read -r -d '' f; do
13
  rel="${f#"$DOTFILES"/}"          #Strip the prefix to get the relative path
14
  link "$f" "$HOME/${rel#*/}"      #Strip the first directory level, then link into $HOME
15
done < <(find "$DOTFILES/shell" "$DOTFILES/git" -type f -print0)
16

17
#Install runtimes and global tools
18
mise install
19
curl -sS https://starship.rs/install.sh | sh -s -- --yes
20

21
echo "🎉 Done, restart the shell for it to take effect"

Conclusion#

The return on investment for configuring your environment is often underestimated. Spend a weekend organizing your dotfiles into a repository, and every time you switch machines, add a server, or onboard a new colleague, you’ll be recouping that investment.

If you haven’t started yet, the minimum viable starting point is three things: commit .zshrc and .gitconfig to a private repository, write a link() function that only does symlinking, use .mise.toml to declare project versions. The rest can grow over time.

References#

• GNU Stow manual: https://www.gnu.org/software/stow/manual/stow.html
• mise: https://mise.jdx.dev/
• direnv: https://direnv.net/
• Starship configuration docs: https://starship.rs/config/
• just command runner: https://github.com/casey/just
• Homebrew Bundle: https://docs.brew.sh/Brew-Bundle-and-Brewfile
• VS Code workspace settings: https://code.visualstudio.com/docs/getstarted/settings