DEV Community

Jian Yuan Lee
Jian Yuan Lee

Posted on Edited on Originally published at jian.fyi

A Guided Tour of My Dotfiles

jianyuan/dotfiles on GitHub

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
Enter fullscreen mode Exit fullscreen mode

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}" "${@}"
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Defaults

The defaults apply to every link unless a link overrides them:

  • create makes any missing parent directories before creating a symlink.
  • relink replaces 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, fzf for fuzzy finding, ripgrep (rg), fd, tmux and neovim. I use mise to manage runtimes and dev environments, and zoxide as a smarter cd.
  • For Git, the usual git and the GitHub CLI (gh), plus tig for browsing history in the terminal and git-town for managing branches.
  • For containers and VMs, colima runs Docker without Docker Desktop, alongside the docker CLI tools, and utm runs virtual machines.
  • Mac apps installed as casks, including raycast, bitwarden, tailscale-app and nordvpn.
  • 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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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"]
}
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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.

jianyuan/dotfiles on GitHub

Top comments (0)