Move Git file/directory and update all references

VerifiedSafe

Move a file or directory in a Git repository and automatically update all references in code, config, and documentation.

Sby Skills Guide Bot
DevelopmentIntermediate
7/27/2026
Claude CodeCursorCodex
#git#refactoring#file-move#codebase-search#imports

Recommended for

Automated summary

Moves a file or directory with git mv and updates every textual reference to the old path across the repository.

Strengths

  • Uses git mv so the moved file keeps its Git history
  • Scans the repo (Python source, tests, YAML/JSON, markdown) to replace references and re-greps to confirm none remain
  • Reports every file touched with a per-file replacement count and flags ambiguous matches for review
  • Writes a plan.md and asks for clarification when the request is unclear

Limitations

  • Replacement is plain grep-based, so it can rewrite unrelated substring matches of the path
  • Cannot handle dynamically constructed references such as computed imports or runtime-concatenated paths
  • Subrepo cases like helpers_root require manual cd and path adjustment
When to use it

Reach for it when restructuring a Git repo's layout and a path rename must propagate through code, tests, config and docs.

When not to use it

Skip it when the source path is a short, common substring, or when references are built at runtime and need a hand-written migration.

Security analysis

Safe
Quality score85/100

The skill uses standard Git and grep commands for a legitimate repository maintenance task. It includes safeguards such as checking that the source exists, the destination does not already exist, creating parent directories, and skipping binary files and .git. There is no destructive, exfiltrating, or obfuscated behavior.

No concerns found

How this analysis is made

Examples

Move a Python module
Move src/utils/parsing.py to src/core/parsing.py and update all references to it in the repo.
Relocate a config directory
git mv the directory config/legacy/ to config/archive/legacy/ and fix every path in our YAML, JSON and markdown files.
Move a file inside a subrepo
Move helpers_root/tools/log.py to helpers_root/core/log.py, descending into helpers_root for git mv, and update the imports.

description: Move a file or directory in the Git repo and update all references to it model: haiku

Goal

  • Given a source path <SRC> and destination path <DST> move a file or directory in the Git repo and update all references to it

Workflow

Validate Inputs

  • Confirm <SRC> exists in the repository
  • Confirm <DST> does not already exist (to prevent accidental overwrites)
  • Ensure the parent directory of <DST> exists, creating it if necessary

Move the File or Directory

  • Run git mv <SRC> <DST> to preserve Git history
  • If the file is in a subrepo (e.g., helpers_root), descend in that dir to use git mv
    • E.g., cd helpers_root && git mv <SRC> <DST> adjusting the paths accordingly

Update All References

  • Search the entire repository for any occurrences of <SRC>
    > grep -r -i <SRC> .
    
  • Replace each occurrence of <SRC> with <DST>
  • This includes:
    • Source code imports in Python
    • Unit test code in Python
    • Configuration files in YAML and JSON
    • Documentation in markdown and text
    • Any other plaintext files
  • Skip binary files and the .git/ directory

Summarize Changes

  • Report what changes were performed
    • List every file that had references updated, with a count of replacements per file
    • Flag any ambiguous matches that may need manual review

Ask for Help If Unsure How to Do

  • If the task is not perfectly clear, you MUST not perform it, but ask for clarifications
    • When the task is complex, create a plan.md with 5 bullet points explaining what the plan is

Verify Results

  • Make sure that there is no reference left over about file <SRC>
    > grep -r -i <SRC> .
    

From the file to a first result

The download contains exactly the content displayed on this page. This copy may differ from the latest version in the source repository.

View the source and supporting files

This download contains SKILL.md only. Any scripts, references, templates and dependencies are not included. Get the required files from the source, preserving their directory structure, before continuing.

1. Download the file

Download SKILL.md

From the root of a test project, save the file as .skill-downloads/move-git-file-directory-and-update-all-references-ms2s7d9b/SKILL.md, or use the command below. This folder is for inspecting the skill before installation.

Command for macOS/Linux or WSL: requires a POSIX shell and curl. On Windows without WSL, use the download button and create the folder manually.

mkdir -p '.skill-downloads/move-git-file-directory-and-update-all-references-ms2s7d9b' && curl --fail --show-error --location 'https://skills-guides.com/api/skills/move-git-file-directory-and-update-all-references-ms2s7d9b/download' --output '.skill-downloads/move-git-file-directory-and-update-all-references-ms2s7d9b/SKILL.md.part' && mv '.skill-downloads/move-git-file-directory-and-update-all-references-ms2s7d9b/SKILL.md.part' '.skill-downloads/move-git-file-directory-and-update-all-references-ms2s7d9b/SKILL.md'

2. Check prerequisites

Read SKILL.md before using it. If it references scripts or external services, inspect them and prepare the required access in your test environment.

No recognized prerequisites section in this file. This does not mean it is self-contained: libraries, tools and access requirements may be mentioned elsewhere in the content or source repository.

The platforms on this page are catalog indications. The paths below follow tool documentation; they do not prove this skill has been run in those tools. No minimum tool version is confirmed for this listing.

3. Load the skill

This file does not provide a usable name/description header for this native procedure. It remains available to download and inspect; use the manual method below.

Manual method or another tool: attach SKILL.md to a conversation, or open it in an agent that can read files. Include any required supporting resources. No universal folder is recognized by every tool.

4. Try a first task

Use a short, synthetic input: an API endpoint, a small document or an interface brief. In a new conversation, attach the file or give the agent its path, then adapt this request:

Read .skill-downloads/move-git-file-directory-and-update-all-references-ms2s7d9b/SKILL.md and apply its instructions to this example: [describe a test input]. Identify any missing files, dependencies or access. Produce the result requested by the skill without inventing data or running unreviewed scripts.

Expected result: output matching the skill instructions, or a precise list of missing prerequisites. A read confirmation alone does not validate a first use. If an external resource is unavailable, that path remains untested.

Related skills