Perforce changelists: check out, shelve, resolve and submit

What a Perforce changelist is, and why submits fail

In Perforce, every file you check out, add or delete goes into a pending changelist. A changelist is a numbered bundle of file operations plus a description. When you submit it, all its files become new revisions on the server together, in one atomic step: either every file is submitted or none is.

• The default changelist is where files land when you do not choose one. It has no number until you submit it; Perforce assigns one at that moment.
• Numbered changelists are ones you create yourself to separate pieces of work, for example one for a lighting pass and one for a bug fix, so each can be submitted on its own.
• A shelf is a copy of the files in a pending changelist stored on the server without submitting them. The files stay checked out in your workspace. Shelving is a backup of work in progress, and a way to hand it to a teammate for review.
• A resolve is needed when someone submitted a newer revision of a file you have open. Perforce will not let you submit over it until you decide how to combine the two versions.

Submits fail for predictable reasons: a file in the changelist is out of date and needs a resolve, a teammate holds a lock on one of the files, a file opened for add was deleted from disk, or the Unreal Editor still has a file open so it cannot be read. Found at the end of a large upload, each of these costs time. Found before the submit, each is a quick fix.

Perforce's references for p4 submit and p4 shelve cover the full command options.

How Gameheim handles changelists, shelves and submits

On the P4 Workspace page, two panels hold your pending work. Opened Files lists every file you have open, with a tab per changelist, search, and actions on a selection: Move to…, Lock, Shelve and Revert. Pending Changelists shows one card per changelist with its file count and transfer size, and the actions Submit, View, Edit, Shelve, Unshelve and Delete CL.

When an action needs a changelist, Gameheim asks which one: the Default changelist, an existing one, or Create new changelist. Tick Remember this choice for this session to stop being asked.

A submit in three steps

1. Compose. A dialog collects the Description, the tasks to link with Link tasks, and, if AI is available to you, a generated description draft.
2. Check. Gameheim runs a read-only pre-submit check on every file in the changelist and shows what will be transferred: files added, modified and deleted, the total size, an estimated upload time and the heaviest files.
3. Confirm. Nothing reaches the depot until you press Submit. If the check found only warnings, the button reads Submit Anyway. If it found a blocker, fix it first.

Task references that update the board

A changelist description can reference tasks by key, and the task board updates when the submit completes. You do not have to type the syntax: tasks picked in Link tasks are written into the description for you, at the end, where the server reads them.

How to organise, shelve and submit a changelist in Gameheim

1. 1

   Create a changelist for the piece of work

   In Pending Changelists, click New CL, type a description and click Create. Keep one changelist per logical change: it makes review easier and lets you submit one piece without the other.

2. 2

   Put the right files in it

   Files you check out, add or mark for delete from Workspace Changes go into the changelist you choose. To reorganise, select files in Opened Files and use Move to…. To drop a file you opened by mistake, Revert Unchanged reverts every open file you did not actually modify.

3. 3

   Shelve work in progress

   Click Shelve on the changelist card (or select files in Opened Files and click Shelve). A copy of the files goes to the server; they stay checked out on your machine. The card shows a Shelved badge, and Shelved in Opened Files lists your shelved changelists, where you can Unshelve or Delete a shelf.

   Tip:Shelving before you leave for the day protects unsubmitted work against a disk failure, and lets a lead look at it without it reaching the depot.
4. 4

   Open the submit dialog and describe the change

   Click Submit on the changelist card. Write the Description: what changed and why, in words a teammate will understand in six months. A description is required, and it is limited to 10,000 characters.

5. 5

   Link the tasks you worked on

   Under Link tasks, search for tasks in the project and add them. For each one choose Link only, Progress with a percentage, or Completed. Gameheim appends the matching tokens to the end of the description.

6. 6

   Optionally generate the description with AI

   In Generate with AI, pick a description template, write a couple of lines about what you did, and click Generate. The draft is built from your notes, the list of files in the changelist and the linked tasks, and it fills the description box for you to review and edit. Nothing is submitted until you confirm.

7. 7

   Read the pre-submit check

   Click Submit in the dialog. Gameheim checks every file in the changelist without modifying anything. All clear means no conflicts were found. Otherwise each problem is listed with the fix available: sync, resolve, remove from the changelist, or contact a lock holder. Use Re-check after fixing.

8. 8

   Resolve conflicts, then submit

   For files marked Needs resolve, choose a strategy per file and click the resolve button. Binary files such as .uasset are tagged BINARY and accept only Accept Theirs or Accept Yours. When the check is clean, press Submit. The operation appears in Agent Operations, and your tasks update when it completes.

How to organise, shelve, resolve and submit by hand with p4

The same workflow from the command line. P4V offers each step from the right-click menu of a pending changelist or file.

1. Organise the work in changelists

p4 change
p4 edit -c 1234 //depot/MyGame/Content/Maps/Level01.umap
p4 reopen -c 1235 //depot/MyGame/Config/DefaultGame.ini
p4 revert -a -c 1234 //...
p4 opened -c 1234

p4 change prints the number of the new changelist when you save the form. p4 reopen -c moves files that are already open into another changelist. p4 revert -a reverts only the files you opened but did not modify.

2. Shelve work in progress

p4 shelve -c 1234
p4 shelve -r -c 1234
p4 describe -S 1234
p4 unshelve -s 1234 -c 1240
p4 shelve -d -c 1234

-r replaces the whole shelf with the files currently open in the changelist. p4 describe -S lists what is on the shelf. A teammate reviews a shelf with p4 unshelve -s into a changelist of their own workspace, and the shelf stays on the server until its owner deletes it with p4 shelve -d.

3. Check the changelist before submitting

p4 sync //depot/MyGame/...
p4 resolve -n
p4 opened -a //depot/MyGame/Content/Maps/Level01.umap

• Syncing before a submit brings in teammates' newer revisions. Files you have open that changed on the server are scheduled for resolve instead of overwritten.
• p4 resolve -n lists the files that still need a resolve, without resolving anything.
• p4 opened -a on a file shows whether someone else has it open or locked.
• Check that every file opened for add still exists on disk, and close the Unreal Editor or save and close the assets you are submitting.

4. Resolve

p4 resolve -am //depot/MyGame/Source/...
p4 resolve -at //depot/MyGame/Content/Props/Crate.uasset
p4 resolve -ay //depot/MyGame/Content/Props/Barrel.uasset
p4 resolve

-am merges text files automatically and leaves real conflicts unresolved. -at takes the server version and -ay keeps yours. Plain p4 resolve goes through the files one by one and lets you open a merge tool for text files. For binary assets only -at and -ay make sense.

5. Submit

p4 submit -c 1234
p4 submit -d "Fix crate collision #DQ-12 done"

p4 submit -c opens the form so you can review the description first. -d gives the description on the command line and works only for the default changelist. If a submit fails, the files stay open in a pending changelist; for the default changelist Perforce moves them into a new numbered one and tells you its number, so you can fix the problem and run p4 submit -c with it.

By hand and in Gameheim

Task reference syntax in changelist descriptions

Task keys are the project code plus a number, for example DQ-12. Gameheim recognises three forms, in any case:

• Only keys with this project's code are applied. A key from another project stays plain text.
• If the same task appears more than once, the strongest instruction wins: done beats any progress, and the higher percentage beats the lower.
• Task updates happen for submits made from Gameheim. The person submitting needs permission to edit tasks (tasks:write); otherwise the submit goes through and the tasks are left unchanged.
• Bug and decision keys can also be referenced in a description. See Bug tracking for game development and Game design decision log.

Pre-submit check: what each problem means

If a submit fails after starting, the changelist card shows Resolve and the dialog reopens with the same categories, plus Retry submit.

Resolve strategies explained

Conflicts found after a sync also appear in the Sync Status panel under Conflicts to Resolve, with Theirs, Mine, Auto, Merge and Revert per file and Auto Resolve All for the whole list. Merge opens a three-way merge editor in a browser window, served by the agent on your own computer, so the file contents stay on your machine.

Undoing work safely: revert, remove, delete

AI description templates

A template defines the structure, tone and language the AI follows for a project. It is a format specification, not a form to fill in. The built-in tags are {summary}, {notes}, {changes}, {files} and {tasks}; you can add custom tags with your own instruction, such as a {risks} tag that lists possible regressions. Open Manage templates from the template picker to create one, and mark one as the project default with Preselect this template for the project. Until a template exists, a built-in default is used. Task tokens are always added by the picker, never by the AI.

More on AI features in Gameheim: AI assistants for game projects.

Frequently asked questions