| name | tools-p4-changelist |
| description | Perforce changelist management including creating, editing, moving files between changelists, and pending change workflows. |
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
| Type | Description |
|---|
| Default | Auto-created changelist for quick edits |
| Numbered | Named changelist with description |
| Pending | Not yet submitted |
| Submitted | Already committed to depot |
| Shelved | Changes stored on server, not submitted |
Creating Changelists
Create New Changelist
p4 change
p4 change -o | sed 's/<enter description here>/Fix player movement/' | p4 change -i
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
p4 changes -s pending -u $P4USER
p4 changes -s pending //depot/project/...
p4 changes -s submitted -m 20 //depot/project/...
p4 changes -u john.doe -m 10
p4 changes -s submitted @2024/01/01,@2024/01/31
p4 changes -l -m 10 //depot/project/...
View Specific Changelist
p4 describe 12345
p4 describe -s 12345
p4 describe -S 12345
p4 change -o 12345
Editing Changelists
Modify Changelist Description
p4 change 12345
p4 change -o 12345 | sed 's/old description/new description/' | p4 change -i
Change Changelist Owner
p4 change -o 12345 | sed 's/User:.*/User: new_owner/' | p4 change -i -f
Moving Files Between Changelists
Reopen Files to Different Changelist
p4 reopen -c 12345 file.txt
p4 reopen -c default file.txt
p4 reopen -c 12346 //...@=12345
p4 reopen -c 12345 *.cs
Split Changelist
p4 change
p4 reopen -c NEW_CL file1.txt file2.txt
p4 opened -c 12345
p4 opened -c NEW_CL
Merge Changelists
p4 reopen -c 12345 //...@=12346
p4 change -d 12346
Default Changelist
Working with Default Changelist
p4 opened -c default
p4 edit file.txt
p4 reopen -c 12345 file.txt
p4 submit
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
p4 change -d 12345
p4 revert -c 12345 //...
p4 change -d 12345
p4 reopen -c default //...@=12345
p4 change -d 12345
p4 change -d -f 12345
Fix Submitted Changelist Description
p4 change -o 12345 | sed 's/typo/fixed/' | p4 change -i -f -u
Changelist Workflow Patterns
Feature Branch Pattern
p4 change -o | sed 's/<enter description here>/Feature: Player Dash Ability/' | p4 change -i
p4 edit -c 12345 Player.cs
p4 edit -c 12345 PlayerAbilities.cs
p4 add -c 12345 DashAbility.cs
p4 submit -c 12345
Bug Fix Pattern
p4 edit BuggyFile.cs
p4 submit -d "Fix: Null reference in PlayerController"
Multiple Tasks Pattern
p4 change
p4 change
p4 edit -c TASK_A_CL FileA.cs
p4 edit -c TASK_B_CL FileB.cs
p4 submit -c TASK_A_CL
Work In Progress Pattern
WIP_CL=$(p4 change -o | sed 's/<enter description here>/WIP: Do not submit/' | p4 change -i | grep -o '[0-9]*')
p4 edit -c $WIP_CL experimental.cs
p4 change $WIP_CL
p4 submit -c $WIP_CL
Querying Changelists
Search Changelists
p4 changes -l //depot/... | grep -B5 "player"
p4 changes //depot/project/Player.cs
p4 changes -u $P4USER -s submitted @$(date -v-7d +%Y/%m/%d),@now
p4 changes -s submitted -m 1000 //depot/project/... | awk '{print $6}' | sort | uniq -c | sort -rn
Changelist Statistics
p4 describe -s 12345 | grep "^\.\.\." | wc -l
p4 describe 12345 | grep "^@@" | wc -l
p4 describe -s 12345 | grep "^\.\.\." | sed 's/.*#//' | sort | uniq -c
Integration with Workflows
Pre-Submit Checklist
#!/bin/bash
CL=$1
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
FILES=$(p4 opened -c $CL 2>/dev/null | wc -l)
if [ "$FILES" -eq 0 ]; then
echo "ERROR: No files in changelist"
exit 1
fi
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
cat << 'EOF' | p4 change -i
Change: new
Description:
[TYPE]: Brief description
- Change 1
- Change 2
- [ ] Unit tests pass
- [ ] Manual testing done
- Jira: GOD-XXXX
EOF
Best Practices
- Use numbered changelists for any non-trivial work
- Write descriptive descriptions - What and why
- One logical change per changelist - Atomic commits
- Don't mix refactoring with features - Separate CLs
- Prefix WIP changelists to prevent accidental submit
- Review before submit with
p4 describe -s
- Keep changelists small - Easier review and rollback
- Use consistent naming - Team conventions
- Link to issue tracker in description
- Clean up empty changelists regularly
Troubleshooting
| Issue | Solution |
|---|
| "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 changelist | Use p4 reopen -c |
| Lost changelist number | p4 changes -s pending -u $USER |
| Description too long | Some triggers limit length |