This chapter teaches basic Perforce usage. You'll learn how to move files to and from the common file repository, how to back out of these operations, and the basic Perforce reporting commands.
These concepts and commands are painted with very broad strokes in this chapter; the details are provided in the next.
The basic ideas behind Perforce are quite simple: files are created, edited, and deleted in the user's own directories, which are called client workspaces. Perforce commands are used to move files to and from a shared file repository known as the depot. Perforce users can retrieve files from the depot into their own client workspaces, where they can be read, edited, and resubmitted to the depot for other users to access. When a new revision of a file is stored in the depot, the old revisions are kept, and are still accessible.
Perforce was written to be as unobtrusive as possible; very few changes to your normal work habits are required. Files are still created in your own directories with a standard text editor; Perforce commands supplement your normal work actions instead of replacing them.
Perforce commands are always entered in the form p4 command [arguments].
This manual makes extensive use of examples based on the Elm source code set. The Elm examples used in this manual are set up as follows:
A single depot is used to store the elm files, and perhaps other projects as well. The elm files will be shared by storing them under an elm subdirectory within the depot.
Each user will store his or her client workspace Elm files in a different subdirectory. The two users we'll be following most closely, Ed and Lisa, will work with their Elm files in the following locations:
User | Username | Client Workspace Name | Top of own Elm File Tree |
edk | eds_elm | /usr/edk/elm | |
lisag | lisas_ws | /usr/lisag/docs |
To move files between a client workspace and the depot, the Perforce server requires two pieces of information:
To name your client workspace, or to use a different workspace, set the environment variable P4CLIENT to the name of the client workspace.
Ed is working on the code for Elm. He wants to refer to the collection of files he's working on by the name eds_elm. In the Korn shell, he'd type
$ export P4CLIENT=eds_elm
Each operating system or shell has its own method of defining environment variables; Appendix A describes how to create environment variables within each shell and OS.
Once the client workspace has been named, it must be identified and described to the Perforce server with the p4 client command. Typing p4 client brings up the client definition form in a standard text editor; once the form is filled in and the editor exited, the Perforce server will be able to move files between the depot and the client workspace.
The p4 client form has a number of fields; the two most important are the Root and View. The meanings of these fields are as follows:
Ed is working with his elm files in a setting as described above. He's set the environment variable P4CLIENT to eds_elm; now he types p4 client from his home directory, and sees the following form:
Client: eds_elm
Owner: ed
Description:
Created by ed.
Root: /usr/edk
Options: nomodtime noclobber
View:
//depot/... //eds_elm/...
If he were to leave the form as is, all of the files under /usr/edk would be mapped to the depot, and they would map to the entire depot, instead of to just the elm project. He changes the values in the Root: and View: fields as follows:
Client: eds_elm
Owner: ed
Description:
Created by ed.
Root: /usr/edk/elm
Options: nomodtime noclobber
View:
//depot/elm_proj/... //eds_elm/...
This specifies that /usr/edk/elm is the top level directory of Ed's client workspace, and that the files under this workspace directory are to be mapped to the depot's elm_proj subtree.
When Ed's done, he quits from the editor, and the p4 client command completes.
The read-only Client: field contains the string stored in the P4CLIENT environment variable. Description: can be filled with anything at all (up to 128 characters); this provides an arbitrary textual description of what's contained in this client workspace. The View: describes the relationship between files in the depot and files in the client workspace.
Creating a client specification has no immediate visible effect; no files are created when a client specification is created or edited. The client specification simply indicates where files will be located when subsequent p4 commands are used.
To use Perforce properly, it is crucial to understand how views work. Views are explained in more detail at the start of the next chapter.
p4 client can be used at any time to change the client workspace specification. Just as when a client specification is created, changing a specification has no immediate affect on the locations of any files; the location of files in the depot and workspace is affected only when the client specification is used in subsequent commands. But there is an important distinction between changing the client's root and changing the client's view: if you change the root, Perforce assumes that you will manually relocate the files as well. If you change the view and then bring files into the client from the depot, Perforce will delete and add files as necessary to make the client workspace reflect the view.
An existing client workspace specification can be deleted with p4 client -d clientname. Deleting a client specification has no effect on any files in the client workspace or depot; it simply removes the p4d server's record of the mapping between the depot and the client workspace. To delete existing files from a client workspace, use p4 sync #none (described on page 34) on the files before deleting the client specification, or use the standard local OS deletion commands after deleting the client specification.
Any file in a client workspace can be added to, updated in, or deleted from the depot. This is accomplished in two steps:
The commands p4 add, p4 edit, and p4 delete do not immediately add, edit, or delete files in the depot. Instead, the affected file and the corresponding operation are listed in the default changelist, and the files in the depot are affected only when this changelist is submitted to the depot with p4 submit. This allows a set of files to be updated in the depot all at once: when the changelist is submitted, either all of the files in the changelist are affected, or none of them are.
When a file has been opened with p4 add, p4 edit, or p4 delete, but the corresponding changelist has not yet been submitted in the depot, the file is said to be open in the client workspace.
This chapter discusses only the default changelist, which is automatically maintained by Perforce. Changelists can be created by the user; please see Chapter 7 for a full discussion.
To add a file or files to the depot, type p4 add filename(s). The p4 add commands opens the file(s) for edit and lists them in the the default changelist; they won't be added to the depot until the p4 submit command is given.
Ed is writing a help manual for Elm. The files are named elm-help.0 through
elm-help.3, and they're sitting in the doc subdirectory of his client workspace root. He wants to add these files to the depot.
At this point, the files he wants to add to the depot have been added to his default changelist. However, the files are not actually added to the depot until the p4 submit command is given.
Ed is ready to submit his added files to the depot. He types p4 submit and sees the following form in a standard UNIX text editor:
Ed changes the contents of the Description: field to describe what these file updates do. When he's done, he quits from the editor; the new files are added to the depot.
The Description: field contents must be changed, or the depot update won't be accepted. Lines can be deleted from the Files: field; any files deleted from this list will carry over to the next default changelist, and will appear again the next time p4 submit is performed.
Multiple file arguments can be provided on the command line.
Ed wants to add all his Elm library, documentation, and header files to the depot.
... and then does a p4 submit.
The operating system's write permission on submitted files is turned off in the client workspace when p4 submit is performed. This helps ensure that file editing is done with Perforce's knowledge. The write permissions are turned back on by p4 edit, which is described below.
You might have noticed in the example above that the filenames are displayed as filename#1. Perforce always displays filenames with a #n suffix; the #n indicates that this is the n-th revision of this file. Revision numbers are always assigned sequentially.
If a submit fails, the default changelist will be assigned a number, and you'll need to submit that changelist in a slightly different way.
Please see Chapter 5 for instructions on resolving file conflicts.
To open a file for edit, use p4 edit. This has two effects:
Since the files must have their write permission turned back on before they can be edited, the p4 edit command must be given before the file is actually edited.
To save the new file revision in the depot, use p4 submit, as above.
Example: Ed wants to make changes to his elm-help.3 file. He opens the file for edit:
$ cd ~/elm
$ p4 edit doc/elm-help.3
//depot/elm_proj/doc/elm-help.3#1 - opened for edit
... and then edits the file with any text editor. When he's finished, he submits the file to the depot with p4 submit, as above.
Files are deleted from the depot similarly to the way they are added and edited: the p4 delete command opens the file for delete in the default changelist, and then p4 submit is used to delete the file from the depot. p4 delete also deletes the file from the client workspace; this occurs when the p4 delete command is given. In essence,
p4 delete replaces the operating systems rm or del command.
Ed's file doc/elm-help.3 is no longer needed. He deletes it from both his client workspace and from the depot as follows:
$ cd ~elm/doc
$ p4 delete elm-help.3
//depot/elm_proj/doc/elm-help.3#1 - opened for delete
The file is deleted from the client workspace immediately; it is not deleted from the depot until the p4 submit command is given.
Once the changelist is submitted, it will appear as if the file has been deleted from the depot; however, old file revisions are never actually removed. This makes it possible to read older revisions of `deleted' files back into the client workspace.
Multiple files can be included in any changelist. Submitting the changelist to the depot works atomically: either all the files are updated in the depot, or none of them are. (In Perforce's terminology, this is called an atomic change transaction). Changelists can be used to keep files together that have a common purpose.
Ed is writing the portion of Elm that is responsible for multiple folders (multiple mailboxes). He has a new source file src/newmbox.c, and he needs to edit the header file hdrs/s_elm.h and the doc/elm-help files. He adds the new file and prepares to edit the existing files:
He edits the existing files and then p4 submit's the default changelist:
All of his changes supporting multiple mailboxes are grouped together in a single changelist; when Ed quits from the editor, either all of these files are updated in the depot, or, if the submission fails for any reason, none of them are.
Files can be deleted from the Files: field; these files are moved into the next default changelist, and will appear again the next time p4 submit is performed.
Files can be retrieved from the depot into a client workspace from the depot with p4 sync.
p4 sync was named p4 get in previous versions of Perforce.. p4 get can still be used as an alias for p4 sync.
Jill has been assigned to fix bugs in Ed's code. She creates a directory called elm_ws within her own directory, and sets up a client workspace; now she wants to copy all the existing elm files from the depot into her workspace.
$ cd ~elm_ws
$ p4 sync
//depot/elm_proj/doc/elm-help.0#2 - added as /usr/lisag/elm_ws/doc/elm-help.0
//depot/elm_proj/doc/elm-help.1#2 - added as /usr/lisag/elm_ws/doc/elm-help.1
<etc.>
Once the command completes, the most recent revisions of all the files in the depot that are mapped through her client workspace view will be available in her workspace.
The p4 sync command maps depot files through the client view, compares the result against the current client contents, and then adds, updates, or deletes files in the client workspace as needed to bring the client contents in sync with the depot. p4 sync can take filenames as parameters, with or without wildcards, to limit the files it retrieves.
p4 sync's job is to match the state of the client workspace to that of the depot; thus, if a file has been deleted from the depot, p4 sync will delete it from the client workspace.
Any file opened for add, edit, or delete can be removed from its changelist with p4 revert. This command will revert the file in the client workspace back to its unopened state.
Ed wants to edit a set of files in his src directory: leavembox.c, limit.c, and signals.c. He opens the files for edit:
and then realizes that signals.c is not one of the files he will be working on, and that he didn't mean to open it. He can revert signals.c to its unopened state with p4 revert
$ p4 revert signals.c
//depot/elm_proj/src/signals.c#1 - was edit, reverted
:
If p4 revert is used on a file that had been opened with p4 delete, it will appear back in the client workspace immediately. If p4 add was used to open the file, p4 revert removes it from the changelist, but leaves the client workspace file intact. If the reverted file was originally opened with p4 edit, the last synced version will be written back to the client workspace, overwriting the newly-edited version of the file. In this case, you may want to save a copy of the file before running p4 revert.
Perforce provides some 20+ reporting commands. Each chapter in this manual ends with a description of the reporting commands relevant to the chapter topic. All the reporting commands are discussed in greater detail in the reporting chapter, chapter 12.
The most basic Perforce commands are p4 help and p4 info.
Two other reporting commands are used quite often: