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
| Feature | Shelving | Submitting |
|---|
| Stored on server | Yes | Yes |
| Creates revision | No | Yes |
| Visible to others | Yes (optional) | Yes |
| Reversible | Easy delete | Need revert |
| Affects depot | No | Yes |
| Builds triggered | Usually no | Usually 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
- Shelve frequently - Backup work in progress
- Use descriptive changelist names - Easy to identify shelves
- Clean up old shelves - Don't leave orphaned shelves
- Force update with
-f when re-shelving - Verify unshelve - Check files are correct
- Delete shelf after submit - Keep server clean
- Use for code review - Before committing
- Don't rely solely on shelves - Not a permanent backup
- Communicate shelf numbers - For collaboration
- Test unshelved code - Before submitting
Troubleshooting
| Issue | Solution |
|---|
| "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
