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.
Underlying Concepts
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.p4 command [arguments]. File Configurations Used in the Examples
This manual makes extensive use of examples based on the Elm source code set. The setup of files is as follows:elm subdirectory within the depot.
User |
Username |
Top of own Elm File Tree |
|
Ed
| edk | |
|
Lisa
| lisag | |
Setting Up a Client Workspace
To move files between a client workspace and the depot, the Perforce server requires two pieces of information:
P4CLIENT to the name of the client workspace.Example: Ed is working on the code for Elm, a UNIX mail program. 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.
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/...
/usr/edk would be mapped to the depot, and they would map to the entire depot, instead of to just the elm project. He fills 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/...
/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. p4 client command completes.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. Editing an Existing Client Specification
p4 client can be used at any time to change the client workspace specification. Changing this 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. Copying Files from the Workspace to the Depot
Any file in a client workspace can be added to, updated in, or deleted from the depot. This is accomplished in two steps:
p4 add filenames, p4 edit filenames, or p4 delete filenames. When these commands are given, the corresponding files are listed in a Perforce changelist, which is a list of files and operations on those files to be performed in the depot.
p4 submit command is given.
p4 delete eventually deletes the file from the depot, the deletion is not performed immediately. Instead, the affected file and the corresponding operation are listed in the default changelist; when this changelist is handed to the depot with p4 submit, only then is the file deleted from the depot. 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 updated with p4 add, p4 edit, or p4 delete, but has not yet been deleted in the depot, it is said to be open in the client workspace.
p4 add filename(s). The p4 add commands add the file(s) to 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. Files 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 and p4 delete, both of which are 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 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.
Updating Depot Files
To update a file that already exists in the depot, use p4 edit. This has two effects:
write permission turned back on before they can be edited, the p4 edit command must be given before the file is actually edited. To store the new version 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.
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; however, 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 revert back to older revisions of `deleted' files.
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 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.
p4 get.Lisa has been assigned to fix bugs in Ed's code. She creates a directory called
elm 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.
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 get 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 get can take filenames as a parameter, with or without wildcards, to limit the files it retrieves.
p4 get's job is to match the state of the client workspace to that of the depot; `get' in this case means `get state of depot', not `get files from depot'. Thus, if a file has been deleted from the depot, p4 get will delete it from the client workspace.
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 the state it was previously in.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 unneeded state with
$ 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 not appear back in the client workspace until p4 get is performed on the file. 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 gotten 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.
The most basic Perforce commands are
p4 help and p4 info.
Two other reporting commands were discussed in this chapter:.