Perforce 2008.1 P4 User's Guide
<< Previous Chapter
Issuing P4 Commands
Table of Contents
Index
Perforce on the Web
Next Chapter >>
Resolving Conflicts

Chapter 4
Managing Files and Changelists

This chapter tells you how to manage files and work in a team development environment, where multiple users who are working on the same files might need to reconcile their changes.

Managing files

To change files in the depot (file repository), you open the files in changelists and submit the changelists with a description of your changes. Perforce assigns numbers to changelists and maintains the revision history of your files. This approach enables you to group related changes and find out who changed a file and why and when it was changed. Here are the basic steps for working with files.

Task
Description

Syncing (retrieving files from the depot)

Issue the p4 sync command, specifying the files and directories you want to retrieve from the depot. You can only sync files that are mapped in your client view.

Adding files to the depot

  1. Create the file in the workspace.

  2. Open the file for add in a changelist (p4 add).

  3. Submit the changelist (p4 submit).

Editing files and checking in changes

  1. If necessary, sync the desired file revision to your workspace (p4 sync).

  2. Open the file for edit in a changelist (p4 edit).

  3. Make your changes.

  4. Submit the changelist (p4 submit). To discard changes, issue the p4 revert command.

Deleting files from the depot

  1. Open the file for delete in a changelist (p4 delete). The file is deleted from your workspace.

  2. Submit the changelist (p4 submit). The file is deleted from the depot.

Discarding changes

Revert the files or the changelist in which the files are open. Reverting has the following effects on open files:

Add: no effect--the file remains in your workspace.

Edit: the revision you opened is resynced from the depot, overwriting any changes you made to the file in your workspace.

Delete: the file is resynced to your workspace.

Files are added to, deleted from, or updated in the depot only when you successfully submit the pending changelist in which the files are open. A changelist can contain a mixture of files open for add, edit and delete.

For details about the syntax that you use to specify files on the command line, refer to "Specifying filenames on the command line" on page 40. The following sections provide more details about working with files.

Syncing (retrieving) files

To retrieve files from the depot into your client workspace, issue the p4 sync command. You cannot sync files that are not in your client view. For details about specifying client views, see "Refining client views" on page 24.

The p4 sync command adds, updates, or deletes files in the client workspace to bring the workspace contents into agreement with the depot. If a file exists within a particular subdirectory in the depot, but that directory does not exist in the client workspace, the directory is created in the client workspace when you sync the file. If a file has been deleted from the depot, p4 sync deletes it from the client workspace.

To sync revisions of files prior to the latest revision in the depot, use revision specifiers. For example, to sync the first revision of Jamfile, which has multiple revisions, issue the following command:

For more details, refer to "Specifying file revisions" on page 44.

To sync groups of files or entire directories, use wildcards. For example, to sync everything in and below the "jam" folder, issue the following command:

For more details, see "Perforce wildcards" on page 41.

The Perforce server tracks the revisions that you sync (in a database located on the server machine). For maximum efficiency, Perforce does not resync an already-synced file revision. To resync files you (perhaps inadvertently) deleted manually, specify the -f flag when you issue the p4 sync command.

Adding files

To add files to the depot, create the files in your workspace, then issue the p4 add command. The p4 add command opens the files for add in the default pending changelist. The files are added when you successfully submit the default pending changelist. You can open multiple files for add using a single p4 add command by using wildcards. You cannot use the Perforce ...wildcard to add files recursively.

For platform-specific details about adding files recursively (meaning files in subdirectories), see Tech Note 12 on the Perforce web site:

You must enter a description in the Description: field. You can delete lines from the Files: field. Any files deleted from this list are moved to the next default changelist, and are listed the next time you submit the default changelist.

If you are adding a file to a directory that does not exist in the depot, the depot directory is created when you successfully submit the changelist.

Changing files

To open a file for edit, issue the p4 edit command. When you open a file for edit, Perforce enables write permission for the file in your workspace and adds the file to a changelist. If the file is in the depot but not in your workspace, you must sync it before you open it for edit. You must open a file for edit before you attempt to edit the file.

Discarding changes (reverting)

To remove an open file from a changelist and discard any changes you made, issue the p4 revert command. When you revert a file, the Perforce server restores the last version you synced to your workspace. If you revert a file that is open for add, the file is removed from the changelist but is not deleted from your workspace.

To preview the results of a revert operation without actually reverting files, specify the -n flag when you issue the p4 revert command.

Deleting files

To delete files from the depot, you open them for delete by issuing the p4 delete command, then submit the changelist in which they are open. When you delete a file from the depot, previous revisions remain, and a new head revision is added, marked as "deleted." You can still sync previous revisions of the file.

When you issue the p4 delete command, the files are deleted from your workspace but not from the depot. If you revert files that are open for delete, they are restored to your workspace. When you successfully submit the changelist in which they are open, the files are deleted from the depot.

Managing changelists

To change files in the depot, you open them in a changelist, make any changes to the files, and then submit the changelist. A changelist contains a list of files, their revision numbers, and the operations to be performed on the files. Unsubmitted changelists are referred to as pending changelists.

Submission of changelists is an all-or-nothing operation; that is, either all of the files in the changelist are updated in the depot, or, if an error occurs, none of them are. This approach guarantees that code alterations that affect multiple files occur simultaneously.

Perforce assigns numbers to changelists and also maintains a default changelist, which is numbered when you submit it. You can create multiple changelists to organize your work. For example, one changelist might contain files that are changed to implement a new feature, and another changelist might contain a bug fix. When you open a file, it is placed in the default changelist unless you specify an existing changelist number on the command line using the -c flag. For example, to edit a file and submit it in changelist number 4, use p4 edit -c 4 filename. To open a file in the default changelist, omit the
-c flag

The Perforce server might renumber a changelist when you submit it, depending on other users' activities; if your changelist is renumbered, its original number is never reassigned to another changelist.

The commands that add or remove files from changelists are:

To submit a numbered changelist, specify the -c flag when you issue the p4 submit command. To submit the default changelist, omit the -c flag. For details, refer to the p4 submit command description in the Perforce Command Reference.

To move files from one changelist to another, issue the p4 reopen -c changenum filenames command, where changenum specifies the number of the target changelist. If you are moving files to the default changelist, use p4 reopen -c default filenames.

Creating numbered changelists

To create a numbered changelist, issue the p4 change command. This command displays the changelist form. Enter a description and make any desired changes; then save the form and exit the editor.

All files open in the default changelist are moved to the new changelist. When you exit the text editor, the changelist is assigned a number. If you delete files from this changelist, the files are moved back to the default changelist.

The numbers assigned to submitted changelists reflect the order in which the changelists were submitted. When a changelist is submitted, the Perforce server might renumber it, as shown in the following example.

Submitting changelists

To submit a pending changelist, issue the p4 submit command. When you issue the p4 submit command, a form is displayed, listing the files in the changelist. You can remove files from this list. The files you remove remain open in the default pending changelist until you submit them or revert them.

To submit specific files that are open in the default changelist, issue the p4 submit filename command. To specify groups of files, use wildcards. For example, to submit all text files open in the default changelist, type p4 submit "*".txt. (Use quotation marks as an escape code around the * wildcard to prevent it from being interpreted by the local command shell).

After you save the changelist form and exit the text editor, the changelist is submitted to the Perforce server, and the server updates the files in the depot. After a changelist has been successfully submitted, only a Perforce administrator can change it, and the only fields that can be changed are the description and user name.

If an error occurs when you submit the default changelist, Perforce creates a numbered changelist containing the files you attempted to submit. You must then fix the problems and submit the numbered changelist using the -c flag.

Perforce enables write permission for files that you open for edit and disables write permission when you successfully submit the changelist containing the files. To prevent conflicts with the Perforce server's management of your workspace, do not change file write permissions manually.

Deleting changelists

To delete a pending changelist, you must first remove all files and jobs associated with it and then issue the p4 change -d changenum command. Related operations include the following:

Changelists that have already been submitted can be deleted only by a Perforce administrator. See the Perforce System Administrator's Guide for more information.

Renaming and moving files

To rename or move files, you use the p4 delete and p4 integrate commands to simultaneously create the new file and delete the original file, thereby preserving its revision history. The process is as follows:

p4 integrate source_file target_file
p4 delete source_file
p4 submit

To rename groups of files, use matching wildcards in the source_file and target_file specifiers. To rename files, you must have Perforce write permission for the specified files. (For details about Perforce permissions, see the Perforce System Administrator's Guide.)

When you rename or move a file using p4 integrate, the Perforce server creates an integration record that links it to its deleted predecessor, preserving the file's history. (Integration is also used to create branches and to propagate changes. For details, see "Integrating changes" on page 75.

Displaying information about changelists

To display brief information about changelists, use the p4 changes command. To display full information, use the p4 describe command. The following table describes some useful reporting commands and options.

Command
Description

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 specified number of changelists.

p4 changes -s status

Limits the list to those changelists with a particular status; for example, p4 changes -s submitted lists 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.)

For more information, see "Changelist reporting" on page 97.

Diffing files

Perforce provides a program that enables you to diff (compare) revisions of text files. By diffing files, you can display:

To diff a file that is synced to your workspace with a depot revision, issue the p4 diff filename#rev command. If you omit the revision specifier, the file in your workspace is compared with the revision you last synced, to display changes you made after syncing the file.

To diff two revisions that reside in the depot but not in your workspace, use the p4 diff2 command. To diff a set of files, specify wildcards in the filename argument when you issue the p4 diff2 command.

The p4 diff command performs the diff on your client machine, but the p4 diff2 command performs the diff on the server machine and sends the results to your client machine.

The following table lists some common uses for diff commands.

To diff
Against
Use this command

The workspace file

The head revision

p4 diff file
or
p4 diff file#head

The workspace file

Revision 3

p4 diff file#3

The head revision

Revision 134

p4 diff2 file file#134

File revision at changelist 32

File revision at changelist 177

p4 diff2 file@32 file@177

All files in release 1

All files in release 2

p4 diff2 //depot/rel1/... //depot/rel2/...

By default, the p4 diff command launches the Perforce client's internal diff program. To use a different diff program, set the P4DIFF environment variable to specify the path and executable of the desired program. To specify arguments for the external diff program, use the -d flag. For details, refer to the Perforce Command Reference.

Working detached

If you need to work detached (without access to your Perforce server) on files under Perforce control, you must reconcile your work with the Perforce server when you regain access to the server. The following method for working detached assumes that you work on files in your client workspace or update the workspace with your additions, changes, and deletions before you update the depot.

For platform-specific details about working detached, see Tech Note 2 on the Perforce web site:

To work detached:

  1. Work on files without issuing p4 commands. Instead, use operating system commands to change the permissions on files.

  2. After the network connection is reestablished, use p4 diff to find all files in your workspace that have changed. (You need to track new files manually.)

  3. Update the depot by opening files for add, edit, or delete as required and submitting the resulting changelists.

The following sections provide more details.

Finding changed files

To detect changed files, issue the p4 diff command. The following flags enable you to locate files that you changed or deleted manually, without opening them for edit or delete in Perforce.

Flag
Description

p4 diff -se

Lists workspace files that are not open for edit but have been changed since being synced. To update the depot with these files, open them for edit and submit them.

p4 diff -sd

Lists files that are not open for delete but have been manually deleted from the workspace. To update the depot with these file deletions, open them for delete and submit them.

Submitting your changes

To update the depot with the changes that you made to the client workspace while working detached, use the p4 diff flags described above with the -x flag, as shown in the following examples. The -x flag directs the p4 edit command to accept arguments from the pipe (or a file).

To open changed files for edit after working detached, issue the following command:

To delete files from the depot that were removed from the client workspace, issue the following command:

Open any new files for add; then submit the changelist containing your additions, changes, and deletions.


Perforce 2008.1 P4 User's Guide
<< Previous Chapter
Issuing P4 Commands
Table of Contents
Index
Perforce on the Web
Next Chapter >>
Resolving Conflicts
Please send comments and questions about this manual to [email protected].
Copyright 2005-2008 Perforce Software. All rights reserved.
Last updated: 07/08/08