Perforce 2005.1 User's Guide
<< Previous Chapter
Perforce Basics:
Miscellaneous Topics

Table of Contents
Perforce on the Web
Next Chapter >>

Chapter 7

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:

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.

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.

Automatic Creation and Renumbering of Changelists

Changelist submission can fail for a number of reasons:

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.

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.


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

Perforce 2005.1 User's Guide
<< Previous Chapter
Perforce Basics:
Miscellaneous Topics

Table of Contents
Perforce on the Web
Next Chapter >>
Please send comments and questions about this manual to [email protected].
Copyright 1997-2005 Perforce Software. All rights reserved.
Last updated: 05/12/05