| Perforce 2004.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 few changes to your normal work habits are required. You work on files in your own directories using your editor or IDE of choice; Perforce commands supplement your normal work actions instead of replacing them.
Perforce commands are always entered in the form p4 command [arguments].
|
Note |
Many p4 commands display a form for editing in a standard text editor. You can specify your text editor of choice by setting the P4EDITOR environment variable. |
Ed is working on the code for a project called Elm. He wants to refer to the set of files he's
working on (his client workspace) by the name eds_elm. In the Korn or Bourne shells, he
types:
Subsequent p4 commands will use the client workspace named eds_elm.
Different operating systems and shell have their own methods of setting environment variables. See "Setting and viewing environment variables" on page 148 for details.
p4 client
Typing p4 client brings up the client definition form in a text editor. After you have filled out the form and exited the text editor, you can use Perforce client programs to move files between the depot and your client workspace.
The p4 client form contains a number of fields; at this point, the important fields are the Root: and View: fields:
Ed is working with his Elm files in a setting as described above. He's set the environment
variable P4CLIENT to eds_elm. He then 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) are mapped to the depot, and all files in the depot are mapped to Ed's
home directory, likely cluttering it with files that Ed isn't interested in seeing.
Ed chooses to work on all Elm-related material in an /elm subdirectory beneath his home
directory of /usr/edk, and he would like this directory (/usr/edk/elm) to contain only
files in the elm_proj portion of the depot. He changes the values in the Root: and View:
fields as follows:
|
Client: eds_elm |
The revised form specifies /usr/edk/elm as the top level directory of Ed's client workspace,
and that the files in 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.
In the p4 client form, the read-only Client: field contains the string stored in the P4CLIENT environment variable. The Description: is a free-form text field where you can add a description of the workspace. The View: field describes the relationship between files in the depot and files in the client workspace. To use Perforce properly, it is crucial to understand how views work. Views are discussed in greater detail in "Mapping Depot files to your Client Workspace" on page 38.
Creating a client specification has no immediate visible effect; no files are created when a client specification is created or edited. The client workspace specification merely defines where files are located when you populate your workspace with files from the server.
|
Note |
If you've just installed a Perforce server for the first time, p4 sync won't do anything, because an empty depot contains no files to copy to client workspaces. If you have just installed a Perforce server, use p4 add, as described in "Adding files to the depot" on page 29, to populate the depot by copying files from your client workspace to the depot. |
The p4 sync command maps depot files through your client workspace view, compares the result against the contents of your client workspace, and then adds, updates, or deletes files in your workspace as needed to bring the contents of your workspace into sync with the depot.
If a file exists within a particular subdirectory in the depot, but that directory does not yet exist in your client workspace, the directory is created in the client workspace when you run p4 sync. If a file in your client workspace has been deleted from the depot, p4 sync removes the file from your client workspace.
By default, p4 sync updates your entire client workspace. To limit the update to only a portion of your client workspace, you can supply filenames or wildcards to p4 sync.
Lisa is responsible for the documentation for the Elm project. Her client workspace root is a
directory called elm_ws, and she has set her client workspace view to include only the
elm_proj documentation tree. To populate her client workspace, she enters her client
workspace root, runs p4 sync, and sees:
|
$ cd ~/elm_ws |
After the p4 sync command completes, the most recent revisions of the Elm project's
documentation files as mapped through Lisa's client workspace view, are available in her
workspace.
Changelists enable you to send updated sets of files to the depot in indivisible, or atomic, transactions: when a changelist is submitted, either all of the files in the changelist are committed, or none of the files are committed.
|
Note |
This chapter discusses only the default changelist, which is automatically maintained by Perforce. Changelists are a key concept in Perforce. 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 (for add, for edit, or for delete) in the client workspace.
After you have added files to the changelist, you must submit your changelist to the depot by using the p4 submit command. See "Submitting your changes to the depot" on page 32 for details.
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, four files have been added to his default changelist. The files are not actually
stored in the depot until Ed uses the p4 submit command to submit the changelist.
In the example shown, the filenames are displayed as filename#1. The #n suffix is used by Perforce to indicate the nth revision of this file. The first revision of any file is revision #1. Revision numbers are always assigned sequentially.
Ed wants to add all of his Elm library, documentation, and header files to the depot.
Files in the three specified directories are added to the default changelist.
|
Note |
Before you can open a file for edit, someone must have already added the file to the depot with p4 add, or copied into your client workspace from the depot with p4 sync. |
Ed wants to make changes to his elmdoc.3 file. He opens the file for edit.
Ed then edits the file with his preferred text editor. When he's finished making his changes to
the file, he makes his changes available to other users by using p4 submit to submit the
changelist to the depot.
The p4 delete command deletes the file from your client workspace as soon as you run the p4 delete command, but deletion of the file in the depot does not occur until you use p4 submit to submit the changelist containing the delete operation to the depot.
After you submit a changelist with a file deletion, it appears to all users as though the file is deleted from the depot. Actually, only the most recent revision (or head revision) of the file is marked as deleted. Older revisions of the file are not removed, and by specifying these older revisions, you can always recover old revisions of "deleted" files back into your client workspace.
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 Ed's client workspace immediately, but it is not deleted from the depot
until Ed submits the changelist with the p4 submit command.
Submitting a changelist to the depot works atomically: either all the files in the changelist are updated in the depot, or none of them are. (In Perforce terminology, this is called an atomic change transaction).
To submit a changelist, use the p4 submit command.
Ed is writing the portion of Elm that is responsible for multiple folders (multiple mailboxes).
He has added a new source file src/newmbox.c, and he needs to edit the header file
hdrs/s_elm.h and some of the doc/elmdoc files to reflect his changes.
Ed adds the new file and prepares to edit the existing files as follows:
He edits the header file and the documentation files in his workspace. When he is ready to
submit the changelist, he types p4 submit and sees the following form in a standard text
editor:
Ed changes the contents of the Description: field in the p4 submit form to describe the
changes he's made as follows:
All of Ed's changes 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.
The p4 submit form includes a Description: field; you must supply a description in order for your changelist to be accepted.
The Files: field contains the list of files in the changelist. If you remove files from this field, any files not included in the changelist are carried over to a new default changelist, and reappear the next time you use p4 submit.
If a directory containing a new file does not exist in the depot, the directory is automatically created in the depot when you submit the changelist.
When you run p4 submit, the operating system's write permission on the submitted files in your client workspace is turned off. Write permissions are restored when you open a file for editing with p4 edit.
|
Warning! |
If a submit fails due to a file conflict, the default changelist is assigned a number, and you'll need to submit that changelist in a slightly different way. See Chapter 5, Perforce Basics: Resolving File Conflicts for details on submitting numbered changelists. |
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 plans to change, and that he did not
intend to open it. He reverts signals.c to its unopened state with p4 revert:
If you use p4 revert on a file you opened with p4 delete, the file reappears in your client workspace immediately. If you revert a file opened with p4 add, the file is removed from the changelist, but is left intact in your client workspace.
If you revert a file you originally opened with p4 edit, the last synced version is written back to the client workspace, overwriting the edited version of the file. To reduce the risk of accidentally overwriting your changes, you can preview any 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 useful when getting started with Perforce:
| Perforce 2004.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 |