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

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