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

# 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

:

# 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

:

# 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

:

packages = ["doom", "myapp"]

Step 4: Deploy

cd ~/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:

# 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:

# 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:

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

Check deployment status:

dotter deploy --dry-run --verbose

View what's currently deployed:

cat ~/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)