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