gh-reqvire-org-reqvire-reqvire-claude-plugin/commands/mv-file.md

allowed-tools: Read, Bash(reqvire:*) argument-hint: [source-file] [target-file] description: Move entire specification file with all its elements to a new location model: claude-sonnet-4-5-20250929

Move File

Move an entire specification file with all its elements to a new location, automatically updating all relations that reference elements in the moved file.

Current Model Context

• Total elements: !reqvire search --json | jq -r '.global_counters.total_elements'

User Request

${1:+Source file: $1} ${2:+Target file: $2} ${1:-The user will provide source and target file paths.}

Steps

1. Understand the context:

   • Identify the source file to move
   • Determine the target file location
   • Verify source file exists in the model

2. Preview the move operation:

   reqvire mv-file "<source-file>" "<target-file>" --dry-run
   

   This shows:

   • Which files will be modified
   • How many elements will be moved
   • What relations will be updated
   • Git-style diffs for all affected files

3. Apply the file move:

   reqvire mv-file "<source-file>" "<target-file>"
   

   The mv-file command automatically:

   • Moves all elements from source file to target file
   • Updates all element identifiers to reflect new file path
   • Updates all incoming relations (from other files) to reference new location
   • Preserves all element content, metadata, and outgoing relations
   • Deletes the source file after successful move
   • Creates the target file with all moved elements

4. Verify the changes:

   reqvire validate
   

Important Notes

• Path resolution: File paths are resolved relative to current working directory
• Automatic relation updates: All relations pointing to moved elements are automatically updated throughout the model
• Identifier updates: Element identifiers change from <source-file>#<slug> to <target-file>#<slug>
• Subdirectory support: Works correctly when executed from subdirectories within git repository
• Atomic operation: Either all elements move successfully or none move (on validation failure)

Squash Mode

When the target file already exists, use the --squash flag to merge all elements from source into the target file:

reqvire mv-file "<source-file>" "<existing-target-file>" --squash

Squash behavior:

• All source elements are appended to target file
• Target file's existing elements remain unchanged
• Source file is deleted after successful move
• All relations are updated throughout the model

When to use --squash:

• Consolidating multiple specification files into one
• Merging temporary/experimental specs back into main file
• Reorganizing model structure by combining related files

Error Cases

The mv-file operation will fail with a clear error if:

• The source file does not exist or contains no elements
• The target file already exists in the model (unless --squash flag is provided)
• The operation would result in invalid model state

Examples

Move file within specifications directory:

reqvire mv-file "requirements/OldFile.md" "requirements/NewFile.md"

Move file to different directory:

reqvire mv-file "requirements/Auth.md" "security/Authentication.md"

Preview before moving:

reqvire mv-file "specs/File.md" "requirements/File.md" --dry-run

Get JSON output with element mappings:

reqvire mv-file "old/path.md" "new/path.md" --json

Works from subdirectories (paths relative to current directory):

cd submodule/
reqvire mv-file "specs/File.md" "requirements/File.md"

Squash elements from multiple files:

# Merge experimental specs into main requirements
reqvire mv-file "temp/Experiments.md" "requirements/Requirements.md" --squash

Preview squash before applying:

reqvire mv-file "old/File.md" "requirements/MainFile.md" --squash --dry-run

When to Use mv-file

Use mv-file when:

• Reorganizing specification file structure
• Moving all requirements for a feature to a different location
• Consolidating or splitting specification files
• Refactoring the model directory structure

Use mv-file with --squash when:

• Merging multiple specification files into one
• Consolidating temporary or experimental requirements back into main specs
• Simplifying model structure by reducing file count

Note: mv-file moves entire files with all their elements. To move individual elements between files, use reqvire mv instead.

Related Commands

• Move element: reqvire mv <element-name> <target-file>
• Rename element: reqvire rename <current-name> <new-name>
• Remove element: reqvire rm <element-name>
• Add element: reqvire add <file> < element.md