Move a File

Relocates or renames a single file and systematically updates all references to it — imports, documentation links, configuration entries, and build files.

Inputs

• •Source path: Current location of the file (relative to project root)
• •Destination path: Where the file should end up
• •Context (optional): Why the file is being moved, or what it contains

Procedure

1. Validate Paths

Before doing anything, confirm:

• •The source file exists
• •The destination directory exists (or can be created)
• •Nothing already lives at the destination path
• •Both paths are relative to the project root

If any check fails, report the problem and stop.

2. Find Every Reference

Search the entire codebase for anything that points to the file. Use multiple search patterns to catch all variations:

Scan these file types at minimum:

• •Source code (.py, .js, .ts, .go, .rs, .c, .cpp, .sh)
• •Documentation (.md, .txt, .rst)
• •Configuration (.yaml, .yml, .json, .toml)
• •Build files (Makefile, CMakeLists.txt, package.json)

3. Update Each Reference

For every file that references the moved file:

1. •Read the file to understand the context of the reference
2. •Compute the correct new path (it may need to be relative to that file's location)
3. •Apply the edit
4. •Note what was changed

Path guidelines:

• •Documentation and config files typically use paths relative to the project root
• •Import statements follow the language's own conventions
• •Filesystem operations may need paths relative to the calling file

4. Perform the Move

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>"

5. Report Results

Summarise what happened:

• •Old path and new path
• •Number of files updated
• •List of each updated file with a brief note on the change
• •Any references that look uncertain and may need manual review

Important Considerations

1. •Always use git mv — it preserves file history. Never use plain mv.
2. •Case sensitivity — git is case-sensitive even on case-insensitive filesystems. Take care when only changing letter case.
3. •Search broadly — different files may reference the same path in different ways. Use multiple patterns.
4. •Flag uncertainty — if a reference is ambiguous, include it in the report and ask the user to verify.
5. •Single files only — this skill handles one file at a time. Moving entire directories requires a different approach.