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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 1. Check for open files
p4 opened

# 2. Sync latest
p4 sync

# 3. Resolve any conflicts
p4 resolve

# 4. Continue working

Edit-Submit Workflow

# 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

# 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