xmv — Reference-Aware Move

xmv is a drop-in replacement for mv that moves files or directories and automatically updates all path references across your filesystem.

Install

cargo install --path crates/xmv-cli

Quick Start

# Move a project and update all references
xmv ~/projects/oldname ~/projects/newname

# Preview changes without applying (dry run)
xmv ~/projects/old ~/projects/new --dry-run

# AI/scripted usage — no prompts, JSON output
xmv ~/projects/old ~/projects/new -y -j

# Post-move cleanup (file was already moved)
xmv ~/projects/old ~/projects/new --fixup

# Scan entire filesystem
xmv ~/projects/old ~/projects/new --global

# Allow modifying system files
xmv /opt/oldservice /opt/newservice -g -S

What It Does

When you move a file or directory, xmv:

1. Finds all references to the old path — absolute, tilde (~/), $HOME, and relative (../) forms
2. Shows you a preview of every change it will make (like a package manager)
3. Asks for confirmation before applying
4. Updates references in text files, retargets symlinks
5. Creates backups of non-git files before modifying them

Safety

• Dry-run by default mentality — always shows changes before applying
• Tiered trust model:
  • Git-tracked files: git handles rollback
  • $HOME files: automatic .bak backups
  • System files (/etc): skipped unless --system is passed
• Exact boundary matching — /projects/old never matches /projects/oldstuff
• No --force flag — if the destination exists, you must resolve it manually

Configuration

# User config
~/.config/xmv/config.toml

# Project config (checked into repos)
./.xmv.toml

# System config
/etc/xmv/config.toml

exclude = ["node_modules", "target", "__pycache__"]
extra_scopes = ["~/.config"]
verbose = false

All Flags

MOVE:     -f, --fixup          Post-move mode (skip the move)
SCOPE:    -s, --scope <path>   Additional scan directory
          -g, --global         Scan entire filesystem
          -S, --system         Allow modifying files outside $HOME
          -e, --exclude <pat>  Exclude glob pattern
OUTPUT:   -y, --yes            Skip confirmation
          -n, --dry-run        Preview only
          -j, --json           Structured JSON output
          -v, --verbose        Detailed progress
CONFIG:   --config <path>      Config file override
          --dump-config        Print resolved config
SYMLINKS: --no-symlinks        Skip symlink retargeting
SKIP:     --skip-add <pat>     Add to scan skiplist
          --skip-remove <pat>  Remove from skiplist
          --skip-list          Show skiplist
CLEANUP:  --clean              Delete tracked .bak files
          --before <dur>       Only clean backups older than duration

License

MIT