| name | tools-p4-shelving |
| description | Perforce shelving for code review, sharing work-in-progress, backup, and collaboration workflows. |
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
p4 shelve -c 12345
p4 shelve -c 12345 file1.txt file2.txt
p4 shelve -c 12345
p4 shelve
p4 shelve -f -c 12345
p4 shelve -c 12345
p4 revert -c 12345 //...
View Shelved Changes
p4 changes -s shelved
p4 changes -s shelved -u $P4USER
p4 describe -S 12345
p4 describe -S -s 12345
p4 diff2 //depot/file.txt //depot/file.txt@=12345
Unshelve Changes
p4 unshelve -s 12345
p4 unshelve -s 12345 -c 12346
p4 unshelve -s 12345 -c default
p4 unshelve -s 12345 file.txt
p4 unshelve -s 12345 -f
Delete Shelf
p4 shelve -d -c 12345
p4 shelve -d -c 12345 file.txt
p4 shelve -d -c 12345 //...
p4 submit -e 12345
Shelving Workflows
Work-in-Progress Backup
p4 shelve -c 12345 -f
p4 unshelve -s 12345
Task Switching
p4 shelve -c 12345
p4 revert -c 12345 //...
p4 edit bugfile.cs
p4 submit -d "Fix critical bug"
p4 unshelve -s 12345
Code Review Workflow
p4 shelve -c 12345
echo "Please review CL 12345"
p4 unshelve -s 12345 -c default
p4 revert //...
p4 submit -c 12345
p4 shelve -d -c 12345
Share Between Workspaces
p4 shelve -c 12345
p4 unshelve -s 12345 -c default
Pre-Integration Testing
p4 shelve -c 12345
p4 sync //depot/main/...
p4 unshelve -s 12345
Advanced Shelving
Shelve with Resolve
p4 unshelve -n -s 12345
p4 unshelve -s 12345
p4 resolve -am
p4 unshelve -f -s 12345
Update Existing Shelf
p4 edit file.txt
p4 shelve -f -c 12345
Partial Shelving
p4 shelve -c 12345 important.cs critical.cs
Shelve Across Streams
p4 shelve -c 12345
p4 unshelve -s 12345 -b branch_mapping
Shelf Management
Find Old Shelves
p4 changes -s shelved -u $P4USER
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
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
p4 describe -S -s 12345 | grep "^\.\.\." | wc -l
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
p4 change
p4 shelve -c 12345
Update Review
p4 edit file.txt
p4 shelve -f -c 12345
Commit After Approval
p4 submit -e 12345
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
p4 shelve -c CL
p4 shelve -f -c CL
p4 shelve -d -c CL
p4 unshelve -s CL
p4 unshelve -s CL -c TARGET
p4 unshelve -f -s CL
p4 describe -S CL
p4 changes -s shelved
p4 changes -s shelved -u USER
p4 submit -e CL