| Perforce 2000.2 Command Line User's Guide (2000.2.ug.1) | ||
|
<< Previous Chapter Connecting to the Perforce Server |
Table of Contents Index Perforce on the Web |
Next Chapter >> Perforce Basics: The Details |
These concepts and commands are painted with very broad strokes in this chapter; the details are provided in the next.
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].
|
User |
Username |
Client Workspace Name |
Top of own Elm File Tree |
|---|---|---|---|
|
Ed |
edk |
eds_elm |
/usr/edk/elm |
|
Lisa |
lisag |
lisas_ws |
/usr/lisag/docs |
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:
Each operating system or shell has its own method of defining environment variables. See the "Environment Variables" section of the Perforce Command Reference for details.
|
Note |
Many p4 commands, including p4 client, display a form for editing in a standard text editor. You can define the editor your client uses through the P4EDITOR environment variable. |
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 |
With these default settings, all files in Ed's home directory of /usr/edk (including files unrelated to Ed's
work) would be mapped to the depot, and all files in the depot would be mapped to Ed's home directory, likely
cluttering it with files Ed has no interest in working with.
Ed would like to keep all Elm-related material in a subdirectory in his home directory; /usr/edk/elm, and he
would like this directory to contain only files in the elm_proj portion of the depot. He therefore changes the
values in the Root: and View: fields as follows:
|
Client: 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 exits 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 Perforce commands are used.
You'll also use p4 client to change existing client specifications. This is described in "Perforce Basics: The Details" on page 19.
Lisa 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 |
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.
If a file exists within a particular subdirectory in the depot, but that directory does not yet exist in the client workspace, the directory will be created within the client workspace at sync time.
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.
|
Note |
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. |
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.
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
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.
If the directory containing a new file does not exist in the depot, it is automatically created within the depot at submit time.
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 Nth revision of this file. Revision numbers are always assigned sequentially.
|
!Warning! |
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 save the new file revision in the depot, use p4 submit, as above.
|
Note |
Before a file can be opened for edit, it must already have been added to the depot with p4 add, or copied into the client workspace from the depot with p4 sync. |
Ed wants to make changes to his elm-help.3 file. He opens the file 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.
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. The p4 delete command also deletes the file from the client workspace; this occurs when the p4 delete command is given. The deletion of the file in the depot occurs only after the changelist with the delete operation is submitted.
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:
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.
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 performs a p4 submit of 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.
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:
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.
The most basic reporting commands are p4 help and p4 info.
Two other reporting commands are used quite often:
| Perforce 2000.2 Command Line User's Guide (2000.2.ug.1) | ||
|
<< Previous Chapter Connecting to the Perforce Server |
Table of Contents Index Perforce on the Web |
Next Chapter >> Perforce Basics: The Details |