# Tools P4 Changelist

> Perforce changelist management including creating, editing, moving files between changelists, and pending change workflows.

- Skill: `tjboudreaux/tools-p4-changelist` (Agent Skill)
- Install (CLI): `npx skillmds@latest add tjboudreaux/tools-p4-changelist`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tjboudreaux/tools-p4-changelist/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tjboudreaux (https://skillmd.com/u/tjboudreaux)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tjboudreaux/tools-p4-changelist

---


# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

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

### Multiple Tasks Pattern

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
#!/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

```bash
# 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

| 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 |