MCPInstall

tools-p4-basics

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

Installs
46
Last 24h
—
Trending rank
—
Security
Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/tjboudreaux/cc-plugin-perforce --skill tools-p4-basics
  1. 01

    Install

    Run the command in your project. The CLI asks which agents to install for.

  2. 02

    Describe the task

    Ask your agent for something this skill covers. It loads tools-p4-basics automatically when relevant.

  3. 03

    Review the result

    The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

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

StateDescriptionCommand to Change
Not in depotFile exists locally but not trackedp4 add
SyncedFile matches depot version-
EditedOpen for edit, modified locallyp4 edit then modify
AddedMarked for addition to depotp4 add
DeletedMarked for deletion from depotp4 delete
Out of dateDepot has newer versionp4 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

IssueSolution
"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

FAQ

What does the tools-p4-basics skill do?

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

How do I install tools-p4-basics?

Run npx skills add https://github.com/tjboudreaux/cc-plugin-perforce --skill tools-p4-basics in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/tools-p4-basics/ (personal) or .claude/skills/tools-p4-basics/ (project).

Which AI agents can use tools-p4-basics?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is tools-p4-basics safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains tools-p4-basics?

It is published by tjboudreaux in tjboudreaux/cc-plugin-perforce. It has 46 recorded installs.

Popular other skills

View category →

hyperframes-cli

heygen-com/hyperframes

The HyperFrames CLI by job - scaffold, check, look at frames, edit the timeline, preview, render locally or in the cloud, publish, project history - plus reading its JSON and recovering from build or render failures.

1.3M installs

triage

mattpocock/skills

Move issues and external PRs through a state machine of triage roles, categorise, verify, grill if needed, and write agent-ready briefs.

1M installs

ask-matt

mattpocock/skills

Ask which skill or flow fits your situation. A router over the skills in this repo.

778.4K installs

to-questionnaire

mattpocock/skills

Turn a decision you can't fully answer into a questionnaire for someone else to fill in.

508.9K installs

wait-what

mattpocock/skills

Stop. That last message did not land: re-pitch it.

459.7K installs

loop-me

mattpocock/skills

Grill me about specs for the workflows I want to build, within this workspace.

447.9K installs