p4-file-operations

name	p4-file-operations
description	P4 file operations — query content, history, annotations, diffs, and modify files (add, edit, delete, move, sync, resolve) via P4 MCP tools. Use when: reading file content, viewing history, comparing revisions, adding or editing files, syncing, resolving conflicts, or reconciling workspace changes in P4.

File Operations

Use the query_files and modify_files tools to work with files in P4 depots.

Querying Files

Action	Purpose	Key Parameters
content	Get file content at a revision	file_path
history	Get revision history (filelog)	file_path, max_results
info	Get file metadata (type, size, head revision)	file_path
metadata	Get extended file metadata	file_path
diff	Compare file revisions or depot vs workspace	file_path, file2, diff2
annotations	Get per-line blame/annotation	file_path
search	Search for files by name pattern (wildcard)	file_path, pattern, max_results
grep	Search for files by content pattern	file_path, pattern, case_insensitive, max_results

Modifying Files

Action	Purpose	Key Parameters
add	Mark a new file for add	file_paths, changelist
edit	Open an existing file for edit	file_paths, changelist
delete	Mark a file for delete (requires approval)	file_paths, changelist
move	Move/rename a file	source_paths, target_paths, changelist
revert	Revert opened files to depot version	file_paths
reconcile	Reconcile workspace with depot (detect offline edits)	file_paths
resolve	Resolve file conflicts after integration	file_paths, mode
sync	Sync files from depot to workspace	file_paths, force

Common Workflows

Edit and submit a file

1. modify_changelists → create a pending changelist
2. modify_files → edit to open the file in the changelist
3. Make your changes locally
4. modify_changelists → submit to commit

Add new files

1. modify_changelists → create a pending changelist
2. Create the file(s) locally in your workspace
3. modify_files → add to mark them for add
4. modify_changelists → submit

Investigate file history

1. query_files → history to see revision log
2. query_files → diff to compare specific revisions
3. query_files → annotations to see per-line authorship
4. query_files → content to read a specific revision

Find files by name or content

1. query_files → search with a wildcard pattern (e.g., *.py) to find files by name
2. query_files → grep with a text pattern to find files containing specific content
3. Use query_files → content to read files found from search results

Sync and resolve conflicts

1. modify_files → sync to get latest from depot
2. If conflicts exist, modify_files → resolve to handle them
3. modify_changelists → submit when resolved

Reconcile offline edits

1. Make changes outside of P4 (e.g., IDE edits without opening files first)
2. modify_files → reconcile to detect and open changed files

Best Practices

• Always open files for edit before modifying them so changes are tracked.
• Use reconcile if you forgot to open files first — it detects offline edits, adds, and deletes.
• Use diff to verify changes before submitting.
• Use annotations to understand who last changed each line (useful for debugging).
• Specify changelist when opening files to keep changes organized.
• When moving files, both source and target must be in the same changelist.