home / skills / steveclarke / dotfiles / move-files
This skill guides safe two-phase file moves that preserve git history by separating moves from content changes, ensuring clean, trackable diffs.
npx playbooks add skill steveclarke/dotfiles --skill move-filesReview the files below or copy the command above to add this skill to your agents.
---
name: move-files
description: Move files using a two-phase approach that preserves Git history. Phase 1 uses mv commands only, then waits for staging. Phase 2 makes content changes separately. Use when reorganizing files and need clean, trackable diffs. Triggers on "move files", "reorganize structure", "preserve git history".
disable-model-invocation: true
---
# Move Files Command
## Overview
A two-phase approach for moving files that preserves git history and makes changes trackable in diffs.
## The Problem
When moving files, if you copy content and write new files, git treats them as deletions + additions rather than moves. This makes it impossible to track what actually changed versus what just moved.
## The Solution: Two-Phase Move
### Phase 1: Move Files with `mv` Commands
**CRITICAL RULE:** Use terminal `mv` commands ONLY. Never copy content and write files.
```bash
mv source/path destination/path
```
**After moving files, STOP.**
Tell the user:
> "Phase 1 complete. Files have been moved using `mv` commands. Please stage these moves in git, then let me know when ready for Phase 2."
### Phase 2: Make Content Changes (Only After User Stages)
Only proceed after user explicitly confirms moves are staged.
Now make any necessary content changes to the moved files:
- Update path references
- Fix import statements
- Update documentation links
- Adjust configuration values
- Modify file content as needed
## Why This Works
**Git tracking:** When you use `mv` and stage the move, git recognizes it as a rename/move operation. This preserves file history.
**Clean diffs:**
- Phase 1 diff shows: file moved from A to B (no content changes)
- Phase 2 diff shows: only the actual content modifications
**Easy review:** The user can verify moves are correct before any content changes happen. This makes it clear what moved versus what actually changed.
## When to Use This
Use this pattern whenever:
- Moving files between directories
- Reorganizing documentation
- Refactoring code structure
- Consolidating scattered files
- Any scenario where files need to move AND have content updated
## Example Usage
User says: "Move all the guides from backend/docs/ to project/guides/backend/"
Your response:
1. Use `mv backend/docs/guides project/guides/backend`
2. Verify the move succeeded
3. Tell user to stage the moves
4. **WAIT** for user confirmation
5. Only then make content changes to the moved files
## Key Principles
- **Use `mv` commands only** - Never copy and write
- **Stop after moves** - Wait for staging
- **Make content changes separately** - Only after user confirms staging
- **One phase at a time** - Never combine moves with content changes
This skill performs file reorganizations using a strict two-phase workflow that preserves Git history. It issues only mv commands in the first phase and waits for the user to stage the changes before applying any content edits. The result is clean, reviewable diffs that separate moves from content modifications.
Phase 1 issues terminal mv commands to relocate files or directories and then stops. The tool instructs you to stage those moves in Git and confirm when staging is complete. Phase 2 runs after your confirmation and applies content changes such as updating import paths, links, or configuration values so diffs show only actual edits.
Why use two phases instead of moving and editing at once?
Separating moves from edits keeps git diffs clear: Phase 1 preserves file history as a rename, Phase 2 shows only content changes. Combining them obscures what actually moved vs what changed.
What exactly must I do after Phase 1?
Stage the moved files in git (git add -A or individual paths) and verify the index shows renames. Then confirm to proceed; only then will content edits be applied.
What happens if I forget to stage before confirming?
If moves are not staged, Git may record deletions and additions instead of renames. The skill will refuse to proceed until you stage and confirm to ensure history preservation.