Perforce 98.2 :Quick Start: Basics

Perforce 98.2 p4 User's Guide


<< Previous Chapter Connecting to the p4d Server	Table of Contents Index Perforce on the Web	Next Chapter >> Basics: The Details

Chapter 3
Perforce Basics: Quick Start

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.

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.

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].

File Configurations Used in the Examples

Reference

The use of the Elm source code set is described in the About This Manual chapter.

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
Ed	`edk`	`eds_elm`	`/usr/edk/elm`
Lisa	`lisag`	`lisas_ws`	`/usr/lisag/docs`

Setting Up a Client Workspace

To move files between a client workspace and the depot, the Perforce server requires two pieces of information:

A name that uniquely identifies the client workspace, and
The top-level directory of this workspace.

Naming the Client Workspace

Example

Naming the client workspace

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.

Describing the Client Workspace to the Perforce Server

Note

Many p4 commands, including p4 client, display a form for editing in a standard text editor. The editor that is used is defined through the P4EDITOR environment variable.

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:


Field	Meaning
`Root:`	Identifies the top subdirectory of the client workspace. This should be the lowest-level directory that includes all the files and directories that you'll be working with in this workspace.
`View:`	Describes which files and directories in the depot are available to the client workspace, and where the files in the depot will be located within the client workspace.

Example

Setting the client root and the client view:

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/...

95/98/NT

In the Windows environments, a single client workspace may span multiple drives by setting the client root to null and including the drive letter in the client view. Please see our Windows release notes for further details.

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 exits from the editor, and the p4 client command completes.

! Warning !

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.

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.

Editing an Existing Client Specification

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 effect 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. To update the files in your client workspace, follow these procedures:

If you change only the client workspace view with p4 client, perform a p4 sync immediately afterward. The files in the client workspace will be deleted from their old locations and written to their new locations.
If you use p4 client to change the client root, use p4 sync #none to remove the files from their old location in the workspace before using p4 client to change the client root. After using p4 client to change the root directory, perform a p4 sync to copy the files to their new locations within the client view. (If you forget to perform the p4 sync #none before changing the client view, you can always remove the files from their client workspace locations manually).

Deleting an Existing Client Specification

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 in the Details chapter) on the files before deleting the client specification, or use the standard local OS deletion commands after deleting the client specification.

Copying Files from the Workspace to the Depot

Note

If you're working in an already-established Perforce environment, and want to start by retrieving already- existing files, you can skip to page 24 and come back to this section later.

Any file in a client workspace can be added to, updated in, or deleted from the depot. This is accomplished in two steps:

Perforce is told the new state of client workspace files with the commands 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.
The operations are performed on the files in the changelist when the p4 submit command is given.

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.

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.

Adding Files to the Depot

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 default changelist; they won't be added to the depot until the p4 submit command is given.

Example

Adding files to a changelist.

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.

$ cd ~/elm/doc
$ p4 add elm-help.*
//depot/elm_proj/doc/elm-help.0#1 - opened for add
//depot/elm_proj/doc/elm-help.1#1 - opened for add
//depot/elm_proj/doc/elm-help.2#1 - opened for add
//depot/elm_proj/doc/elm-help.3#1 - opened for add

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.

Example

Submitting a changelist to the depot.

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:

Change: new
Client: edk
User: edk
Status: new
Description:
  <enter description here>
Files:
  //depot/elm_proj/doc/elm-help.0 # add
  //depot/elm_proj/doc/elm-help.1 # add
  //depot/elm_proj/doc/elm-help.2 # add
  //depot/elm_proj/doc/elm-help.3 # add

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.

Example

Using multiple file arguments on a single command line.

Ed wants to add all his Elm library, documentation, and header files to the depot.

$ cd ~
$ p4 add elm/lib/* elm/hdrs/* elm/doc/*
//depot/elm_proj/lib/Makefile.SH#1 - opened for add
//depot/elm_proj/lib/add_site.c#1 - opened for add
//depot/elm_proj/lib/addrmchusr.c#1 - opened for add
<etc.>

... 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.

! 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.

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.

Updating Depot Files

To open a file for edit, use p4 edit. This has two effects:

The file(s) write permissions are turned on in the client workspace, and
The file(s) to be edited are added to the default changelist.

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.

Deleting Files From the Depot

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.

Example

Deleting a file from the depot.

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.

Submitting with Multiple Operations

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.

Example

Adding, updating, and deleting files in a single p4 submit.

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:

$ cd ~
$ p4 add elm/src/newmbox.c
//depot/elm_proj/src/newmbox.c#1 - opened for add
<etc.>
$ p4 edit elm/hdrs/s_elm.h doc/elm-help.*
//depot/elm_proj/hdrs/s_elm.h#1 - opened for edit
//depot/elm_proj/doc/elm-help.0#1 - opened for edit
//depot/elm_proj/doc/elm-help.1#1 - opened for edit
//depot/elm_proj/doc/elm-help.2#2 - opened for edit

He edits the existing files and then p4 submit's the default changelist:

Change: new
Client: eds_elm
User: edk
Status: new
Description:
  Changes to Elm's "mult. mailbox" functionality
Files:
  //depot/elm_proj/doc/elm-help.0 # edit
  //depot/elm_proj/doc/elm-help.1 # edit
  //depot/elm_proj/doc/elm-help.2 # edit
  //depot/elm_proj/hdrs/s_elm.h # edit
  //depot/elm_proj/src/newmbox.c # add

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.

Retrieving Files from the Depot into a Workspace

Files can be retrieved into a client workspace from the depot with p4 sync.

Example

Retrieving files from the depot into the client workspace:

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.

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.

Reverting Files to their Unopened States

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, and any local modifications to the file will be lost.

Example

Reverting a file back to the last synced version.

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:

$ cd ~elm/src
$ p4 edit leavembox.c limit.c signals.c
//depot/elm_proj/src/leavembox.c#2 - opened for edit
//depot/elm_proj/src/limit.c#2 - opened for edit
//depot/elm_proj/src/signals.c#1 - opened 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.

Basic Reporting Commands

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.


Command	Meaning
`p4 help commands`	Lists all Perforce commands with a brief description of each.
`p4 help command`	For any command provided, gives detailed help about that command. For example, `p4 help sync` provides detailed information about the `p4 sync` command.
`p4 help usage`	Describes command-line flags common to all Perforce commands.
`p4 help views`	Gives a discussion of Perforce view syntax
`p4 help`	Describes all the arguments that can be given to `p4 help`.
`p4 info`	Reports information about the current Perforce system: the server address, client root directory, client name, user name, Perforce version, and a few other tidbits.

Two other reporting commands are used quite often:


Command	Meaning
`p4 have`	Lists all file revisions that the Perforce server knows you have in the client workspace.
`p4 sync -n`	Reports what files would be updated in the client workspace by `p4 sync` without actually performing the `sync` operation.

Perforce 98.2 p4 User's Guide


<< Previous Chapter Connecting to the p4d Server	Table of Contents Index Perforce on the Web	Next Chapter >> Basics: The Details