Skip to content

Dotfiles Cleanup

Maintain a clean home directory by removing backup files, cache, and legacy configs that accumulate over time.

Quick start

# Interactive mode (asks for confirmation)
bash ~/dotfiles/scripts/cleanup.sh

# Dry run (preview what would be removed)
bash ~/dotfiles/scripts/cleanup.sh --dry-run

# Force mode (skip confirmation)
bash ~/dotfiles/scripts/cleanup.sh --yes

What gets cleaned up

The cleanup script removes common cruft that accumulates in your home directory:

1. Backup files

Old backup files from manual edits or previous dotfile installations:

  • .zshrc.bak
  • .gitconfig.backup

These are typically created when: - You edit dotfiles directly instead of through the repo - Previous installs of dotfiles created backups - You manually saved a copy before making changes

2. Cache files

Generated files that will be recreated automatically as needed:

  • .zcompdump* — Zsh completion cache (multiple versions from different machines)
  • .lesshst — Less pager history
  • .viminfo — Vim editor history
  • .z — Z directory jump data
  • .DS_Store — macOS Finder metadata

These files are safe to delete and will regenerate when you use the tools again.

3. Legacy configs

Configuration files from replaced or obsolete tooling:

  • .bash_profile — Bash config (if you've switched to Zsh)
  • .profile — Generic shell profile (superseded by .zprofile)
  • .zshenv — Old Zsh environment (if not used)
  • .spaceship.zsh — Spaceship prompt config (if using Starship now)
  • .zsh.plugins.txt, .zsh_plugins.txt, .zsh_plugins.zsh — Old plugin systems (replaced by Sheldon)
  • .angular-config.json — Old Angular CLI cache

These were useful at one time but are no longer needed if you've switched to newer tooling.

What NEVER gets removed

The cleanup script is conservative and only removes files explicitly listed. It never touches:

Managed dotfiles (via symlinks.map)

All files symlinked by install.sh are never touched:

  • .zshrc, .zprofile, .gitconfig, etc.
  • All files listed in config/symlinks.map

Expected unmanaged files

Files that are expected to exist but aren't managed by the repo:

  • .fzf.zsh — Generated by fzf installation, sourced by .zshrc
  • .yarnrc — Work-specific Yarn config (template at templates/yarnrc.template)
  • .zshrc.local — Machine-specific shell config (template at home/examples/zshrc.local.example)
  • ~/.config/git/local.gitconfig — Machine-specific git config (signing keys, work email)
  • ~/.config/git/va.gitconfig — Organization-specific git config
  • ~/.config/git/afs.gitconfig — Organization-specific git config

Directories

The cleanup script only removes files in $HOME root, never subdirectories like:

  • ~/.config/
  • ~/.ssh/
  • ~/.cache/
  • Tool directories (.cargo, .rustup, .rbenv, etc.)

Important data

  • .zsh_history — Your shell command history (kept even though it's cache-like)
  • Any file not explicitly listed in the cleanup script

When to run cleanup

After bootstrap on a new machine

# After setting up a fresh machine
bash ~/dotfiles/bootstrap.sh
bash ~/dotfiles/scripts/cleanup.sh --yes

After uninstalling dotfiles

# When switching to a different dotfiles system
bash ~/dotfiles/scripts/uninstall.sh
bash ~/dotfiles/scripts/cleanup.sh --yes

Periodically for maintenance

# Every few months to keep things tidy
bash ~/dotfiles/scripts/cleanup.sh

After syncing from another machine

If you've been working on dotfiles on a different machine and pull changes:

cd ~/dotfiles
git pull
zsh install.sh
bash scripts/cleanup.sh --dry-run  # Preview first
bash scripts/cleanup.sh            # Then clean up

Safety features

The cleanup script is designed to be safe:

  1. Interactive by default — Asks for confirmation before removing anything
  2. Dry-run mode — Preview changes without making them (--dry-run)
  3. Explicit paths only — No wildcards or glob patterns in rm commands
  4. Existence checks — Only tries to remove files that actually exist
  5. Categorized output — Shows exactly what's being removed and why
  6. Never uses rm -rf — Only removes individual files, never directories

Understanding the output

$ bash ~/dotfiles/scripts/cleanup.sh

  🧹  dotfiles cleanup  —  removing cruft from ~
  ─────────────────────────────────────────────────

  This removes backup files, cache, and legacy configs from your home
  directory. Managed dotfiles (symlinks) are never touched. Continue? [y/N] y

  🧹  Backup files
  → remove    ~/.zshrc.bak
  → remove    ~/.gitconfig.backup

  🧹  Cache files
  → remove    ~/.zcompdump
  → remove    ~/.zcompdump-AFSMW740493660-5.9
  → remove    ~/.z
  → remove    ~/.DS_Store

  🧹  Legacy configs
  → remove    ~/.bash_profile
  → remove    ~/.spaceship.zsh

  ─────────────────────────────────────────────────
  ✓ 8 removed  ·  3 not found
  ─────────────────────────────────────────────────

  → Tip: Run 'bash ~/dotfiles/verify.sh' to check your dotfiles are still healthy

Verification after cleanup

After running cleanup, verify your environment still works:

# Run the dotfiles health check
bash ~/dotfiles/verify.sh

# Test key tools
git config --list          # Git still configured
zsh -c 'echo $SHELL'       # Zsh loads properly
fzf --version              # fzf integration works

Customizing cleanup

If you want to clean up additional files specific to your machine, edit scripts/cleanup.sh and add them to one of the arrays:

# Add to BACKUP_FILES, CACHE_FILES, or LEGACY_CONFIGS
LEGACY_CONFIGS=(
  "$HOME/.bash_profile"
  "$HOME/.your-custom-file"  # Add your own
)

Then commit the change to your dotfiles repo so it runs on all your machines.

See also