dotfiles

How to Backup and Restore Dotfiles Settings

This guide shows you how to backup your dotfiles and restore them on a new machine. Use this when migrating to a new computer or creating backups of your configuration.

Before you begin

Ensure you have:

• Git installed on both machines
• Access to a Git remote (GitHub, GitLab, etc.)
• GNU Stow installed (for restoration)

Backup Solution

Option 1: Full Repository Backup

Use this for complete configuration backup including history.

1. Ensure all changes are committed:

   cd ~/.dotfiles
   git status
   git add -A
   git commit -m "backup: configuration snapshot $(date +%Y-%m-%d)"
   

2. Push to remote repository:

   git push origin main
   

3. Create a backup tag:

   git tag -a "backup-$(date +%Y-%m-%d)" -m "Configuration backup"
   git push origin --tags
   

Option 2: Selective Backup

Use this when you only want specific configurations.

1. Create a backup branch:

   git checkout -b backup/machine-name-$(date +%Y%m%d)
   

2. Remove unwanted configurations:

   # Example: exclude work-specific configs
   rm -rf work/
   git add -A
   git commit -m "backup: filtered configuration"
   

3. Push the backup branch:

   git push origin backup/machine-name-$(date +%Y%m%d)
   

Option 3: Archive Backup

Use this for offline backups without Git history.

1. Create an archive:

   cd ~
   tar -czf dotfiles-backup-$(date +%Y%m%d).tar.gz \
       --exclude='.git' \
       --exclude='*.zwc' \
       --exclude='.DS_Store' \
       .dotfiles/
   

2. Include important non-dotfile configs:

   tar -czf complete-backup-$(date +%Y%m%d).tar.gz \
       .dotfiles/ \
       .ssh/config \
       .gnupg/pubring.kbx \
       .gnupg/trustdb.gpg
   

Restore Solution

Option 1: Full Git + Stow Setup (Recommended)

1. Install prerequisites:

   # On macOS
   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   brew install git stow
   

2. Clone your dotfiles:

   git clone https://github.com/yourusername/dotfiles.git ~/.dotfiles
   cd ~/.dotfiles
   

Option 2: Rsync Fallback (No Git/Stow Available)

When git or stow aren’t available on the target system:

1. From another machine with access:

   # Copy dotfiles to remote system
   rsync -avz ~/.dotfiles/ user@remote-host:~/dotfiles-backup/
      
   # On remote system, manually copy needed files
   cp ~/dotfiles-backup/zsh/.zshrc ~/.zshrc
   cp ~/dotfiles-backup/git/.gitconfig ~/.gitconfig
   

2. Using archive method:

   # Create archive on source machine
   tar -czf dotfiles-essential.tar.gz \
       .dotfiles/zsh/.zshrc \
       .dotfiles/git/.gitconfig \
       .dotfiles/vim/.vimrc
      
   # Transfer and extract on target
   scp dotfiles-essential.tar.gz user@remote-host:
   ssh user@remote-host 'tar -xzf dotfiles-essential.tar.gz'
   

Option 3: Manual Sync for Essential Files

For quick setup of essential configurations on remote systems:

1. Copy core shell configuration:

   # Essential files for basic functionality
   scp ~/.zshrc user@remote-host:~/.zshrc
   scp ~/.gitconfig user@remote-host:~/.gitconfig
   

2. Bootstrap znap on remote system:

   # On remote system, znap will auto-install when .zshrc is sourced
   ssh user@remote-host
   zsh  # Will trigger znap installation and plugin setup
   

Note: The znap plugin manager will automatically clone and set up plugins when the shell configuration is first loaded, making remote setup straightforward.

1. Checkout specific backup (if needed):

   # List available backups
   git tag -l "backup-*"
   git branch -r | grep backup/
      
   # Restore specific backup
   git checkout backup-2024-01-15
   

Step 2: Restore Configurations

1. Check for conflicts:

   # Dry run to see what would happen
   stow -n -v git zsh vim
   

2. Backup existing configs:

   # Create backup directory
   mkdir ~/config-backup-$(date +%Y%m%d)
      
   # Move existing files
   [[ -f ~/.gitconfig ]] && mv ~/.gitconfig ~/config-backup-*/
   [[ -f ~/.zshrc ]] && mv ~/.zshrc ~/config-backup-*/
   

3. Apply configurations:

   # Apply all configs
   stow git zsh vim homebrew
      
   # Or selectively
   stow git  # Just git configs
   stow zsh  # Just shell configs
   

Step 3: Restore Dependencies

1. Install Homebrew packages:

   brew bundle --file=~/.config/homebrew/Brewfile
   

2. Install shell plugins:

   # Znap (if using zsh config)
   git clone --depth 1 https://github.com/marlonrichert/zsh-snap.git ~/znap/zsh-snap
      
   # Restart shell
   exec zsh
   

3. Restore GPG keys (if backed up):

   gpg --import ~/config-backup-*/gpg-private-keys.asc
   gpg --import-ownertrust ~/config-backup-*/gpg-ownertrust.txt
   

Verify Your Restoration

Check that configurations are properly restored:

# Verify symlinks
ls -la ~ | grep "\->"

# Test git aliases
git st  # Should work if aliases restored

# Check shell configuration
echo $SHELL
echo $ZDOTDIR

# Verify Git identity
git config user.name
git config user.email

Automated Backup Script

Create ~/.dotfiles/scripts/backup.sh:

#!/usr/bin/env bash

set -euo pipefail

BACKUP_DATE=$(date +%Y-%m-%d)
DOTFILES_DIR="$HOME/.dotfiles"

# Function to backup dotfiles
backup_dotfiles() {
    cd "$DOTFILES_DIR"
    
    # Check for uncommitted changes
    if [[ -n $(git status -s) ]]; then
        echo "📦 Committing current changes..."
        git add -A
        git commit -m "backup: auto-backup $BACKUP_DATE"
    fi
    
    # Push to remote
    echo "📤 Pushing to remote..."
    git push origin main
    
    # Create backup tag
    echo "🏷️  Creating backup tag..."
    git tag -a "backup-$BACKUP_DATE" -m "Automated backup"
    git push origin --tags
    
    echo "✅ Backup complete!"
}

# Run backup
backup_dotfiles

Make it executable:

chmod +x ~/.dotfiles/scripts/backup.sh

Add to crontab for daily backups:

# Edit crontab
crontab -e

# Add daily backup at 10 PM
0 22 * * * ~/.dotfiles/scripts/backup.sh >> ~/.dotfiles/backup.log 2>&1

Troubleshooting

Problem: Stow conflicts during restore
Solution:

• Use --adopt to adopt existing files: stow --adopt git
• Or backup and remove existing files first

Problem: Missing dependencies after restore
Solution:

• Run brew bundle to install from Brewfile
• Check for system-specific dependencies

Problem: Git push fails with authentication error
Solution:

• Set up SSH keys: ssh-keygen -t ed25519
• Add to GitHub/GitLab
• Use SSH URL: git remote set-url origin git@github.com:user/dotfiles.git

Problem: Restored shell doesn’t work properly
Solution:

• Install shell first: brew install zsh
• Set as default: chsh -s $(which zsh)
• Restart terminal

Best Practices

1. Regular backups: Automate with cron or launchd
2. Test restores: Periodically test on a VM
3. Document dependencies: Keep a list of required tools
4. Exclude secrets: Never backup private keys in the repo
5. Version control: Tag important configurations

Related Tasks

• Manage multiple machines
• Create installation script
• Setup automated sync

This site is open source. Improve this page.