| Perforce 2003.2 User's Guide | ||
|
<< Previous Chapter Connecting to the Perforce Server |
Table of Contents Index Perforce on the Web |
Next Chapter >> Perforce Basics: The Details |
This chapter gives a broad overview of these concepts and commands; for details, see Chapter 4, Perforce Basics: The Details.
Perforce was written to be as unobtrusive as possible, so that very few changes to your normal work habits are required. Files are still created in your own directories with your tool of choice; 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 or Bourne shells, 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.
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 is done, he exits from the editor, and the p4 client command saves his changes.
The read-only Client: field contains the string stored in the P4CLIENT environment variable. The Description: can be filled with anything at all; it's a place where you can enter text that describes the contents of 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 37.
|
Note |
If you're setting up a brand new depot, p4 sync won't do anything, since there are no files in the depot to copy to the client workspace yet. If this is the case, start by copying files from your client workspace to the depot with p4 add, as described in "Adding files to the depot" on page 30. |
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 is created within the client workspace at sync time.
The job of p4 sync 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 deletes it from the client workspace.
|
Note |
This chapter discusses only the default changelist, which is automatically maintained by Perforce. Changelists can also be created by the user; for a full discussion, see Chapter 7, Changelists. |
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 elmdoc.0 through elmdoc.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 stored in 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, and 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.
Ed wants to add all of his Elm library, documentation, and header files to the depot.
After p4 add is finished, Ed 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, Perforce Basics: Resolving File Conflicts for instructions on resolving file conflicts. |
To save the new file revision in the depot, use p4 submit, as described 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 elmdoc.3 file. He opens the file 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.
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/elmdoc.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, but it is not deleted from the depot
until he gives the p4 submit command.
Once the changelist is submitted, it appears 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/elmdoc 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 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. To reduce the risk of overwriting changes by accident, you may want to preview a revert by using p4 revert -n before running p4 revert. The -n option reports what files would be reverted by p4 revert without actually reverting the files.
The most basic reporting commands are p4 help and p4 info.
Two other reporting commands are used quite often:
| Perforce 2003.2 User's Guide | ||
|
<< Previous Chapter Connecting to the Perforce Server |
Table of Contents Index Perforce on the Web |
Next Chapter >> Perforce Basics: The Details |