dotfiles-manage

Overview

Set up dotfiles management — version control for your configuration files (shell config, editor config, git config, etc.) with the ability to deploy them to any new machine in one command.

When to Use

• The user wants their config files versioned and backed up.
• The user is setting up a new machine and wants their configs deployed automatically.
• The user wants to sync configs across multiple machines.
• The user says "set up dotfiles", "version my configs", or "I want my settings on my new laptop".

Strategies

Four approaches, ranked by simplicity:

Strategy 1: Git Bare Repo (simplest)

No extra software needed — just git.

Setup

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

# Add an alias to your shell config
echo "alias config='/usr/bin/git --git-dir=\$HOME/.cfg/ --work-tree=\$HOME'" >> ~/.bashrc
source ~/.bashrc

# Ignore untracked files in your home dir
config config --local status.showUntrackedFiles no

Add files

config add .bashrc .vimrc .gitconfig .tmux.conf
config commit -m "Initial dotfiles"
config remote add origin git@github.com:youruser/dotfiles.git
config push -u origin main

Deploy on a new machine

# Clone as bare repo
git clone --bare git@github.com:youruser/dotfiles.git $HOME/.cfg

# Add the alias
echo "alias config='/usr/bin/git --git-dir=\$HOME/.cfg/ --work-tree=\$HOME'" >> ~/.bashrc
source ~/.bashrc

# Checkout the files
config checkout

# If it fails because files already exist, back them up first:
mkdir -p .config-backup
config checkout 2>&1 | grep "\t" | awk {'print $1'} | xargs -I{} mv {} .config-backup/{}
config checkout

# Set ignore
config config --local status.showUntrackedFiles no

Strategy 2: GNU Stow

Organizes dotfiles into "packages" and symlinks them into your home directory.

Setup

# Install stow
# Linux: apt install stow / pacman -S stow
# macOS: brew install stow

# Create a dotfiles directory
mkdir ~/dotfiles
cd ~/dotfiles

# Organize by package (each package is a directory)
mkdir -p bash vim git tmux

# Move configs into the package directories
mv ~/.bashrc ~/dotfiles/bash/.bashrc
mv ~/.vimrc ~/dotfiles/vim/.vimrc
mv ~/.gitconfig ~/dotfiles/git/.gitconfig

# Stow (create symlinks)
stow bash vim git

# Verify
ls -la ~/.bashrc  # → ~/dotfiles/bash/.bashrc

Deploy on a new machine

git clone git@github.com:youruser/dotfiles.git ~/dotfiles
cd ~/dotfiles
stow bash vim git tmux

Remove a package

stow -D vim  # removes the symlinks for the vim package

Strategy 3: chezmoi (for multiple machines with differences)

chezmoi handles machine-specific values, templating, and secrets.

Setup

# Install
# Linux: snap install chezmoi --classic / or download
# macOS: brew install chezmoi

# Initialize
chezmoi init

# Add a file
chezmoi add ~/.bashrc
chezmoi add ~/.gitconfig

# Edit managed files
chezmoi edit ~/.bashrc

# Apply changes to your home dir
chezmoi apply

# Push to git
chezmoi cd
git add -A
git commit -m "Initial dotfiles"
git remote add origin git@github.com:youruser/dotfiles.git
git push -u origin main

Deploy on a new machine

chezmoi init git@github.com:youruser/dotfiles.git
chezmoi apply

Machine-specific values

# Template file (chezmoi edit ~/.gitconfig)
[user]
    name = {{ .name }}
    email = {{ .email }}

# Set values per machine
chezmoi data --format json  # see current values
# Edit config:
chezmoi edit-config
# Add:
# data:
#   name: "Your Name"
#   email: "your@email.com"

Managing Different OSes

For configs that differ between Linux and macOS:

chezmoi:

# OS-specific files are named with .linux_ or .darwin_ prefix
# chezmoi automatically picks the right one

Git bare repo / Stow:

# Use conditionals in your shell config:
if [ "$(uname)" = "Darwin" ]; then
    # macOS-specific settings
elif [ "$(uname)" = "Linux" ]; then
    # Linux-specific settings
fi

Secrets in Dotfiles

Never commit plaintext secrets (API keys, tokens, passwords).

# Example: load API key from password manager in .bashrc
export OPENAI_API_KEY=$(pass openai/api-key)

Common Pitfalls

1. Committing secrets — Before pushing, check for API keys, tokens, and passwords in your dotfiles. Use git log -p to review history. If secrets are already pushed, rotate them immediately — git history is forever.
2. Symlink loops with Stow — If you stow a directory that contains a symlink pointing back to your home dir, you'll create a loop. Stow will warn you, but check manually.
3. Bare repo checkout fails — If files already exist in your home dir, config checkout fails. Back up the conflicting files first (the deploy script above handles this).
4. Different paths on different OSes — A config that works on Linux (~/.config/) may need a different path on macOS (~/Library/Application Support/). Use chezmoi for cross-OS setups, or conditional logic in shell configs.
5. Forgetting to stow/restow — After adding a new file to a Stow package, you need to re-run stow <package> to create the symlink. It's not automatic.
6. Machine-specific values in git — If you hardcode a machine-specific value (hostname, IP, path) in a dotfile, it breaks on other machines. Use templates (chezmoi) or conditionals.

Verification Checklist

• config status / git -C ~/dotfiles status (or stow -n/chezmoi diff) shows no unexpected changes after setup
• A clean-machine deploy (fresh clone + checkout/stow/chezmoi apply) reproduces the expected files or symlinks
• git log -p reviewed for accidentally committed secrets before the first push
• status.showUntrackedFiles is set to no for the bare-repo approach so git status/config status in $HOME stays quiet