Over the years I've trimmed my development environment down to something small and reproducible that I can set up on any machine in a few minutes. When I get a new machine, I don't spend hours installing apps by hand or copying terminal configs across. I clone one repository, run ./install and wait.
This post walks through how it works. The main tools are Dotbot, Homebrew Bundle and Git Town.
The directory structure
My dotfiles live in a GitHub repository, jianyuan/dotfiles, laid out like this:
dotfiles/
├── Brewfile
├── gitconfig
├── gitconfig_global
├── install
├── install.conf.yaml
├── renovate.json
└── direnv/
└── direnv.toml
The Brewfile installs apps, command-line tools and fonts. The install script and install.conf.yaml run Dotbot, which symlinks the configs into place. The rest are config files for Git and direnv.
1. Symlinking with Dotbot
A hand-written bash script for symlinking files into my home directory breaks easily, so I use Dotbot, which does the job from a short YAML file.
The install script
The install script pulls in Dotbot as a Git submodule, initialises it and runs it with my config file:
#!/usr/bin/env bash
set -euo pipefail
CONFIG="install.conf.yaml"
DOTBOT_DIR="dotbot"
DOTBOT_BIN="bin/dotbot"
BASEDIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
cd "${BASEDIR}"
git -C "${DOTBOT_DIR}" submodule sync --quiet --recursive
git submodule update --init --recursive "${DOTBOT_DIR}"
"${BASEDIR}/${DOTBOT_DIR}/${DOTBOT_BIN}" -d "${BASEDIR}" -c "${CONFIG}" "${@}"
The config: install.conf.yaml
This file tells Dotbot what to do. It sets defaults for links, creates the symlinks, removes dead links, makes sure my projects directory exists and then installs my packages:
- defaults:
link:
create: true
relink: true
- link:
~/.gitconfig:
~/.gitignore_global:
~/.config/direnv: direnv
- clean: ['~']
- create:
- ~/code
- shell:
- command: brew bundle install
stdout: true
Defaults
The defaults apply to every link unless a link overrides them:
-
createmakes any missing parent directories before creating a symlink. -
relinkreplaces an existing symlink with the same name, so reruns don't fail on conflicts.
Link
The link section lists the files and directories in the repository that get symlinked into my home directory. Each entry maps a target path in my home directory to a source in the repository.
Clean
clean removes dead symlinks, the ones pointing at files that no longer exist. I point it at my home directory (~), so anything I've deleted from the repository doesn't leave a broken link behind.
Create
create makes directories that don't exist yet. I use it for ~/code, so my projects always live in the same place.
Shell
The shell section runs commands after the linking and cleanup are done. The stdout option controls whether I see a command's output. Here it runs brew bundle install, which installs everything in my Brewfile.
2. Packages with Homebrew (Brewfile)
A Brewfile replaces a long list of brew install commands. brew bundle install reads it and installs everything, from command-line tools to GUI apps and fonts.
Here's what's in mine:
- For the terminal,
fzffor fuzzy finding,ripgrep(rg),fd,tmuxandneovim. I usemiseto manage runtimes and dev environments, andzoxideas a smartercd. - For Git, the usual
gitand the GitHub CLI (gh), plustigfor browsing history in the terminal andgit-townfor managing branches. - For containers and VMs,
colimaruns Docker without Docker Desktop, alongside thedockerCLI tools, andutmruns virtual machines. - Mac apps installed as casks, including
raycast,bitwarden,tailscale-appandnordvpn. - Cascadia Code Nerd Font (
font-cascadia-code-nf), which has programming ligatures and the Nerd Font icons.
3. Git
My .gitconfig signs commits, rebases on pull, sets up the remote branch on the first push and uses gh for GitHub authentication. It also has a set of aliases for Git Town.
[user]
name = Your Name
email = your-email@example.com
[core]
excludesfile = ~/.gitignore_global
[commit]
gpgsign = true
[pull]
rebase = true
[push]
autoSetupRemote = true
[credential "https://github.com"]
helper =
helper = !/opt/homebrew/bin/gh auth git-credential
Git Town
Git Town automates the branch housekeeping in a Git workflow: creating feature branches, stacking changes and keeping branches in sync with the main branch. I alias its commands so I can type git sync instead of git town sync:
[alias]
append = town append
compress = town compress
contribute = town contribute
hack = town hack
sync = town sync
ship = town ship
# ... shortcuts for prepend, propose, rename, and observe
[git-town]
sync-feature-strategy = rebase
A .gitignore_global keeps the usual junk out of every repository: compiled objects (.o, .so), packages, local SQLite files, .DS_Store, and .env and .envrc files, so I can't stage secrets by accident.
4. Per-project environments with direnv
direnv hooks into the shell and loads or unloads environment variables as you change directories.
I change one setting in direnv/direnv.toml:
[global]
load_dotenv = true
With load_dotenv = true, when I cd into a project with a .env file, direnv exports its values into my shell, so I don't have to source it myself.
Keeping it up to date
Dotfiles go stale. Tools update and schemas change, and things break. To keep up, I added a renovate.json:
{
"$schema": "https://docs.renovatebot.com/renovate-schema.json",
"extends": ["config:recommended"]
}
With Renovate turned on for the repository, I get a pull request whenever a dependency or config schema has an update, and I barely have to think about it.
Setting up a new machine
When I wipe my Mac or get a new one, setup is two steps:
# Step 1: Clone the environment
git clone https://github.com/jianyuan/dotfiles.git ~/dotfiles
# Step 2: Install everything
cd ~/dotfiles
./install
A few minutes later, Dotbot has linked my configs, Homebrew has installed my apps and tools, and my terminal is ready to use.
The full configs are at jianyuan/dotfiles if you want to fork the repository or borrow a few pieces.
Top comments (0)