4 Perforce version control skills covering basic operations, changelist management, conflict resolution, and shelving workflows

version
1.0.0
GitHub stars
7

Install

/plugin install perforce@perforce-marketplace

Run it inside Claude Code after adding the marketplace with /plugin marketplace add tjboudreaux/cc-plugin-perforce.

Contents

Discovered from source

Skills 4

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

Perforce Changelist Management

Overview

Changelists in Perforce group related file changes together for atomic submission. This skill covers creating, managing, and organizing changelists effectively.

When to Use

  • Organizing work into logical units
  • Separating multiple tasks in progress
  • Preparing changes for code review
  • Managing pending vs submitted changes
  • Moving files between changelists

Core Concepts

Changelist Types

TypeDescription
DefaultAuto-created changelist for quick edits
NumberedNamed changelist with description
PendingNot yet submitted
SubmittedAlready committed to depot
ShelvedChanges stored on server, not submitted

Creating Changelists

Create New Changelist

# Create changelist (opens editor)
p4 change

# Create with description directly
p4 change -o | sed 's/<enter description here>/Fix player movement/' | p4 change -i

# Create changelist and get number
CL=$(p4 change -o | sed 's/<enter description here>/My description/' | p4 change -i | grep -o '[0-9]*')
echo "Created changelist: $CL"

Changelist Spec Format

Change: new
Client: your_workspace
User:   your_username
Status: pending
Description:
    Fix player movement bug
    
    - Fixed velocity calculation
    - Added ground check
    - Updated unit tests

Files:
    //depot/project/Player.cs    # edit
    //depot/project/Movement.cs  # edit

Viewing Changelists

List Changelists

# Your pending changelists
p4 changes -s pending -u $P4USER

# All pending changelists for a path
p4 changes -s pending //depot/project/...

# Recent submitted changelists
p4 changes -s submitted -m 20 //depot/project/...

# Changelists by specific user
p4 changes -u john.doe -m 10

# Changelists in date range
p4 changes -s submitted @2024/01/01,@2024/01/31

# Long output with full description
p4 changes -l -m 10 //depot/project/...

View Specific Changelist

# View changelist details
p4 describe 12345

# View changelist without diffs
p4 describe -s 12345

# View changelist with shelved files
p4 describe -S 12345

# View changelist spec
p4 change -o 12345

Editing Changelists

Modify Changelist Description

# Edit changelist (opens editor)
p4 change 12345

# Update description programmatically
p4 change -o 12345 | sed 's/old description/new description/' | p4 change -i

Change Changelist Owner

# Admin operation - change owner
p4 change -o 12345 | sed 's/User:.*/User: new_owner/' | p4 change -i -f

Moving Files Between Changelists

Reopen Files to Different Changelist

# Move single file to different changelist
p4 reopen -c 12345 file.txt

# Move file to default changelist
p4 reopen -c default file.txt

# Move all files from one changelist to another
p4 reopen -c 12346 //...@=12345

# Move files matching pattern
p4 reopen -c 12345 *.cs

Split Changelist

# Create new changelist for some files
p4 change  # Creates new CL, note the number

# Move specific files to new changelist
p4 reopen -c NEW_CL file1.txt file2.txt

# Verify split
p4 opened -c 12345
p4 opened -c NEW_CL

Merge Changelists

# Move all files from CL2 to CL1
p4 reopen -c 12345 //...@=12346

# Delete empty changelist
p4 change -d 12346

Default Changelist

Working with Default Changelist

# See files in default changelist
p4 opened -c default

# Edit file to default changelist
p4 edit file.txt

# Move from default to numbered changelist
p4 reopen -c 12345 file.txt

# Submit only default changelist
p4 submit

# Move all default files to new changelist
NEW_CL=$(p4 change -o | sed 's/<enter description here>/WIP: Feature X/' | p4 change -i | grep -o '[0-9]*')
p4 reopen -c $NEW_CL //...@=default

Changelist Operations

Delete Changelist

# Delete empty pending changelist
p4 change -d 12345

# Delete changelist with files (must revert or move files first)
p4 revert -c 12345 //...
p4 change -d 12345

# Or move files then delete
p4 reopen -c default //...@=12345
p4 change -d 12345

# Force delete (admin)
p4 change -d -f 12345

Fix Submitted Changelist Description

# Admin operation - fix description after submit
p4 change -o 12345 | sed 's/typo/fixed/' | p4 change -i -f -u

Changelist Workflow Patterns

Feature Branch Pattern

# Create changelist for feature
p4 change -o | sed 's/<enter description here>/Feature: Player Dash Ability/' | p4 change -i
# Note the changelist number (e.g., 12345)

# All edits go to this changelist
p4 edit -c 12345 Player.cs
p4 edit -c 12345 PlayerAbilities.cs
p4 add -c 12345 DashAbility.cs

# Work on feature...

# When ready, submit
p4 submit -c 12345

Bug Fix Pattern

# Quick fix to default
p4 edit BuggyFile.cs
# ... fix bug ...
p4 submit -d "Fix: Null reference in PlayerController"

Multiple Tasks Pattern

# Create changelist for each task
p4 change  # CL for Task A
p4 change  # CL for Task B

# Work on Task A
p4 edit -c TASK_A_CL FileA.cs

# Switch to Task B
p4 edit -c TASK_B_CL FileB.cs

# Submit Task A when ready
p4 submit -c TASK_A_CL

# Continue Task B

Work In Progress Pattern

# Create WIP changelist
WIP_CL=$(p4 change -o | sed 's/<enter description here>/WIP: Do not submit/' | p4 change -i | grep -o '[0-9]*')

# All experimental work goes here
p4 edit -c $WIP_CL experimental.cs

# When ready to submit, update description
p4 change $WIP_CL  # Edit description, remove WIP

# Submit
p4 submit -c $WIP_CL

Querying Changelists

Search Changelists

# Find changelists with keyword in description
p4 changes -l //depot/... | grep -B5 "player"

# Find changelists affecting specific file
p4 changes //depot/project/Player.cs

# Find your changelists from last week
p4 changes -u $P4USER -s submitted @$(date -v-7d +%Y/%m/%d),@now

# Count changelists per user
p4 changes -s submitted -m 1000 //depot/project/... | awk '{print $6}' | sort | uniq -c | sort -rn

Changelist Statistics

# Files in changelist
p4 describe -s 12345 | grep "^\.\.\." | wc -l

# Lines changed in changelist
p4 describe 12345 | grep "^@@" | wc -l

# File types in changelist
p4 describe -s 12345 | grep "^\.\.\." | sed 's/.*#//' | sort | uniq -c

Integration with Workflows

Pre-Submit Checklist

#!/bin/bash
CL=$1

# Check changelist has description
DESC=$(p4 change -o $CL | grep -A100 "Description:" | grep -v "Description:" | head -1)
if [ -z "$DESC" ] || [ "$DESC" = "	<enter description here>" ]; then
    echo "ERROR: Changelist needs description"
    exit 1
fi

# Check for files
FILES=$(p4 opened -c $CL 2>/dev/null | wc -l)
if [ "$FILES" -eq 0 ]; then
    echo "ERROR: No files in changelist"
    exit 1
fi

# Check for unresolved
UNRESOLVED=$(p4 resolve -n //...@=$CL 2>&1 | grep -c "must resolve")
if [ "$UNRESOLVED" -gt 0 ]; then
    echo "ERROR: Unresolved files in changelist"
    exit 1
fi

echo "Changelist $CL ready to submit ($FILES files)"

Changelist Template

# Create changelist with template
cat << 'EOF' | p4 change -i
Change: new
Description:
    [TYPE]: Brief description
    
    ## Changes
    - Change 1
    - Change 2
    
    ## Testing
    - [ ] Unit tests pass
    - [ ] Manual testing done
    
    ## Related
    - Jira: GOD-XXXX
EOF

Best Practices

  1. Use numbered changelists for any non-trivial work
  2. Write descriptive descriptions - What and why
  3. One logical change per changelist - Atomic commits
  4. Don't mix refactoring with features - Separate CLs
  5. Prefix WIP changelists to prevent accidental submit
  6. Review before submit with p4 describe -s
  7. Keep changelists small - Easier review and rollback
  8. Use consistent naming - Team conventions
  9. Link to issue tracker in description
  10. Clean up empty changelists regularly

Troubleshooting

IssueSolution
"Can't delete non-empty changelist"Revert or move files first
"Changelist unknown"Check number, may be submitted
"Can't edit submitted changelist"Need admin -f flag
Files in wrong changelistUse p4 reopen -c
Lost changelist numberp4 changes -s pending -u $USER
Description too longSome triggers limit length

Perforce Conflict Resolution

Overview

Conflicts occur when multiple users modify the same file. Perforce provides powerful resolve tools for merging changes. This skill covers all resolve strategies and workflows.

When to Use

  • After syncing when files have conflicts
  • Before submitting changes
  • When integrating between branches
  • Handling binary file conflicts
  • Resolving content vs attribute conflicts

Core Concepts

Conflict Types

TypeDescriptionResolution
ContentBoth versions modified same linesMerge or choose version
AttributeFile type or permissions changedChoose attribute
DeleteFile deleted in one version, modified in otherKeep or delete
Move/DeleteFile moved and deletedChoose action
BinaryBinary file modified by bothChoose version (no merge)

Three-Way Merge

Base (common ancestor)
    |
    +-- Theirs (depot/source)
    |
    +-- Yours (workspace)
    |
    v
Merged Result

Basic Resolve

Check for Conflicts

# Preview resolve (see what needs resolving)
p4 resolve -n

# See files that need resolving
p4 resolve -n //depot/project/...

# Check specific file
p4 resolve -n file.txt

Automatic Resolve

# Auto-resolve all (safe merge where possible)
p4 resolve -am

# Auto-resolve accepting merge result
p4 resolve -am //depot/project/...

# Auto-resolve specific file
p4 resolve -am file.txt

Resolve Strategies

# Accept automatic merge (only if no conflicts)
p4 resolve -am

# Accept theirs (depot version)
p4 resolve -at

# Accept yours (workspace version)
p4 resolve -ay

# Force accept theirs even with conflicts
p4 resolve -at //...

# Force accept yours even with conflicts
p4 resolve -ay //...

Interactive Resolve

Launch Interactive Resolve

# Interactive resolve for all files
p4 resolve

# Interactive resolve for specific file
p4 resolve file.txt

# Interactive with specific merge tool
p4 resolve -t p4merge file.txt

Interactive Menu Options

Diff results:
  1: Accept theirs (loses your changes)
  2: Accept yours (loses depot changes)
  3: Accept merge result
  4: Edit merge result
  5: Show differences (base to theirs)
  6: Show differences (base to yours)
  7: Show differences (yours to theirs)
  8: Skip this file
  9: Help

Choose option:

Interactive Workflow

# 1. Start resolve
p4 resolve file.txt

# 2. View differences
# Option 5, 6, or 7 to understand changes

# 3. Choose resolution
# Option 1 (theirs), 2 (yours), or 3 (merge)

# 4. If merge has conflicts, option 4 to edit

# 5. Accept final result
# Option 3 to accept merge

Merge Tools

Configure P4 Merge Tool

# Set P4MERGE environment variable
export P4MERGE=/usr/local/bin/p4merge

# Or use other merge tools
export P4MERGE=/usr/local/bin/code  # VS Code
export P4MERGE=/usr/local/bin/meld  # Meld
export P4MERGE=/usr/bin/vimdiff     # Vim

P4Merge Workflow

# Launch P4Merge for conflict
p4 resolve -t file.txt

# P4Merge shows four panes:
# - Base (original)
# - Theirs (depot)
# - Yours (local)
# - Result (merged)

# Edit result pane, save, close
# Accept result in terminal

Visual Studio Code Merge

# Set VS Code as merge tool
export P4MERGE="code --wait --merge"

# Resolve using VS Code
p4 resolve file.txt

Resolve Scenarios

Simple Auto-Merge

# Both changed different parts of file
p4 sync
# File needs resolve...
p4 resolve -am
# Merge successful - changes combined

Conflicting Changes

# Both changed same lines
p4 sync
p4 resolve -am
# Conflicts detected...

# Option 1: Accept theirs
p4 resolve -at file.txt

# Option 2: Accept yours
p4 resolve -ay file.txt

# Option 3: Manual merge
p4 resolve file.txt
# Choose option 4 to edit
# Fix conflicts in editor
# Save and accept

Binary File Conflicts

# Binary files can't be merged
p4 sync
p4 resolve -n
# Binary conflict on image.psd

# Accept theirs (depot version)
p4 resolve -at image.psd

# Or accept yours (your version)
p4 resolve -ay image.psd

Delete vs Edit Conflict

# File deleted in depot, edited locally
p4 sync
p4 resolve -n
# Delete vs edit conflict...

# Keep your edited version
p4 resolve -ay file.txt

# Or accept delete
p4 resolve -at file.txt

Advanced Resolve

Partial Resolve

# Resolve only content, not attributes
p4 resolve -c //...

# Resolve only attributes
p4 resolve -A //...

# Resolve specific attribute type
p4 resolve -Aa //...  # All attributes
p4 resolve -Ab //...  # Branch action
p4 resolve -At //...  # File type

Re-Resolve

# Re-resolve already resolved file
p4 resolve -f file.txt

# Re-resolve with different strategy
p4 resolve -f -at file.txt

Resolve During Integration

# Integrate between branches
p4 integrate //depot/dev/... //depot/main/...

# Resolve integration conflicts
p4 resolve -am //depot/main/...

# If conflicts remain
p4 resolve //depot/main/...

Safe Resolve Workflow

# 1. Preview what needs resolving
p4 resolve -n

# 2. Try automatic merge first
p4 resolve -am

# 3. Check what remains
p4 resolve -n

# 4. Handle remaining manually
p4 resolve remaining_file.txt

# 5. Verify resolve complete
p4 resolve -n  # Should show nothing

Conflict Markers

Understanding Markers

When editing merge result manually:

<<<<<<< THEIRS (depot version)
code from depot
=======
code from your workspace
>>>>>>> YOURS (workspace version)

Resolving Markers

# Edit file to remove markers
vim file.txt

# Original with markers:
<<<<<<< THEIRS
function getValue() {
    return this.value;
}
=======
function getValue() {
    return this.cachedValue || this.value;
}
>>>>>>> YOURS

# Resolved (choose best version or combine):
function getValue() {
    return this.cachedValue || this.value;
}

# Save and mark resolved
p4 resolve -am file.txt

Resolve Workflows

Pre-Submit Workflow

#!/bin/bash
# pre-submit-resolve.sh

# Sync latest
p4 sync

# Check for conflicts
CONFLICTS=$(p4 resolve -n 2>&1 | grep -c "resolve")

if [ "$CONFLICTS" -gt 0 ]; then
    echo "Found $CONFLICTS files needing resolve"
    
    # Try auto-merge
    p4 resolve -am
    
    # Check remaining
    REMAINING=$(p4 resolve -n 2>&1 | grep -c "resolve")
    
    if [ "$REMAINING" -gt 0 ]; then
        echo "Manual resolve needed for $REMAINING files"
        p4 resolve -n
        exit 1
    fi
fi

echo "Ready to submit"

Integration Workflow

# 1. Integrate from source to target
p4 integrate //depot/feature/... //depot/main/...

# 2. Preview conflicts
p4 resolve -n //depot/main/...

# 3. Auto-resolve safe merges
p4 resolve -am //depot/main/...

# 4. Handle remaining conflicts
p4 resolve //depot/main/...

# 5. Test merged code

# 6. Submit integration
p4 submit -d "Integrate feature to main"

Batch Resolve Pattern

# Accept all theirs (when their changes are correct)
p4 resolve -at //depot/project/...

# Accept all yours (when your changes are correct)
p4 resolve -ay //depot/project/...

# Mixed resolution
p4 resolve -at //depot/project/Assets/...  # Accept art assets
p4 resolve -am //depot/project/Scripts/... # Merge code

Undoing Resolve

Revert and Re-Sync

# If resolve went wrong, revert and start over
p4 revert file.txt
p4 sync file.txt
p4 edit file.txt
# Re-apply your changes manually

Back Out Bad Merge

# After bad submit, can sync to previous and re-submit
p4 sync //depot/project/file.txt#head-1
p4 edit file.txt
p4 sync -f //depot/project/file.txt#head-1
p4 resolve -ay file.txt
p4 submit -d "Revert bad merge"

Best Practices

  1. Sync frequently - Smaller merges are easier
  2. Resolve before submit - Never submit unresolved
  3. Preview first with p4 resolve -n
  4. Try auto-merge before manual
  5. Use visual merge tool for complex conflicts
  6. Test after resolve - Merged code may have bugs
  7. Keep changelists small - Easier to resolve
  8. Communicate with team about conflicting areas
  9. Use exclusive locks for binary files
  10. Document conflict resolution in submit description

Troubleshooting

IssueSolution
"Must resolve before submit"Run p4 resolve
"No file(s) to resolve"Already resolved or no conflicts
Merge tool not launchingCheck P4MERGE setting
Markers left in fileEdit to remove, re-resolve
Wrong resolution acceptedRevert, sync, re-resolve
Binary conflictMust accept one version (-at or -ay)

Perforce Shelving

Overview

Shelving stores pending changes on the Perforce server without submitting them. This enables code review, work-in-progress backup, sharing between workspaces, and collaboration.

When to Use

  • Backing up work-in-progress
  • Sharing changes for code review
  • Switching between tasks
  • Transferring work between workspaces
  • Parking changes temporarily
  • Pre-submit review (Swarm)

Core Concepts

Shelving vs Submitting

FeatureShelvingSubmitting
Stored on serverYesYes
Creates revisionNoYes
Visible to othersYes (optional)Yes
ReversibleEasy deleteNeed revert
Affects depotNoYes
Builds triggeredUsually noUsually yes

Basic Shelving

Shelve Changes

# Shelve all files in changelist
p4 shelve -c 12345

# Shelve specific files
p4 shelve -c 12345 file1.txt file2.txt

# Shelve and keep files open
p4 shelve -c 12345

# Shelve default changelist
p4 shelve

# Replace existing shelf
p4 shelve -f -c 12345

# Shelve with delete of local files (submit-like)
p4 shelve -c 12345
p4 revert -c 12345 //...

View Shelved Changes

# List shelved changelists
p4 changes -s shelved

# List your shelved changelists
p4 changes -s shelved -u $P4USER

# Describe shelved changelist
p4 describe -S 12345

# List files in shelf
p4 describe -S -s 12345

# Diff shelved file vs depot
p4 diff2 //depot/file.txt //depot/file.txt@=12345

Unshelve Changes

# Unshelve to same changelist
p4 unshelve -s 12345

# Unshelve to different changelist
p4 unshelve -s 12345 -c 12346

# Unshelve to new changelist
p4 unshelve -s 12345 -c default
# Then move to new CL if desired

# Unshelve specific files
p4 unshelve -s 12345 file.txt

# Force unshelve (overwrite local changes)
p4 unshelve -s 12345 -f

Delete Shelf

# Delete shelved files from changelist
p4 shelve -d -c 12345

# Delete specific files from shelf
p4 shelve -d -c 12345 file.txt

# Delete shelf completely
p4 shelve -d -c 12345 //...

# Promote shelf to commit (delete shelf after submit)
p4 submit -e 12345

Shelving Workflows

Work-in-Progress Backup

# End of day - shelve your work
p4 shelve -c 12345 -f

# Next day - continue working
# Files already open, shelf is backup

# If workspace lost, unshelve to recover
p4 unshelve -s 12345

Task Switching

# Working on Feature A (CL 12345)
# Urgent bug needs fixing

# Shelve Feature A work
p4 shelve -c 12345

# Revert local changes (keep shelf)
p4 revert -c 12345 //...

# Work on bug fix
p4 edit bugfile.cs
# ... fix bug ...
p4 submit -d "Fix critical bug"

# Resume Feature A
p4 unshelve -s 12345

Code Review Workflow

# Developer: Shelve for review
p4 shelve -c 12345
echo "Please review CL 12345"

# Reviewer: Get shelved changes to review workspace
p4 unshelve -s 12345 -c default

# Review code...

# Reviewer: Revert after review (or keep to test)
p4 revert //...

# Developer: After approval, submit
p4 submit -c 12345
p4 shelve -d -c 12345  # Clean up shelf

Share Between Workspaces

# Workspace A: Shelve changes
p4 shelve -c 12345

# Workspace B: Get shelved changes
# (in different workspace)
p4 unshelve -s 12345 -c default

# Now both workspaces have the changes

Pre-Integration Testing

# Shelve feature branch changes
p4 shelve -c 12345

# In integration workspace:
# Sync to main
p4 sync //depot/main/...

# Unshelve feature changes
p4 unshelve -s 12345

# Test integration
# ... run tests ...

# If tests pass, developer can submit
# If tests fail, developer can fix

Advanced Shelving

Shelve with Resolve

# When unshelving conflicts with current workspace

# Preview unshelve conflicts
p4 unshelve -n -s 12345

# Unshelve and resolve
p4 unshelve -s 12345
p4 resolve -am  # Auto-merge

# Or force overwrite
p4 unshelve -f -s 12345

Update Existing Shelf

# Make more changes
p4 edit file.txt
# ... edit file ...

# Update shelf with new changes
p4 shelve -f -c 12345

# -f (force) replaces existing shelf

Partial Shelving

# Shelve only some files from changelist
p4 shelve -c 12345 important.cs critical.cs

# Leave other files unshelved but still open

Shelve Across Streams

# Shelve in one stream
p4 shelve -c 12345

# Unshelve to different stream (if mappings allow)
# May need branch mapping
p4 unshelve -s 12345 -b branch_mapping

Shelf Management

Find Old Shelves

# Find your old shelves
p4 changes -s shelved -u $P4USER

# Find shelves older than 30 days
p4 changes -s shelved -u $P4USER | while read line; do
    CL=$(echo $line | awk '{print $2}')
    DATE=$(p4 change -o $CL | grep "^Date:" | awk '{print $2}')
    echo "$CL: $DATE"
done

Clean Up Old Shelves

#!/bin/bash
# cleanup-shelves.sh

# Delete shelves older than 30 days
CUTOFF=$(date -v-30d +%Y/%m/%d)

p4 changes -s shelved -u $P4USER | while read line; do
    CL=$(echo $line | awk '{print $2}')
    DATE=$(echo $line | awk '{print $4}')
    
    if [[ "$DATE" < "$CUTOFF" ]]; then
        echo "Deleting old shelf: $CL ($DATE)"
        p4 shelve -d -c $CL //...
    fi
done

Shelf Statistics

# Count files in shelf
p4 describe -S -s 12345 | grep "^\.\.\." | wc -l

# Size of shelved files
p4 describe -S -s 12345 | grep "^\.\.\." | while read line; do
    FILE=$(echo $line | awk '{print $1}')
    p4 fstat -Ol "$FILE@=$CL" 2>/dev/null | grep fileSize
done

Swarm Integration

Shelve for Swarm Review

# Create review-ready changelist
p4 change  # Add description with review info

# Shelve for Swarm
p4 shelve -c 12345

# Swarm automatically detects and creates review
# Or trigger manually:
# POST to Swarm API

Update Review

# Make changes based on feedback
p4 edit file.txt
# ... make changes ...

# Update shelf (triggers review update in Swarm)
p4 shelve -f -c 12345

Commit After Approval

# After review approved in Swarm
p4 submit -e 12345

# -e submits shelved files directly
# Cleans up shelf automatically

Best Practices

  1. Shelve frequently - Backup work in progress
  2. Use descriptive changelist names - Easy to identify shelves
  3. Clean up old shelves - Don't leave orphaned shelves
  4. Force update with -f when re-shelving
  5. Verify unshelve - Check files are correct
  6. Delete shelf after submit - Keep server clean
  7. Use for code review - Before committing
  8. Don't rely solely on shelves - Not a permanent backup
  9. Communicate shelf numbers - For collaboration
  10. Test unshelved code - Before submitting

Troubleshooting

IssueSolution
"Files not shelved"Check files are open in changelist
"Can't unshelve - conflicts"Use -f to force or resolve
"Shelf not found"Check changelist number, may be deleted
"No permission to unshelve"Check protections, may need owner
"Files differ"Use -f to replace or resolve
"Can't delete shelf"Must delete all files first

Common Commands Reference

# Shelve
p4 shelve -c CL                    # Shelve changelist
p4 shelve -f -c CL                 # Replace existing shelf
p4 shelve -d -c CL                 # Delete shelf

# Unshelve
p4 unshelve -s CL                  # Unshelve to same CL
p4 unshelve -s CL -c TARGET        # Unshelve to different CL
p4 unshelve -f -s CL               # Force unshelve

# View
p4 describe -S CL                  # View shelved changelist
p4 changes -s shelved              # List all shelves
p4 changes -s shelved -u USER      # List user's shelves

# Submit shelved
p4 submit -e CL                    # Submit shelf directly

Sponsors

Details

Marketplace
tjboudreaux/cc-plugin-perforce
Category
Development