Introduction

Dotfiles — configuration files for your shell, editor, git, and other tools — are the backbone of your development environment. Properly managing them ensures consistency across machines, easy recovery after a crash, and collaboration with your team. This article compares the three main approaches: chezmoi, GNU Stow, and bare git repositories.

Bare Git Repo

The simplest approach: use git directly without any additional tool:

Initialize a bare repository in your home directory

git init --bare $HOME/.dotfiles

Create an alias to manage it

alias dotfiles='/usr/bin/git --git-dir=$HOME/.dotfiles --work-tree=$HOME'

Add the alias to your shell config

echo "alias dotfiles='/usr/bin/git --git-dir=$HOME/.dotfiles --work-tree=$HOME'" >> ~/.zshrc

Start tracking files

dotfiles status

dotfiles add ~/.zshrc ~/.gitconfig ~/.tmux.conf

dotfiles commit -m "Initial dotfiles"

dotfiles remote add origin git@github.com:user/dotfiles.git

dotfiles push -u origin main

On a new machine:

git clone --bare https://github.com/user/dotfiles.git $HOME/.dotfiles

alias dotfiles='/usr/bin/git --git-dir=$HOME/.dotfiles --work-tree=$HOME'

dotfiles checkout

Pros : No external dependencies, just git. Simple to understand.

Cons : No templating (machine-specific configs require symlink hacks). Lacks encryption for secrets. Easy to accidentally commit sensitive data.

GNU Stow

Stow creates symlinks from a structured directory to your home directory:

Directory structure

~/dotfiles/

zsh/

.zshrc

.zprofile

git/

.gitconfig

.gitignore_global

tmux/

.tmux.conf

nvim/

.config/nvim/

init.lua

Install all packages

stow -t $HOME zsh git tmux nvim

Stow creates symlinks:

~/dotfiles/zsh/.zshrc -> ~/.zshrc

~/dotfiles/git/.gitconfig -> ~/.gitconfig

Uninstall a package

stow -D -t $HOME zsh

Restow (update symlinks after changes)

stow -R -t $HOME nvim

Pros : Clean directory structure. Easy to understand. Works on any Unix system.

Cons : No templating. No encryption. Conflicts if files overlap. Root privileges needed for system configs.

chezmoi

chezmoi is purpose-built for dotfile management with advanced features:

Install chezmoi

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

Initialize

chezmoi init

Add a file

chezmoi add ~/.zshrc

chezmoi add ~/.config/nvim/init.lua

Edit a tracked file

chezmoi edit ~/.zshrc

See what would change

chezmoi diff

Apply changes

chezmoi apply

On a new machine

chezmoi init https://github.com/user/dotfiles.git

chezmoi apply

Templating with chezmoi

chezmoi supports Go templates for machine-specific configs:

.zshrc.tmpl — template file

export EDITOR='{{ if eq .chezmoi.os "darwin" }}code{{ else }}nvim{{ end }}'

export WORK_MODE=true

export AWS_PROFILE=work

Template data includes: OS, hostname, architecture, username, and custom variables

Secret Management

Store secrets in your password manager

chezmoi secret set github_token

chezmoi secret set ssh_private_key

Use in templates

Or use encrypted files with age/gpg

chezmoi age encrypt ~/.ssh/id_ed25519 > ~/.local/share/chezmoi/encrypted_dot_ssh/id_ed25519.age

Comparison

|---------|----------|----------|---------|

| Templating | No | No | Full Go templates |

| Learning curve | Low | Low | Medium |

| Cross-platform | Yes | Unix only | Yes |

Recommendations

Single machine, no secrets : Bare git repo is the simplest approach.
Multiple Unix machines : GNU Stow provides clean structure with minimal dependencies.
Multiple machines with different configs : chezmei's templating handles this elegantly.
Need secret management : chezmoi's built-in encryption and password manager integration is essential.
Team dotfiles : chezmoi's robust apply/diff workflow supports collaboration safely.

Choose chezmoi if you have more than two machines or need secret management. Choose bare git for simplicity on single-machine setups. Choose Stow if you prefer Unix philosophy and have mostly identical machines.

Dotfile Management: chezmoi, GNU Stow, Bare Git Repos