From Setup Hell to Dev Heaven: Why You Should Use Dotfiles

I’m not the most careful person when it comes to laptops — or any device, really. At one of my former jobs, I ended up replacing my machine three times (not proud of it 💀). By the third round, I was already sick of going through the whole setup process again. That pain led me to discover something that changed my workflow for good: dotfiles.

In this article, I’ll walk you through what dotfiles are, why they matter, how to version-control them, and how to back up and restore your full dev setup without the pain.

🧠 What Are Dotfiles? Why Version-Control Them?

Dotfiles are hidden configuration files on Unix-based systems (like macOS, Linux, or WSL). They store preferences for tools like your shell, text editor, terminal multiplexer, and more — allowing you to personalize your development environment.

By version-controlling your dotfiles with Git, you keep your setup consistent across machines, save time when setting up a new environment, and can easily track or roll back changes.

🗂️ Common Dotfiles:

• Bash users:

  • .bash_profile: Runs once at login; good for environment variables.
  • .bashrc: Runs on new terminal sessions; good for aliases, functions.

• Zsh users:

  • .zshrc: Main Zsh config file.

• Other useful ones:

  • .vimrc: Vim behavior and appearance
  • .gitconfig: Global Git settings
  • .tmux.conf: Tmux layout and bindings
  • .config/: App configs (e.g., gh, gcloud) — these are usually defaults added during installation

⚠️ Note: Some dotfiles may contain sensitive info (tokens, credentials). Be careful when committing them or consider using tools like chezmoi for secret management.

🍺 Brewfile: Your Dev Toolkit Snapshot

While not technically a dotfile, Brewfile is essential if you use Homebrew — the package manager for macOS (and Linux). And if you're a macOS user, you'll love the Cask project because it lets you install and manage GUI macOS applications directly from the terminal (no more "To install, drag this icon..."). Here's a searchable list of available Cask apps: https://formulae.brew.sh/cask/

You can export all your installed packages with:

brew bundle dump --file=~/.dotfiles/Brewfile --describe --force

This includes:

• brew: CLI tools from Homebrew core

• cask: GUI apps (via Cask)

• mas: Mac App Store apps (via mas CLI)

• tap: External repos

• vscode: VSCode extensions (if installed via Homebrew)

I prefer to exclude VSCode extensions from Brewfile and sync them via GitHub login.

📦 Example: My Public Dotfiles Repo

Want to see a live example? Check out .dotfiles-blog — a public version of my personal dotfiles. It includes:

• .zshrc, .gitconfig

• A Brewfile to restore packages

• Helpful shell aliases

☁️ Backing Up Your Dotfiles (Step-by-Step)

1. Create a .dotfiles directory

mkdir ~/.dotfiles

2. Move your config files into it

mv ~/.zshrc ~/.dotfiles/.zshrc
mv ~/.gitconfig ~/.dotfiles/.gitconfig

3. Create symlinks back to your home directory

ln -s ~/.dotfiles/.zshrc ~/.zshrc
ln -s ~/.dotfiles/.gitconfig ~/.gitconfig

This lets your shell use the configs while keeping them under version control.

4. Add custom Zsh aliases (optional but recommended — I use one to back up my Homebrew packages)

touch ~/.dotfiles/.zsh_aliases

Then edit it:

alias brew_dump="brew bundle dump --describe --file=~/.dotfiles/Brewfile"
alias brew_redump="brew bundle dump --describe --force --file=~/.dotfiles/Brewfile"
alias gac='git commit -am'
alias grevert='git reset --soft HEAD~1'
# add others that you find useful

Add this line to your .zshrc to load them:

source ~/.dotfiles/.zsh_aliases

Then reload your shell

source ~/.zshrc

5. Create a .gitignore file

echo "Brewfile.lock.json" >> ~/.dotfiles/.gitignore

6. Initialize a Git repository

cd ~/.dotfiles
git init
git add .
git commit -m "Initial commit of dotfiles"

7. Push to GitHub

# if you have GitHub CLI installed
gh repo create .dotfiles --private --push --source=.

Or manually:

git remote add origin git@github.com:<your-username>/.dotfiles.git
git branch -M main
git push -u origin main

✅ Done! Your environment is now portable.

🛠️ Restoring on a New Machine

1. Install Xcode CLI tools (this is required for Git, compilers, and many developer tools — macOS users)

xcode-select --install

2. Install Homebrew

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

3. Install Git (Xcode includes Git, but if you skipped it because you are not a macOS user)

brew install git

4. Clone your dotfiles repo

git clone https://github.com/your-username/.dotfiles.git ~/.dotfiles

5. Create symlinks

ln -s ~/.dotfiles/.zshrc ~/.zshrc
ln -s ~/.dotfiles/.gitconfig ~/.gitconfig

6. Install your tools

brew bundle --file=~/.dotfiles/Brewfile

7. Reload your shell

source ~/.zshrc

🧰 Alternatives to Manual Dotfiles Management

You could certainly create a Bash script to automate some of the steps above, or leverage existing tools that make dotfile management easier. While I like to keep my setup simple, here are a few tools worth exploring:

1. Chezmoi – Declarative, encrypted, cross-platform dotfile manager with templating and host-specific configs.

2. Dotbot – Git + YAML-based manager that automates symlinks and setup commands.

3. GNU Stow – Simple, folder-based symlink manager that works like a charm.

4. YADM – Git-based dotfiles manager with built-in secret management and no symlinks needed.

5. rcm – A flexible dotfile manager from Thoughtbot for multiple-host environments.

🎯 Final Thoughts

Whether you're setting up a new machine or tired of configuring everything from scratch every time, dotfiles can save your sanity. Start small — back up your .zshrc and .gitconfig — and build from there. You'll thank yourself the next time your laptop dies unexpectedly 💀

Let me know if you use another tool or have a setup you love!