Managing Personal Dotfiles with Yadm

This skill manages personal dotfiles using yadm (Yet Another Dotfiles Manager).

Note: For work-specific dotfiles (Spotify GHE), use the managing-work-dotfiles skill with yadm-work commands.

Repository Info

• Remote: Your dotfiles git repository
• Work tree: $HOME
• Yadm repo: ~/.local/share/yadm/repo.git

Getting Current State

Always start by checking the current state:

yadm status          # Show modified/staged files
yadm ls-files        # List all tracked files
yadm diff            # Show unstaged changes

Managed Files Reference

Run yadm ls-files to get the authoritative list. Common categories:

Category	Files
Shell	.config/fish/ (config.fish, aliases, env, functions, keybindings, plugins)
Editor	.vimrc, Library/Application Support/Code/User/ (settings.json, keybindings.json)
Terminal	.tmux.conf, .config/ghostty/config, .config/starship.toml
Git	.gitconfig, .gitignore, .gitmodules
Claude	.claude/skills/ (commit, creating-pull-requests, managing-dotfiles)
Yadm	.config/yadm/ (bootstrap, hooks, README, install-hooks.sh)
Other	.config/bat/config, .config/ruff/pyproject.toml, .duti, .hushlogin, Caddyfile

Core Operations

Pull from Remote

yadm pull

If merge conflicts occur:

1. Run yadm status to see conflicted files
2. Edit files to resolve conflicts (remove conflict markers)
3. Stage resolved files: yadm add <file>
4. Complete the merge: yadm commit

Commit and Push Changes

yadm add <file>           # Stage specific file
yadm add -u               # Stage all modified tracked files
yadm commit -m "message"  # Commit with message
yadm push                 # Push to remote

Commit conventions (from commit skill):

• No AI/Claude attribution
• No Co-Authored-By headers

Modify Configuration Files

When asked to modify a config (e.g., "update tmux to do X"):

1. Find the relevant file: yadm ls-files | grep -i tmux
2. Read and understand the current config
3. Make the requested changes
4. Stage, commit, and push:

   yadm add <modified-file>
   yadm commit -m "Update <config> to <what was changed>"
   yadm push
   

Adding/Removing Files

Add a new file to tracking

yadm add <new-file>
yadm commit -m "Add <file> to dotfiles"
yadm push

Stop tracking a file (without deleting it)

yadm rm --cached <file>
yadm commit -m "Stop tracking <file>"
yadm push

Pre-commit Hooks

Pre-commit is configured via ~/.pre-commit-config.yaml. Hooks check for:

• Private keys and secrets
• Large files (>500KB)
• Trailing whitespace
• Merge conflicts

Run manually:

yadm enter pre-commit run --all-files

If a commit fails due to pre-commit fixes, stage the fixes and retry.

Self-Management

This skill is itself tracked by yadm at ~/.claude/skills/managing-dotfiles/.

When updating this skill:

1. Make changes to the skill files
2. Commit with yadm:

   yadm add ~/.claude/skills/managing-dotfiles/
   yadm commit -m "Update managing-dotfiles skill"
   yadm push
   

When files are added/removed from yadm tracking, update the "Managed Files Reference" section above if the categories change significantly.

Useful Commands

See yadm-command-reference.md for a quick reference of common yadm commands.

Bootstrap (New System Setup)

On a new system after cloning:

yadm bootstrap

This runs ~/.config/yadm/bootstrap which installs Homebrew, uv, vim-plug, and other dependencies.