Safely move or rename a file while finding and updating every reference across the codebase.
Relocates or renames a single file and systematically updates all references to it — imports, documentation links, configuration entries, and build files.
Before doing anything, confirm:
If any check fails, report the problem and stop.
Search the entire codebase for anything that points to the file. Use multiple search patterns to catch all variations:
| Pattern type | Example |
|---|
| Bare filename | config.py |
| Full relative path | src/utils/config.py |
With leading ./ | ./src/utils/config.py |
| Without extension | config (for import statements) |
| In import syntax | from src.utils import config |
Scan these file types at minimum:
.py, .js, .ts, .go, .rs, .c, .cpp, .sh).md, .txt, .rst).yaml, .yml, .json, .toml)Makefile, CMakeLists.txt, package.json)For every file that references the moved file:
Path guidelines:
Use git mv to preserve history:
git mv "<source>" "<destination>"
If the destination directory doesn't exist yet:
mkdir -p "$(dirname '<destination>')" && git mv "<source>" "<destination>"
Summarise what happened:
git mv — it preserves file history. Never use plain mv.