---

name: dotfiles-manage description: Manage dotfiles using dotter (symlink manager and templater). Use when deploying, adding, removing, or organizing configuration files in ~/dotfiles.

Manage Dotfiles Skill

Manage dotfiles using dotter - a dotfile manager and templater.

Environment

• Dotfiles repo: ~/dotfiles
• Dotter config: ~/dotfiles/.dotter/
  • global.toml: Package definitions (files to deploy)
  • local.toml: Machine-specific package selection
  • cache.toml: Deployment state cache

Core Commands

Copy# Deploy all configured files
dotter deploy

# Preview changes without applying
dotter deploy --dry-run

# Undeploy all managed files
dotter undeploy

# Watch for changes and auto-deploy
dotter watch

Workflow: Add New Dotfile

Step 1: Add Source File

Place the configuration file in ~/dotfiles:

Copy# Example: adding a new config
cp ~/.config/app/config.toml ~/dotfiles/.config/app/config.toml

Step 2: Define in global.toml

Add a new package or extend existing one in ~/dotfiles/.dotter/global.toml:

Copy# New package
[myapp.files]
".config/app/config.toml" = "~/.config/app/config.toml"

# Or extend existing package
[existing-package.files]
".config/app/config.toml" = "~/.config/app/config.toml"

File mapping format: "source" = "target"

• Source: relative path from dotfiles repo root
• Target: absolute path or ~ for home directory

Step 3: Enable Package (if new)

Add package to ~/dotfiles/.dotter/local.toml:

Copypackages = ["doom", "myapp"]

Step 4: Deploy

Copycd ~/dotfiles && dotter deploy

Workflow: Remove Dotfile

1. Undeploy first: dotter undeploy
2. Remove from global.toml: Delete the file mapping
3. Remove package from local.toml (if removing entire package)
4. Redeploy: dotter deploy
5. Clean up source (optional): Remove file from dotfiles repo

Package Organization

Group related files into packages:

Copy# Shell configuration
[shell.files]
".zshrc" = "~/.zshrc"
".zprofile" = "~/.zprofile"
".config/starship.toml" = "~/.config/starship.toml"

# Editor configuration
[nvim.files]
".config/nvim" = "~/.config/nvim"

# Git configuration
[git.files]
".gitconfig" = "~/.gitconfig"
".gitignore_global" = "~/.gitignore_global"

Templating

Dotter supports Handlebars templating for machine-specific values:

Copy# In global.toml - define variables
[package.variables]
email = "default@example.com"

# In local.toml - override per machine
[variables]
email = "work@company.com"

In template files, use \{{email}} syntax.

Troubleshooting

Conflict with existing file:

Copy# Force overwrite (use with caution)
dotter deploy --force

Check deployment status:

Copydotter deploy --dry-run --verbose

View what's currently deployed:

Copycat ~/dotfiles/.dotter/cache.toml

Best Practices

• Keep packages granular and focused
• Use descriptive package names
• Commit changes to dotfiles repo after modifications
• Test with --dry-run before deploying
• Use templating for machine-specific values (email, paths)