Dotfiles Management: Version Your Developer Configurations

In this tutorial, you'll learn to manage dotfiles with Git including bare repos, symlinks, dotfile managers like GNU Stow, and sharing configurations across multiple machines securely.

Why Dotfiles Management Matters

Your shell config, editor settings, git aliases, and terminal themes represent hundreds of hours of tuning. Losing them when a machine dies or rebuilding from scratch on a new laptop wastes days. Dotfiles management means your entire development environment lives in a Git Repository, ready to deploy anywhere in minutes.

By the end of this guide, you will have a version-controlled dotfiles Repository, a deployment Strategy, and a system for handling secrets and machine-specific settings.

What are Dotfiles?

Dotfiles are configuration files beginning with a dot (.) in Unix systems. Examples include .zshrc, .vimrc, .tmux.conf, .gitconfig, and application configs stored in ~/.config/.

flowchart TD
  A[Dotfiles Git Repo] --> B[Install Script]
  B --> C[Symlinks Created]
  C --> D[~/.zshrc -> repo/.zshrc]
  C --> E[~/.config/nvim/ -> repo/nvim/]
  C --> F[~/.tmux.conf -> repo/.tmux.conf]
  A --> G[Bootstrap Script]
  G --> H[Install Packages]
  G --> I[Install Plugins]
  G --> J[Set Defaults]

Method 1: Bare Git Repo

The simplest approach uses a bare Git Repository directly in your home directory.

# Create a bare repo
git init --bare $HOME/.dotfiles

# Create an alias for easy commands
alias dotfiles='git --git-dir=$HOME/.dotfiles/ --work-tree=$HOME'

# Add files
dotfiles add ~/.zshrc
dotfiles add ~/.config/nvim/init.lua
dotfiles add ~/.tmux.conf

# Commit and push
dotfiles commit -m "Initial dotfiles"
dotfiles remote add origin git@github.com:username/dotfiles.git
dotfiles push -u origin main

Cloning to a New Machine

# Clone the bare repo
git clone --bare git@github.com:username/dotfiles.git $HOME/.dotfiles

# Create the alias
alias dotfiles='git --git-dir=$HOME/.dotfiles/ --work-tree=$HOME'

# Checkout files
dotfiles checkout

# If there are conflicts, back up existing files
mkdir -p .dotfiles-backup
dotfiles checkout 2>&1 | grep -E "^\s+." | awk '{print $1}' | xargs -I{} sh -c 'mkdir -p .dotfiles-backup/$(dirname {}) && mv {} .dotfiles-backup/{}'
dotfiles checkout

Expected Output

$ dotfiles status
On branch main
nothing to commit, working tree clean

$ dotfiles log --oneline -3
a1b2c3d Add nvim telescope plugin config
d4e5f6f Update zsh aliases
g7h8i9j Initial commit

Method 2: GNU Stow

GNU Stow is a symlink farm manager. It creates symlinks from a dotfiles directory to your home directory.

# Install stow
sudo apt install stow -y    # Linux
brew install stow           # macOS

# Create dotfiles directory structure
mkdir -p ~/dotfiles/zsh
mkdir -p ~/dotfiles/nvim/.config/nvim
mkdir -p ~/dotfiles/tmux

# Place configs
mv ~/.zshrc ~/dotfiles/zsh/
mv ~/.config/nvim/init.lua ~/dotfiles/nvim/.config/nvim/
mv ~/.tmux.conf ~/dotfiles/tmux/

# Create symlinks with stow
cd ~/dotfiles
stow zsh
stow nvim
stow tmux

Expected Result

~/dotfiles/
├── zsh/
│   └── .zshrc          # Actual file
├── nvim/
│   └── .config/
│       └── nvim/
│           └── init.lua # Actual file
└── tmux/
    └── .tmux.conf      # Actual file

~/.zshrc -> ~/dotfiles/zsh/.zshrc          # Symlink
~/.config/nvim/init.lua -> ~/dotfiles/nvim/.config/nvim/init.lua  # Symlink
~/.tmux.conf -> ~/dotfiles/tmux/.tmux.conf # Symlink

Method 3: Dotfile Managers

chezmoi

# Install chezmoi
sh -c "$(curl -fsLS get.chezmoi.io)"

# Initialize
chezmoi init

# Add files
chezmoi add ~/.zshrc
chezmoi add ~/.config/nvim/init.lua

# Edit a managed file
chezmoi edit ~/.zshrc

# Apply changes
chezmoi apply

# Push to remote
chezmoi cd
git remote add origin git@github.com:username/dotfiles.git
git push -u origin main

Handling Secrets

Never commit secrets to a public dotfiles Repository. Use these strategies:

Strategy 1: Environment Files

# ~/.zshrc sources a local file
if [ -f "$HOME/.env.local" ]; then
  source "$HOME/.env.local"
fi

# ~/.env.local (not tracked by Git)
export GITHUB_TOKEN="ghp_abc123"
export AWS_ACCESS_KEY_ID="AKIA..."
unset HISTORY  # Prevent tokens from being logged

Strategy 2: Git Template Files

Commit a template, never the real config:

# ~/dotfiles/git/.gitconfig.template
[user]
  name = Your Name
  email = your.email@example.com

Create a script that renames the template on new machines:

#!/bin/bash
# ~/dotfiles/scripts/setup-git.sh
cp ~/.gitconfig.template ~/.gitconfig
echo "Enter your Git email:"
read email
sed -i "s/your.email@example.com/$email/" ~/.gitconfig

Bootstrap Script

A Bootstrap script automates the entire setup on a new machine:

#!/bin/bash
# ~/dotfiles/bootstrap.sh

echo "Installing dotfiles..."

# Clone dotfiles if not present
if [ ! -d "$HOME/dotfiles" ]; then
  git clone https://github.com/username/dotfiles.git ~/dotfiles
fi

# Install packages
if [[ "$OSTYPE" == "linux-gnu"* ]]; then
  sudo apt update && sudo apt install -y zsh tmux neovim stow
elif [[ "$OSTYPE" == "darwin"* ]]; then
  brew install zsh tmux neovim stow
fi

# Create symlinks with stow
cd ~/dotfiles
for dir in */; do
  stow "$dir"
done

# Install vim/neovim plugins
nvim --headless +"Lazy sync" +qa

echo "Done! Restart your terminal."

Organization Tips

Common Errors

Practice Questions

1. What is a bare Git Repository?

A Git Repository without a working tree. It stores only the .git directory metadata.

2. How does GNU Stow work?

It creates symlinks from a dotfiles directory to the home directory, mirroring the directory structure.

3. What is the purpose of a Bootstrap script in dotfiles management?

It automates the setup of a new machine: cloning the repo, installing packages, and creating symlinks.

4. How should you handle API keys in dotfiles?

Use a separate .env.local file that is excluded from version control and sourced by the main config.

5. What is the advantage of chezmoi over a simple Git repo?

chezmoi provides file-by-file management, template rendering, and per-machine configuration handling.

Challenge

Create a dotfiles Repository using GNU Stow that manages at least four configurations: Zsh, Neovim, Tmux, and Git. Write a Bootstrap script that installs dependencies and deploys the config on a fresh Ubuntu installation.

Real-World Task

Migrate your current development environment to a version-controlled dotfiles Repository. Start by tracking .zshrc, .tmux.conf, and your editor config. Push to a private Git Repository. Then clone and deploy on a second machine (or a virtual machine) using the Bootstrap script. Verify that all tools work identically.

Built by the developers of Doda Browser, DodaZIP, and Durga Antivirus Pro.