Dotfiles Management Skill

Overview

The dotfiles automation provides bidirectional sync between local configuration files and a centralized ~/.dotfiles repository. Configuration is managed via dotfiles.json and the dotfiles command.

Structure

Repository: ~/.dotfiles/ (git-tracked)

Key Files:

• dotfiles.json - Configuration mapping (tool → file paths)
• config/ - Organized dotfile storage by tool name
• bin/dotfiles - Ruby automation script (also in ~/bin/dotfiles)

Storage Pattern:

~/.dotfiles/config/{tool_name}/

Examples:

• ~/.dotfiles/config/git/.gitconfig
• ~/.dotfiles/config/zsh/.zshrc
• ~/.dotfiles/config/sublimetext/Preferences.sublime-settings

Configuration Format

File: ~/.dotfiles/dotfiles.json

Structure:

{
  "tool_name": [
    "~/path/to/config_file",
    "~/path/to/directory/*",
    "~/path/to/directory/"
  ]
}

Path Types:

• Single file: ~/.gitconfig
• Directory (recursive): ~/.config/nvim/* or ~/.config/nvim/
• Preserves relative directory structure

Commands

Save (local → dotfiles):

dotfiles save          # Copy local configs to dotfiles repo
dotfiles save -n       # Dry run (show what would be done)
dotfiles save -v       # Verbose output
dotfiles save -p       # Prune removed files from dotfiles

Apply (dotfiles → local):

dotfiles apply          # Apply configs from dotfiles repo to local
dotfiles apply -n       # Dry run
dotfiles apply -v       # Verbose output
dotfiles apply -p       # Prune removed files from local

Status:

dotfiles status        # Show sync status of managed files
# Output: in sync, local changes, dotfile changes, missing, etc.

Config:

dotfiles config        # Show configuration mapping as JSON

Status Indicators

Options

• -n, --dry-run - Preview changes without applying
• -v, --verbose - Show detailed file operations
• -p, --prune - Remove destination files missing from source
• -h, --help - Show help message

Expected Workflows

Save: dotfiles save -v (optionally check dotfiles status first)

Apply: dotfiles apply -v (optionally check dotfiles status first)

Push/Pull: Git operations on ~/.dotfiles repo

• Push (optionally after save): cd ~/.dotfiles && git add . && git commit -m "..." && git push
• Pull (optionally before apply): cd ~/.dotfiles && git pull

Usage Guidelines

• Check dotfiles status when it makes sense before saving/loading
• Use dry-run (-n) for safety when you consider it necessary
• Edit dotfiles.json to add new config files
• Config stored in ~/.dotfiles/config/{tool_name}/
• The ~/.dotfiles repo is git-tracked
• Single source of truth for configuration across machines