Perforce 2003.2 User's Guide | ||
<< Previous Chapter Perforce Basics: Miscellaneous Topics |
Table of Contents Index Perforce on the Web |
Next Chapter >> Labels |
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:
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:
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.
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.
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.
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 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
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 |
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 at his leisure. He 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, 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.
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).
Ed has finished fixing the filtering bug that he's been using changelist 29 for. Since he created
that changelist, he's 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.
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.
Perforce 2003.2 User's Guide | ||
<< Previous Chapter Perforce Basics: Miscellaneous Topics |
Table of Contents Index Perforce on the Web |
Next Chapter >> Labels |