# Tools P4 Basics

> Fundamental Perforce operations including sync, edit, add, delete, submit, revert, and file state management.

- Skill: `tjboudreaux/tools-p4-basics` (Agent Skill)
- Install (CLI): `npx skillmds@latest add tjboudreaux/tools-p4-basics`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tjboudreaux/tools-p4-basics/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tjboudreaux (https://skillmd.com/u/tjboudreaux)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tjboudreaux/tools-p4-basics

---


# Perforce Basics

## Overview

Perforce (P4) is a centralized version control system optimized for large codebases and binary assets. This skill covers essential daily operations.

## When to Use

- Syncing latest changes
- Editing files for modification
- Adding new files
- Deleting files
- Submitting changes
- Reverting unwanted changes

## Core Concepts

### File States

| State | Description | Command to Change |
|-------|-------------|-------------------|
| **Not in depot** | File exists locally but not tracked | `p4 add` |
| **Synced** | File matches depot version | - |
| **Edited** | Open for edit, modified locally | `p4 edit` then modify |
| **Added** | Marked for addition to depot | `p4 add` |
| **Deleted** | Marked for deletion from depot | `p4 delete` |
| **Out of date** | Depot has newer version | `p4 sync` |

### Revision Specifiers

```bash
# Specific revision number
file.txt#3

# Head revision (latest)
file.txt#head

# Changelist number
file.txt@12345

# Label
file.txt@release_1.0

# Date/time
file.txt@2024/01/15
file.txt@2024/01/15:14:30:00

# Revision range
file.txt#2,#5
file.txt@10000,@12000
```

## Sync Operations

### Basic Sync

```bash
# Sync entire workspace to head
p4 sync

# Sync specific path
p4 sync //depot/project/...

# Sync specific file
p4 sync //depot/project/file.txt

# Sync to specific revision
p4 sync //depot/project/...#head
p4 sync //depot/project/...@12345

# Sync to specific changelist
p4 sync @12345
```

### Sync Options

```bash
# Preview sync (don't actually sync)
p4 sync -n //depot/project/...

# Force sync (re-download even if up to date)
p4 sync -f //depot/project/...

# Parallel sync (faster for many files)
p4 sync --parallel=threads=4 //depot/project/...

# Safe sync (don't clobber writable files)
p4 sync -s //depot/project/...

# Sync and show affected files
p4 sync //depot/project/... 2>&1 | head -50
```

### Selective Sync

```bash
# Sync only specific file types
p4 sync //depot/project/....cs
p4 sync //depot/project/....prefab

# Sync excluding paths (use workspace view instead)
# Or sync specific subdirectories
p4 sync //depot/project/Assets/Scripts/...
```

## Edit Operations

### Opening Files for Edit

```bash
# Edit single file
p4 edit file.txt

# Edit multiple files
p4 edit *.cs

# Edit files in directory
p4 edit Assets/Scripts/...

# Edit with specific changelist
p4 edit -c 12345 file.txt

# Edit to default changelist
p4 edit -c default file.txt
```

### Check Edit Status

```bash
# See files open for edit
p4 opened

# See files open in specific changelist
p4 opened -c 12345

# See files open by all users
p4 opened -a //depot/project/...

# See who has file open
p4 opened -a //depot/project/file.txt
```

## Add Operations

### Adding New Files

```bash
# Add single file
p4 add newfile.txt

# Add multiple files
p4 add *.cs

# Add files recursively
p4 add Assets/NewFeature/...

# Add to specific changelist
p4 add -c 12345 newfile.txt

# Add with specific file type
p4 add -t binary+l largefile.bin
p4 add -t text+x script.sh
```

### File Types

```bash
# Common file types
text        # Text file, diff/merge enabled
binary      # Binary file, no diff/merge
unicode     # Unicode text
symlink     # Symbolic link

# Modifiers
+l          # Exclusive lock (only one user can edit)
+w          # Always writable on client
+x          # Executable bit
+S          # Only head revision stored (saves space)
+F          # Check for RCS keywords

# Examples
p4 add -t binary+l Assets/Textures/hero.psd    # Locked binary
p4 add -t text Assets/Scripts/Player.cs         # Text file
```

## Delete Operations

### Deleting Files

```bash
# Delete single file
p4 delete file.txt

# Delete multiple files
p4 delete *.bak

# Delete in specific changelist
p4 delete -c 12345 file.txt

# Delete files matching pattern
p4 delete //depot/project/....tmp
```

### Handling Deleted Files

```bash
# See deleted files in depot
p4 files //depot/project/...@head | grep "delete change"

# Recover deleted file (sync old revision, then add)
p4 sync //depot/project/file.txt#head-1
p4 add file.txt

# Or use obliterate (admin only) to permanently remove
```

## Revert Operations

### Reverting Changes

```bash
# Revert single file
p4 revert file.txt

# Revert all files in changelist
p4 revert -c 12345 //...

# Revert all open files
p4 revert //...

# Revert unchanged files only
p4 revert -a //...

# Revert with preview
p4 revert -n //...
```

### Revert to Specific Revision

```bash
# Sync to old revision (makes file read-only)
p4 sync //depot/project/file.txt#3

# To actually revert content and submit:
p4 sync //depot/project/file.txt#head
p4 edit file.txt
p4 sync -f //depot/project/file.txt#3
p4 resolve -ay file.txt
# Now submit
```

## Submit Operations

### Submitting Changes

```bash
# Submit default changelist (opens editor for description)
p4 submit

# Submit specific changelist
p4 submit -c 12345

# Submit with description
p4 submit -d "Fix player movement bug"

# Submit specific files from default changelist
p4 submit file.txt

# Submit and reopen files for further editing
p4 submit -r -c 12345
```

### Pre-Submit Checks

```bash
# Check what will be submitted
p4 opened -c default

# Check for conflicts before submit
p4 sync
p4 resolve

# Verify files are correct
p4 diff -se //...  # Files that differ from depot

# Check changelist description
p4 change -o 12345
```

## Status Commands

### Workspace Status

```bash
# Files open for edit/add/delete
p4 opened

# Files that need sync
p4 sync -n //...

# Files modified but not opened (reconcile needed)
p4 status

# Reconcile local changes with depot
p4 reconcile //...
```

### Depot Status

```bash
# List files in depot
p4 files //depot/project/...

# List files with specific pattern
p4 files //depot/project/....cs

# Get file info
p4 fstat //depot/project/file.txt

# Detailed file info
p4 fstat -Ol //depot/project/file.txt
```

## Reconcile Operations

### Finding Untracked Changes

```bash
# Find all local changes not in Perforce
p4 reconcile //...

# Preview reconcile
p4 reconcile -n //...

# Reconcile specific types
p4 reconcile -e //...  # Edited files
p4 reconcile -a //...  # Added files
p4 reconcile -d //...  # Deleted files

# Reconcile to specific changelist
p4 reconcile -c 12345 //...
```

## Common Workflows

### Daily Sync Workflow

```bash
# 1. Check for open files
p4 opened

# 2. Sync latest
p4 sync

# 3. Resolve any conflicts
p4 resolve

# 4. Continue working
```

### Edit-Submit Workflow

```bash
# 1. Open file for edit
p4 edit file.txt

# 2. Make changes
# ... edit file ...

# 3. Verify changes
p4 diff file.txt

# 4. Submit
p4 submit -d "Description of changes"
```

### Add New Files Workflow

```bash
# 1. Create files locally
# ... create files ...

# 2. Add to Perforce
p4 add newfile.txt

# 3. Verify
p4 opened

# 4. Submit
p4 submit -d "Add new feature files"
```

## Best Practices

1. **Always sync before editing** - Avoid conflicts
2. **Use descriptive changelist descriptions** - Help others understand
3. **Submit related changes together** - Atomic commits
4. **Revert unchanged files** with `p4 revert -a`
5. **Check `p4 opened`** before leaving for the day
6. **Use `p4 reconcile`** to catch local changes
7. **Preview with `-n`** before destructive operations
8. **Use exclusive locks** for binary files
9. **Don't submit broken code** - Test first
10. **Keep changelists small** - Easier to review/revert

## Troubleshooting

| Issue | Solution |
|-------|----------|
| "File not on client" | Run `p4 sync` first |
| "Can't edit - not synced" | Sync file, then edit |
| "Can't clobber writable file" | Use `p4 sync -f` or fix permissions |
| "File already open" | Check `p4 opened -a` for who has it |
| "Out of date" | Sync and resolve before submit |
| "No such file" | Check path, use `p4 files` to verify |