Perforce 2003.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. 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.

When a changelist is submitted 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 code alterations spanning multiple files are updated in the depot simultaneously. To reflect the atomic nature of changelist submissions, submission of a changelist is sometimes called an atomic change transaction.

Perforce attempts to make changelist usage as transparent as possible: in the normal case, 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. However, there are two sets of circumstances that would require the user to understand and manipulate non-default changelists:

For example, suppose a user is fixing two bugs, each of which spans a separate set of files. Rather than submit the fixes to both bugs in a single changelist, the user might elect to create one changelist for the files that fix the first bug, and another changelist for the files that fix the second bug. Each changelist would be submitted to the depot via separate p4 submit operations.

For example, if one user has a file locked and another user submits a changelist that contains that file, the submit fails. 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.

In the above circumstances, the user must understand how to work with numbered changelists.

Working with the Default Changelist

Note

The material in this subsection has already been presented in a slightly different form in earlier chapters. It is presented again here to provide a complete discussion of changelists.

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 of the files in the changelist is said to be open within the client workspace: the first of the files above was opened for edit with p4 edit, and the second was opened for deletion with p4 delete.

The files in the changelist are updated within the depot with p4 submit, which sends the changelist to the server; the server processes 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 you type p4 add filename, this file is added to the default changelist. When you type p4 submit, the default changelist is submitted.

When you type p4 submit, a change form is displayed, containing 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 you type p4 submit. A changelist must contain a user-entered description, which describes the nature of the changes being made.

p4 submit can take an optional, single file pattern as an argument. In this case, only those files in the default changelist that match the file pattern are included in the submitted changelist. Since the p4d server program must receive this file pattern as a single argument, make sure to escape the * wildcard if it is used.

When the user quits from the p4 submit editor, 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 unchangeable except by Perforce administrators.

Creating Numbered Changelists Manually

A user can create a changelist in advance of submission with p4 change. This command brings up the same form that you see during p4 submit.

All files in the default changelist are moved to this new changelist. When you quit from the form, the changelist is assigned the next changelist number in sequence, and this changelist must be subsequently referred to 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 you submit the files in the changelist.

Any single client file can be included in only one pending changelist.

Working With Numbered Changelists

You can use commands such as p4 edit filename, which by default adds the files to the default changelist, to append a file to a pending numbered changelist with the -c changenum flag. For example, to edit a file and submit it in changelist number 4, use p4 edit -c 4 filename.

You can move files from one changelist to another with p4 reopen -c changenum filenames, where changenum is the number of the moving-to changelist. If you are moving files to the default changelist, use p4 reopen -c default filenames.

Automatic Creation and Renumbering of Changelists

When submit of the default changelist fails,
the changelist is assigned a number

Submits of changelists occasionally fail. This can happen for a number of reasons:

User A's submit is rejected, since the file revision of file1.c that he edited is no longer the head revision of that file.

If any file 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, Perforce assigns the changelist the next change number in sequence, and this change number must be used from this point on to refer to the changelist. Perforce also locks the files to prevent others from changing them while the user resolves the reason for the failed submit.

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. (File merging is described in Chapter 5, Perforce Basics: Resolving File Conflicts).

Perforce May Renumber a Changelist upon Submission

The change numbers of submitted changelists always reflect the order in which the changelists were submitted. Thus, when a changelist is submitted, it may be renumbered.

Deleting Changelists

To remove a pending changelist that has no files or jobs associated with it, use p4 change -d changenum. Pending changelists that contain open 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.

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. The former is used to view lists of changelists with short descriptions, while the latter prints verbose information for a single 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.)


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

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