Previous Table of Contents Next
Perforce 2014.1: Getting Started with P4V

P4V, the Perforce Visual client, is Perforce's cross-platform graphical user interface. You can use P4V on Windows, Mac, UNIX and Linux computers and benefit from an identical interface regardless of platform. This introductory guide provides some Perforce basics and an orientation to P4V's layout and features. For more details about P4V, consult its online help. To learn more about Perforce, consult the user documentation on our Web site.
To use Perforce to manage files, you typically connect to the Perforce versioning service using an application like P4V. P4V enables you to check files in and out, and perform various other versioning tasks. The following sections tell you how to perform basic versioning with P4V and point out some of P4V's powerful features and shortcuts.
Basic Concepts
P4V connects your computer to the Perforce versioning service and helps you move files between Perforce depots and your workspace, as shown below.
The definitions for these Perforce terms are as follows:
Perforce application: P4V (or another Perforce application), running on your workstation, which makes requests from the Perforce versioning service and delivers the results of those requests (files, status information, and so on) to you.
Depot: a file repository hosted by the Perforce service. It contains all existing versions of all files ever submitted. Perforce can host multiple depots, but the examples in this guide show a single depot.
Connecting to Perforce
To gain access to your files, you must connect to Perforce. The first time you launch P4V, the Connection Setup Wizard (Mac: Connection Setup Assistant) guides you through the process of configuring a connection, during which you specify the server, user, and workspace. To launch the wizard/assistant in subsequent sessions, choose Connection > Set Up Connection...
Alternately, you can configure connection settings on a single dialog, as follows:
Server: the name of the machine that hosts the shared versioning service. You must also specify a TCP/IP port. If you are connecting to Perforce with SSL, use ssl:hostname:port.
To display a list of existing users and workspaces, click Browse. (The server and port must be specified before clicking Browse.)
If you have incorrectly specified a server setting, P4V displays a message like the following:
Connect to server failed; check $P4PORT.
TCP connect to bigserver failed.
bigserver: host unknown.
The next section describes the main screen panes.
Navigating the Main Screen
The following figure points out the panes and important features of the main screen. To see what a button or screen element does, hold the mouse cursor over it. P4V displays a descriptive tooltip.
Setting up your workspace
Your Perforce administrator can do this for you, but it's advisable to learn a few important aspects of configuring your workspace, specifically (1) configuring the workspace root directory and (2) configuring the workspace view.
To define a workspace, choose Connection > New Workspace.... and, when prompted, enter a name for the workspace. To edit your current workspace specification, choose Connection > Edit Current Workspace...
P4V displays the specification details in the lower portion of the right pane; for example:
Root: specifies the location on your workstation under which Perforce stores copies of depot files. Specify a meaningful name, and make sure it's not set to your computer's root directory!
Workspace Mappings: enable you to restrict the depot files to which you have access. Set the view to ensure that you see only what you need to see.
To display and set the workspace view graphically, click the Basic tab. Browse to desired files and folders and context-click to include them or exclude them from the workspace mappings, as shown in the following figure.
Managing your Files
To manage files using Perforce, you typically perform the following sequence of tasks:
The following sections provide details about these and other common file management tasks.
Getting files from the depot
To copy files from the depot to your workspace:
Context-click the file or folder. To get the most recent version, choose Get Latest Revision. To get an older version, choose Get Revision... and specify the version you want.
In the Log pane, P4V displays a message like the following.
p4 sync //depot/Misc/manuals/...#head
    //depot/Misc/manuals/recommended_configuration.doc  added  c:\p4clients\bruno-1492\Misc\manuals\recommended_configuration.doc
    //depot/Misc/manuals/triggers.doc  added  c:\p4clients\bruno-1492\Misc\manuals\triggers.doc
    //depot/Misc/manuals/vendor_branches.doc  added  c:\p4clients\bruno-1492\Misc\manuals\vendor_branches.doc
    Sync copied 3 files to workspace (including 3 that were added)
    Sync removed no files from workspace
Sync completed with no warnings or errors.
In the left pane, note that the files display green dots, indicating that they are present in your workspace:Before you can edit the file, however, you must check it out.
Checking out files from the depot
To check out a file in your workspace:
In the Log pane, P4V displays a message like the following:
p4 edit //bruno-1492/Misc/manuals/recommended_configuration.doc
    //depot/Misc/manuals/recommended_configuration.doc#1 - opened for edit
Opened 1 files for edit
In the left pane, note that the file displays a red check mark, indicating that you checked it out:
Note that, when you check out a file, Perforce adds it to a changelist, which is a list of related files. You can use changelists to group related files, for example, all files that contain changes required to implement a new product feature. To view the changelist, choose View > Pending Changelists or click in the toolbar.
Now you're ready to edit your files.
Editing files in your workspace
To edit a checked-out file, double-click it (or context-click it and choose Open With, then select the desired application). P4V launches the corresponding editing application. Make changes and save the file.
To select an application with which to open a file, choose File>Open With>Choose Application. You can configure editors on the Preferences dialog File Editors page.
Adding new files to the depot
To add a file to the depot, you must perform two actions. First, you mark the file for add, which places the file in a changelist, and then you submit the changelist, which copies the file to the depot.
To add a file to the depot:
If you do not see the local file in the Workspace tab, choose Search>Filter Workspace>Show Local Workspace Files.
Context-click the file and choose Mark for Add. The file icon displays a red plus sign indicating it is open for add.
Submit the changelist containing the file that you marked for add. Context-click the file and choose Submit.... The Pending Changelist form is displayed, listing the files in the changelist. (See Checking your edits into the depot.)
Diffing files to view your edits
To enable you to see what changes you've made, you can compare (diff) your edited file with the version you checked out. To diff, context-click the checked-out file in the left pane and choose Diff Against Have Revision. P4V launches the diff tool, displaying the differences between the two files. For example:
Discarding edits by reverting
If you decide you want to discard your changes:
Context-click the file in the left pane and choose Revert. P4V displays a warning dialog.
Click OK. In the Log pane, P4V displays a message like the following:
Checking your edits into the depot
To check your changed file into the depot, perform the following steps.
Display pending changelists: click  in the toolbar. P4V displays a list of pending changelists, as shown in the following figure. To display the files in a changelist, expand it
Enter a description explaining the changes you made and click Submit. The Log pane displays a message confirming that your changelist was submitted, similar to the following.
Change 813 submitted.
    submit complete. 1 file affected.
Displaying a file's revision history
To view the changes made to a file or folder, context-click the file or folder and choose File History or Folder History. The history for the selected file or folder is displayed in the right pane. For example, the following figure shows the history of a folder, listing every submitted changelist that affected a file in the folder.
Graphical Reporting Tools
P4V includes several valuable graphical reporting tools:
Time-lapse View: shows how the contents of a selected text file changed from revision to revision. You can easily sweep through revision ranges to locate passages of interest and see when they were created and how they changed.
The following sections provide more details about these tools.
Viewing file revisions as a diagram
To display the revision diagram for a file, context-click the file in the left pane and choose Revision Graph. P4V launches the tool, which displays a diagram like the following one.
This diagram shows you when the file was created and how it was branched, and enables you to view details about each version submitted to the depot and navigate through the graph using the navigation map. For more details about the information displayed in the revision graph, consult P4V online help.
Browsing file revisions using Time-lapse View
To browse the changes made to a text file, context-click the file in the left pane and choose Time-lapse View. P4V launches the utility, which displays a screen like the following one.
Using Time-lapse View, you can sweep through all revisions of the file using the slider, noting when changes were made and who made them. Again, for details, consult P4V online help.
Displaying folder history using the folder diff tool
The folder diff tool enables you to see how the contents of a folder have changed: which files have been added, changed, or deleted. To view changes to a folder:
Context-click the folder in the left pane Depot or Workspace tab and choose Folder History. In the right pane, P4V lists changelists that affected the folder, for example:
P4V displays the changes as shown in the following figure. This example shows that, between the selected revisions, a file was edited and checked in. File highlights are color-coded to indicate additions, changes, and deletions. Expand folders and scroll to locate changes of interest. To skip to the next or previous change, click the right and left arrows.
Viewing Streams
Perforce streams are "branches with brains," a containerized approach to managing bodies of related files such as codelines. If your organization uses streams, you'll see streams depots in the Depot pane. Streams depots look like this: . To display the streams in the depot:
Choose the streams depot that you want to view. P4V displays the stream graph, which shows the parent/child relationships and status of the streams; for example:
For detailed information about streams in P4V, consult the online help. For general information, see Introducing Perforce, the P4 User's Guide and the Perforce Command Reference.
Important and Useful Features
Among the many features provided by P4V, the following are especially useful:
The following sections provide more details.
P4V provides tooltips for many objects on the screen. For example, to display the status of a file, hold the mouse cursor over the file in the left pane. P4V displays a tooltip like the following one.
Another example: to display a changelist description, click in the toolbar and hold the mouse cursor over the changelist in the right pane. There are tooltips for all the P4V buttons, too.
Drag and drop
P4V provides drag and drop shortcuts for common tasks. Drag and drop can simplify operations on large groups of files. For example, to check out all the files in a folder, drag the folder to a changelist. To diff two files, drag one to the other. For details about drag and drop shortcuts, refer to the P4V online help.
File views
If you use Perforce to manage graphics files, P4V's thumbnail views enable you to preview the files. To display thumbnails, click the Files tab in the right pane, then select the desired thumbnail size from the title bar.
P4V displays thumbnails as shown in the following example.
Undocking tabs
To keep a tab open, you can undock it. For example, context-click a file and choose File History, then choose Window > Undock Tab. P4V opens it in a separate window, as shown in the following figure.
To restore it to the main window, choose Window > Dock Window.
Setting Preferences
To configure P4V, edit its preferences (Mac: P4V > Preferences, Windows: Edit > Preferences). The File Editor page enables you to associate applications with file types, overriding any operating system associations. The Diff and Merge pages enable you to configure external applications, in case you prefer tools other than those that are bundled with P4V.
Launching P4V Components from the Command Line
If you are a Perforce command line client user who occasionally uses P4V for certain functions, like viewing the Revision Graph or the Stream Graph, you can use P4VC, a command-line tool included with P4V that enables you to launch discrete P4V components from the command line without having to open a full P4V instance. For more information, type p4vc help in the command line.
Migrating from P4Win
If you're moving from P4Win to P4V, here's a list of equivalent operations to help you in your transition.
Add to Source Control...
Applies only to files in the Workspace Tree
Graphical annotation tool
Diff 2 Files, Folders or Revisions
Diff Client File vs. Depot File
Or context- click on file and choose:
Diff Against Have Revision
Integrate Using Filespec or Branchspec
File properties are displayed in the Details pane at the bottom of the Files in Folder view
Remove from Workspace
Revision History...
Alternatively context click on file and choose File History
Alternatively context click on file and choose Open
Check Consistency
Applies only to folders in the Workspace Tree
Find File Matching Pattern…
Find File Under Selected Folder...
Restrict to client view by choosing:
View>Filter Depot>Tree Restricted to Workspace View
(any specification menu)
Navigate directly to desired specification
Show the entire depot by choosing:
View>Filter Depot>Entire Depot Tree
Local View of Client Tree
Show Deleted Depot Files
Show Deleted Depot Files
Favorite Connections
Favorite Connections
Switch Port Client User...
Set Password for (current user)...
Superusers can manage users and groups from within P4V
Next Steps
This guide helps you to start working with files using P4V and points out important basic features, but P4V enables you to do much more: create jobs, branch groups of files, and handle file conflicts that arise in team development settings.
Perforce administrators can perform administrative operations by choosing Tools > Administration. Using the Administration tool, superusers can manage users and groups, along with their access to files and folders within the depot. Some administrative functions must still be performed using the Perforce command-line client (p4). For details, see the Perforce Command Reference and the Perforce System Administrator's Guide.
To become expert with P4V:
Pay attention to the file icons and decorations in the left pane. The decorations and icons display a great deal of information about the type and status of a file.
To get the whole picture, read the P4V online help, Introducing Perforce and the Perforce System Administrator's Guide. The guides, which are available from the Perforce web site, describe the full set of features that the Perforce Server provides. Perforce Technical Support is always ready to help you, and there's a thriving community of Perforce users active on the perforce-user mailing list and the Perforce Forums. Consult our web site for details.

Previous Table of Contents Next

Perforce 2014.1: Getting Started with P4V
Copyright 2005-2014 Perforce Software.