Chapter 4
Managing Files and Changelists

Managing files

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

Example:  Copying files from the depot to a client workspace

The following command retrieves the most recent revisions of all files in the client view from the depot into the workspace. As files are synced, they are listed in the command output.

C:\bruno_ws>p4 sync //depot/dev/main/bin/bin.linux24x86/readme.txt#1 - added as c:\bruno_ws\dev\main\bin\bin.linux24x86\readme.txt //depot/dev/main/bin/bin.ntx86/glut32.dll#1 - added as c:\bruno_ws\dev\main\bin\bin.ntx86\glut32.dll //depot/dev/main/bin/bin.ntx86/jamgraph.exe#2 - added as c:\bruno_ws\dev\main\bin\bin.ntx86\jamgraph.exe [...]

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:

p4 sync//depot/dev/main/jam/Jamfile#1

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:

p4 sync //depot/dev/main/jam/...

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

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

http://www.perforce.com/perforce/technotes/note012.html

Example:  Adding files to a changelist

Bruno has created a couple of text files that he needs to add to the depot. To add all the text files at once, he uses the "*" wildcard when he issues the p4 add command.

C:\bruno_ws\dev\main\docs\manuals>p4 add *.txt //depot/dev/main/docs/manuals/installnotes.txt#1 - opened for add //depot/dev/main/docs/manuals/requirements.txt#1 - opened for add

Now the files he wants to add to the depot are open in his default changelist. The files are stored in the depot when the changelist is submitted.

Example:  Submitting a changelist to the depot

Bruno is ready to add his files to the depot. He types p4 submit and sees the following form in a standard text editor:

Change: new Client: bruno_ws User:   bruno Status: new Description:         <enter description here> Files:     //depot/dev/main/docs/manuals/installnotes.txt   # add     //depot/dev/main/docs/manuals/requirements.txt   # add

Bruno changes the contents of the Description: field to describe his file updates. When he's done, he saves the form and exits the editor, and the new files are added to the depot.

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

Example:  Opening a file for edit

Bruno wants to make changes to command.c, so he syncs it and opens the file for edit.

p4 sync //depot/dev/command.c //depot/dev/command.c#8 - added as c:\bruno_ws\dev\command.c p4 edit //depot/dev/command.c //depot/dev/command.c#8 - opened for edit

He then edits the file with any text editor. When he's finished, he submits the file to the depot with p4 submit, as described above.

Discarding changes (reverting)

Example:  Reverting a file

Bruno decides not to add his text files after all.

C:\bruno_ws\dev\main\docs\manuals>p4 revert *.txt //depot/dev/main/docs/manuals/installnotes.txt#none - was add, abandoned //depot/dev/main/docs/manuals/requirements.txt#none - was add, abandoned

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

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.

Example:  Deleting a file from the depot

Bruno deletes vendor.doc from the depot as follows:

p4 delete //depot/dev/main/docs/manuals/vendor.doc //depot/dev/main/docs/manuals/vendor.doc#1 - opened for delete

The file is deleted from the client workspace immediately, but it is not deleted from the depot until he issues the p4 submit command.

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

• p4 add

• p4 delete

• p4 edit

• p4 integrate

• p4 reopen

• p4 revert

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

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.

Example:  Working with multiple changelists

Bruno is fixing two different bugs, and needs to submit each fix in a separate changelist. He syncs the head revisions of the files for the first fix and opens the for edit in the default changelist

C:\bruno_ws\>p4 sync //depot/dev/main/jam/*.c [list of files synced...] C:\bruno_ws>p4 edit //depot/dev/main/jam/*.c [list of files opened for edit...]

Now he issues the p4 change command and enters a description in the changelist form. After he saves the file and exits the editor, Perforce creates a numbered changelist containing the files.

C:\bruno_ws\dev\main\docs\manuals>p4 change     [Enter description and save form] Change 777 created with 33 open file(s).

For the second bug fix, he performs the same steps, p4 sync, p4 edit, and p4 change. Now he has two numbered changelists, one for each fix.

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.

Example:  Automatic renumbering of changelists

Bruno has finished fixing the bug that he's been using changelist 777 for. After he created that changelist, he submitted another changelist, and two other users also submitted changelists. Bruno submits changelist 777 with p4 submit -c 777, and sees the following message:

Change 777 renamed change 783 and submitted.

Submitting changelists

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 move files to another changelist, issue the p4 reopen -c changenum command.

• To remove files from the changelist and discard any changes, issue the p4 revert -c changenum command.

Renaming and moving files

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

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

Diffing files

• Changes that you made after opening the file for edit

• Differences between any two revisions

• Differences between file revisions in different branches

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.

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

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

http://www.perforce.com/perforce/technotes/note002.html

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.

Finding changed files

Submitting your changes

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

p4 diff -se | p4 -x - edit

p4 diff -sd | p4 -x - delete