managing-dotfiles

majiayu000's avatarfrom majiayu000

Use this skill when working with dotfiles managed by yadm. This includes pulling remote changes, committing and pushing dotfile changes, modifying configuration files (shell, editor, terminal, git, etc.), viewing tracked files, resolving merge conflicts, and maintaining the dotfiles repository.

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 5, 2026
[Developer Tools]

When & Why to Use This Skill

This Claude skill provides a comprehensive interface for managing system dotfiles using yadm (Yet Another Dotfiles Manager). It streamlines the process of version-controlling, synchronizing, and deploying configuration files for shells, editors, and terminal emulators across multiple environments. By leveraging Git-based workflows, it ensures developer environment consistency, simplifies system bootstrapping, and automates the maintenance of personalized configurations with built-in support for conflict resolution and pre-commit security checks.

Use Cases

  • Case 1: Synchronizing development environments (shell aliases, editor settings, and UI themes) across multiple Linux or macOS workstations to ensure a consistent workflow.
  • Case 2: Automating the setup of a fresh operating system installation using the 'yadm bootstrap' command to install essential packages and restore personal configurations.
  • Case 3: Managing complex configuration updates for tools like Tmux, Vim, or VS Code by tracking changes, committing updates, and pushing them to a remote Git repository.
  • Case 4: Resolving configuration merge conflicts that arise when different machines have divergent local settings, ensuring a clean and functional state.
  • Case 5: Implementing security best practices for dotfiles by using pre-commit hooks to prevent accidental leakage of private keys or secrets into public repositories.
namemanaging-dotfiles
descriptionUse this skill when working with dotfiles managed by yadm. This includes pulling remote changes, committing and pushing dotfile changes, modifying configuration files (shell, editor, terminal, git, etc.), viewing tracked files, resolving merge conflicts, and maintaining the dotfiles repository.

Managing Dotfiles with Yadm

This skill helps manage dotfiles using yadm (Yet Another Dotfiles Manager).

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.