A Perforce changelist is a list of files, their revision numbers, and operations to be performed on these files. Commands such as
p4 add filenames and p4 edit filenames include the affected files in a changelist; the depot is not actually altered until the changelist is submitted with p4 submit. p4 edit add the affected files to a default changelist (called, appropriately enough, the default changelist), and p4 submit sends the default changelist to the server for processing. But there are two sets of circumstances that would require the user to understand and manipulate non-default changelists:
p4 submit's.
p4 submit command can fail. For example, if one user has a file locked and another user submits a changelist that contains that file, the submit will fail. When a submit of the default changelist fails, the changelist is assigned a number, is no longer the default changelist, and must be referred to by its number.
/doc/elm-help.1 revision 3 edit
The only way of changing files in the depot is with
p4 submit. This command sends a changelist to the server; the server looks at the files contained in the changelist and alters the depot accordingly.The commands that add or remove files from changelists are:
p4 add | p4 delete |
p4 edit | p4 integrate |
p4 reopen | p4 revert |
By default, these commands, and p4 submit, act on the default changelist; for example, if a user types
p4 add filename, this file is added to the default changelist. When a user types p4 submit, the default changelist is submitted.p4 submit is typed, a change form is displayed that contains the files in the default changelist. Any file can be deleted from this list; when a file is deleted, it is moved to the next default changelist, and will appear again the next time p4 submit is typed. A changelist must contain a user-entered description, which should describe the nature of the changes being made.p4 submit form, the changelist is submitted to the server and the server attempts to update the files in the depot. If there are no problems, the changelist is assigned a sequential number, and its status changes from new or pending to submitted. Once a changelist has been submitted, it becomes a permanent part of the depot's metadata, and is absolutely unchangeable. Creating Numbered Changelists Manually
A user can create a changelist in advance of submission with p4 change. This command brings up the same form seen during p4 submit. All files in the default changelist are moved to this new changelist; when the user quits from the form, the changelist is assigned the next changelist number in sequence, and this changelist must be referred to from this point on by this change number. Files can be deleted from the changelist by editing the form; files deleted from this changelist are moved to the next default changelist. The status for a changelist created by this method is pending until the form is submitted. Working With Numbered Changelists
Commands like p4 edit filename, which by default puts the file in the default changelist, can be used to append a file to a pending numbered changelist with the p4 change -c changenum flag. For example, to edit a file and submit it in change number 4, use p4 edit -c 4 filename.p4 reopen -c changenum filenames, where changenum is the number of the moving-to changelist. If files are being moved to the default changelist, use p4 reopen -c default filenames.utils/elmalias.c. Ed wants to update each bug separately in the depot; this will allow him to refer to one bug fix by one change number and the other bug fix by another change number. He's already started fixing both bugs, and has opened some of the affected files for edit. He types p4 change, and sees
Change: new
Client: eds_elm
User: edk
Status: new
Description:
Fixes filtering problems
Files:
//depot/elm_proj/filter/filter.c # edit
//depot/elm_proj/filter/lock.c # edit
Change 29 created with 2 open file(s).The file that he removed from the list,
utils/elmalias.c, is now found in the default changelist. He could include that file in another numbered changelist, but decides to leave it where it is.He fixes both bugs at his leisure. He realizes that the filter problem will require updates to another file:
filter/lock.c. He opens this file for edit with p4 edit -c 29 filter/lock.c; opening the file with the -c 29 flag puts the file in changelist 29, which he created above. (If the file had already been open for edit in the default changelist, he could have moved it to changelist 29 with p4 reopen -c 29 filter/lock.c).Ed finishes fixing the aliasing bug; since the affected files are in the default changelist, he submits the changelist with a straightforward
p4 submit. He'll finish fixing the filtering bug later.
p4 lock;
p4 edit //depot/somefile;If the submit failed because the client-owned revision of the file is not the head revision, a merge must be performed before the changelist will be accepted.
Ed has finished fixing the filtering bug that he's been using changelist
29 for. Since he created that changelist, he's since submitted another changelist (change 30), and two other users have submitted changelists. Ed submits change 29 with p4 submit -c 29, and is told
Change 29 renamed change 33 and submitted.All submitted changelists are numbered in the order in which they were submitted.
p4 change -d changenum. Pending changelists that contain files or jobs must have the files and jobs removed from them before they can be deleted: use p4 reopen to move files to another changelist, p4 revert to remove files from the changelist (and revert them back to their old versions), or p4 fix -d to remove jobs from the changelist.Submitted changelists can never be deleted.
p4 changes and p4 describe. The former is used to view lists of changelists with short descriptions; the latter prints verbose information for a single changelist.