Perforce 2004.2 User's Guide


<< Previous Chapter Perforce Basics: Miscellaneous Topics	Table of Contents Index Perforce on the Web	Next Chapter >> Labels

Chapter 7
Changelists

A Perforce changelist is a list of files, their revision numbers, and operations to be performed on these files. You add files to a changelist with commands such as p4 add filenames or p4 edit filenames, and the changed files are stored in the depot when you submit the changelist with p4 submit.

When you submit a changelist to the depot, the depot is updated atomically: either all of the files in the changelist are updated in the depot, or none of them are. This grouping of files as a single unit guarantees that all files grouped together in a changelist are updated simultaneously. A Perforce changelist is an atomic change transaction.

Perforce attempts to make working with changelists as transparent as possible. Perforce commands such as p4 edit add the affected files to the default changelist, and p4 submit sends the default changelist to the server for processing. Sometimes, the default changelist is not sufficient, and you must use a numbered changelist. Use numbered changelist when:

You are working on two or more unrelated changes at the same time.

For example, suppose you're fixing two bugs, each of which affects a separate set of files. Rather than submit the fixes to both bugs in a single changelist, you might create one changelist for the files that fix the first bug, and a second changelist for the files that fix the second bug, and use two p4 submit commands to submit your work to the depot.

The p4 submit command fails.

For example, if you are working on a file in the default changelist, but another user has locked the file, or submitted a changelist that affects your file, your submit fails. Whenever 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 assigned number.

Working with the Default Changelist

A changelist is a list of files, revision numbers of those files, and operations to be performed on those files. For example, a single changelist might contain the following:


`/doc/elm-help.1 revision 3 edit /utils/elmalias.c revision 2 delete`

Each file in a changelist is said to be open in the client workspace and in the changelist: the first file in the example is open for edit, and the second file is open for deletion.

The depot is updated with the files in the changelist when you call p4 submit to send your changes to the Perforce server.

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, operate on the default changelist. For example, if you type p4 add filename, this file is added to the default changelist.

When you type p4 submit, a change form is displayed, showing the files in the default changelist. In order to submit a changelist, you must also supply a description of the changes being made. When you save the p4 submit form, the files shown in the form are submitted to the server and the server attempts to update the files in the depot.

If there are no problems with the submission, the changelist is assigned a sequential number, and its status changes from new or pending to submitted. Any files you removed from the default changelist by editing the p4 submit form reappear in a new default changelist. After a changelist has been submitted, it becomes a permanent part of the depot's metadata, and is unchangeable except by Perforce administrators.

Creating Numbered Changelists Manually

You can create a numbered changelist manually by using the p4 change command. This command brings up the same form that you see during p4 submit.

All files in the default changelist are included in the new changelist. When you exit the form, the new changelist is assigned the next changelist number in sequence, and the changelist must be subsequently referred to by this change number. You can delete files from the changelist by editing the p4 change form; files deleted from the new changelist reappear in the default changelist. The status for a changelist created by the p4 change command is pending until you submit the changelist.

Files in your workspace may appear in only one pending changelist at a time.

Working With Numbered Changelists

To add files to numbered changelists (as opposed to the default changelist), use the -c changenum flag when you use Perforce commands such as p4 edit filename. For example, if you have just created a changelist 34, use p4 edit -c 34 filename to add filename to pending changelist 34.

You can move files from one changelist to another with p4 reopen -c changenum filename, where changenum is the number of the moving-to changelist. To move a file from a numbered changelist to the default changelist, use p4 reopen -c default filename.

Example:

Working with multiple changelists.

Ed is working on two bug fixes simultaneously. One of the bugs involves mail filtering and requires updates of files in the filter subdirectory; the other problem is in the aliasing system, and requires an update of utils/elmalias.c.

Ed wants to fix each bug in its own changelist; doing so enables 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: <enter description here> Files: //depot/elm_proj/filter/filter.c # edit //depot/elm_proj/filter/lock.c # edit //depot/elm_proj/utils/elmalias.c # edit

`Change: new Client: eds_elm User: edk Status: new Description: <enter description here> Files: //depot/elm_proj/filter/filter.c # edit //depot/elm_proj/filter/lock.c # edit //depot/elm_proj/utils/elmalias.c # edit`

Ed wants to use this changelist to submit only the fix to the filter problems. He changes the form, deleting the last file revision from the file list. When he's done, the form looks like this:

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

When he quits from the editor, he's told

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, and realizes that the filter problem requires 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, and because the affected files are in the default changelist, he submits the default changelist with p4 submit and no arguments. When Ed finishes fixing the filtering bug, he submits that changelist with p4 submit -c 29.

Automatic Creation and Renumbering of Changelists

Changelist submission can fail for a number of reasons:

A file in the changelist has been locked by another user with p4 lock.
Your client workspace no longer contains a file included in the changelist.
There is a server error, such as not enough disk space.
You were not editing the head revision of a particular file. (If another user submits a change to a file you're working on, the revision in your client workspace is no longer the head revision.)

If any of the files in a changelist is rejected for any reason, the entire changelist is backed out, and none of the files in the changelist are updated in the depot. If the submitted changelist was the default changelist, the Perforce server assigns the next available changelist number to the changelist, and this change number must be used to refer to the changelist in the future. Perforce also locks the files to prevent others from changing them while you resolve the reason for the failed submit.

If a submit fails because your revision of the file is not the head revision, this is called a file conflict. You must resolve the conflict before the changelist can be accepted. (For details, see Chapter 5, Perforce Basics: Resolving File Conflicts).

When Perforce renumbers changelists

The changelist numbers of submitted changelists always reflect the order in which changelists were submitted to the depot. Whenever a numbered changelist is submitted out of sequence, the server automatically renumbers the changelist to reflect the order in which changelists were submitted.

Example:

Automatic renumbering of changelists

Ed has finished fixing the filtering bug that he's been working on in numbered changelist 29. After Ed created that changelist, he submitted another changelist (change 30), and two other users have also submitted changelists. Ed submits change 29 with p4 submit -c 29, and is informed of a changelist renumbering as follows:

Change 29 renamed change 33 and submitted.

Deleting Changelists

To remove a pending changelist that has no files or jobs associated with it, use p4 change -d changenum. You must remove all files and jobs from a pending changelist before you can delete it. Use p4 reopen to move files to another changelist, p4 revert to remove files from the changelist (and to revert them back to their old versions), and p4 fix -d to remove jobs from the changelist.

Changelists that have already been submitted can be deleted by a Perforce administrator only under very specific circumstances. Please see the Perforce System Administrator's Guide for more information.

Changelist Reporting

The two reporting commands associated with changelists are p4 changes and p4 describe. Use p4 changes to obtain lists of changelists with short descriptions, and p4 describe to obtain verbose information pertaining to a specified changelist.


Command	Meaning
`p4 changes`	Displays a list of all pending and submitted changelists, one line per changelist, and an abbreviated description.
`p4 changes -m count`	Limits the number of changelists reported on to the last `count` changelists.
`p4 changes -s status`	Limits the list to those changelists with a particular status; for example, `p4 changes -s submitted` will list only already submitted changelists.
`p4 changes -u user`	Limits the list to those changelists submitted by a particular user.
`p4 changes -c workspace`	Limits the list to those changelists submitted from a particular client workspace.
`p4 describe changenum`	Displays full information about a single changelist. If the changelist has already been submitted, the report includes a list of affected files and the diffs of these files. (You can use the `-s` flag to exclude the file diffs.)