Essential P4V

Home , Perforce, Tab (interface), Window (computing)

Essential P4V

Introduction P4V, the Perforce Visual Client, is a multi-platform graphical interface for Perforce. P4V has a lot to offer. It can help you to perform your daily tasks. It helps you browse the server and your local workspace. It lets you drill down the history of your files and supplies various graphical tools for viewing that history. It can assist you to make educated decisions of how to manage your precious data.

Using P4V on multiple platforms should be quite transparent. All paradigms are the same, although some behavior and look and feel of the windows is platform dependent. P4V currently runs on the following platforms: • Mac OS X 10.2.x or higher • RedHat Linux 7.2, 7.3, 8.0, 9.0 and Suse 7.1 • Windows 2000, Windows XP, and Windows 2003 • FreeBSD 4.4 • Solaris 8

In this talk we'll show you how the program is organized and what functionality is offered. Understanding this will help you to use the program effectively. Connecting to a Perforce Server When you first start P4V, you connect to a server. To connect initially, you need to know a server/port combination.

If the server is up and running, you can browse the server for users and then client workspaces. If you know your user and client workspace name, you can type them in. If they do not exist, you can create them.

There are certain operations that require a client workspace, such as checking files out, submitting changelists, and integrating.

However, there are quite a few tasks that do not require a client workspace: • browse the server • browse documents or earlier revisions of documents in your favorite editor • manage jobs, labels, branch specifications, client workspaces and users

The Recent connections combo box at the top of this dialog remembers the successful connections previously used. You can choose your connection from this list the next time you use P4V. Screen layout Once you connect to P4V, you see a screen that looks like this. Each connection (address/port/user) has its own window. If you are working with more then one connection, you'll have more than one instance of this window.

Here is a quick overview of the parts of the screen that you see:

Left pane This is where you navigate the depot and the client workspace trees. Right pane This is your work area, where you do detailed viewing and editing. Menu bar The command center for all your operations. Tool bar Contains a subset of the most commonly used menu bar commands. Address bar Allows textual navigation and supports bookmarking. Log pane Reports activity as Perforce commands. Status bar Reports server connection information and activity.

Left pane The left pane consists of two tabs that show two trees of directories and files: the Depot tree and the Workspace tree.

Depot tree This browser allows you to see everything in the depot. You can filter it to only show the files that are mapped to your client, or you can view the entire depot. In this view, you can also see deleted files.

Workspace tree This browser only shows information if you are connected to a client workspace. It can be used to browse your local files. You can only see files that are actually in client workspace. You can see local files that are not yet in the depot. You cannot see deleted or unmapped files or files that you have not yet gotten from the depot.

These are the main differences between the Workspace and Depot trees. Your experience using either tree should be the same; it is your preference that ultimately determines which browser you should use.

At the top of this pane you'll see a combo box that you can use to switch workspaces within a connection (server/port/user combination). It is very easy to switch client workspaces in P4V, which makes branching and integrating easier.

Right pane This is your work area. You can view the following items in the right pane by choosing the appropriate selection from the View menu, which opens an appropriate tab.

Files in Folder This view is shown in the Files tab and displays all of the files in the selected folder in the Depot or Workspace tree to the left. • The Files in Folder list shows more details about each file than the Tree pane. • View additional details about each selected file in the lower part of the pane. • Files can be viewed as a detailed list or as thumbnails.

File/Folder History This view is shown in the History tab and will either show the file history or folder history, depending on which object you have selected. • Shows the revision history of the selected file or folder. • Specific revision details are shown in the lower part of the pane. • File revisions can be viewed as a detailed list or as thumbnails.

Essential P4V

Pending Changelists This view shows a list of all pending changelists on the server and the contents of those changelists. • You can view/manage pending changelists and filter the list by user, directory, or file by dragging and dropping or by typing. • Use this view to see which files you are currently working on; the files you have checked out and/or marked for add or delete. • If files are grouped in named pending changelists, each changelist acts as a container of files. • Double-click a changelist to display the Submit form.

Submitted Changelists This view shows a list of all submitted changelists on the server and the contents of those changelists. • Each changelist shows which files were submitted. • You can also see what jobs, if any, were attached. • Double-click a submitted changelist to open the Details pane, showing you more information about that changelist.

Branches, Labels, Workspaces, Users, and Jobs. Each of these views contains a list of these objects on the server to which you are connected. • Double-click an item in the list to open a Details pane. From this pane, you can view details or click the Edit button to edit the object. • The Workspace editor has a View tab which allows you to graphically edit your Client Workspace view. You can include and exclude trees and files by context- clicking those objects. • You can filter the Jobs and Workspaces lists using the field at the top of those panes.

Details When you double-click most of the above objects in P4V, additional information is displayed in the Details tab. • All of the object details that you view are stacked in the Details tab. • You can go back and forth in this stack using the arrows or the pull-down menu.

Working with views All tabs in the right pane can be undocked by context-clicking the tab name and choosing Undock Tab. Once a tab has been undocked into a separate window, you can re-dock it by context-clicking the tab in that window and choosing Dock Tab.

All of the tabs can be closed by context-clicking the tab and choosing Close Tab, or by clicking the X in the lower right hand corner of the right pane while the tab is active.

If you are editing a form and you want to give it some thought, you can “tear it off” by clicking the Tear Off button at the top of the pane. A “Tear off' is a floating instance, which allows you to keep a form you are editing open. It is no longer in the Details stack.

Both the Files pane and the File History pane can also be torn off. This allows you to look at a particular File or File History while browsing somewhere else.

Undocked tabs act the same way that docked tabs do. They are simply a single tab in a separate window. Tear offs are like “snapshots” of a single view at a particular point in time.

Menu bar The menu bar is divided into tasks. Here is a brief overview of the menu bar:

File Look here when you want to create something or perform an action. Of course, this is also where you exit P4V. Edit Here you will find editing and search operations. View Most items in here are for navigation (mirrored in the tool bar). Others are used to set up filters. You'll also find Refresh here. Tools Here you can launch all the integrated tools and set application preferences. Windows Here you can find and manage all undocked and “Torn off” windows. Use this to switch between different connection windows. Help The place to be when you need help. Besides the P4V help files, there is also a “Getting Started with P4V” guide here to help you on your first day.

Toolbar The toolbar is basically divided into two main sections: action and navigation.

Action buttons The first several buttons of the tool bar are used for common actions. If you have an object selected and the button action applies, it is enabled. The buttons are: Refresh, Get latest revision, Check out, Mark for add, Mark for delete, Submit changelist containing file, Revert unchanged files, and Diff files.

Navigation buttons Most of the remainder of the toolbar is used for navigation. The buttons that look like folder tree browsers bring the Depot or Workspace tree to the foreground in the left pane.

The following buttons affect what you see in the right pane: View files in folder, File/folder revision history, Pending changelists, Submitted changelists, Branches, Labels, Client workspaces, Users, and Branches. Theses bring the requested tab in the current connection to the foreground, regardless if they are undocked or not. If the tab is not yet visible, P4V creates it in the right pane. If it was undocked the last time it was closed, it will be created as an undocked pane.

Using these buttons to navigate makes managing undocked tabs easy and avoids mistakes if you are working in more then one connection.

Essential P4V

The last navigation button is a pull down button to navigate your Tear offs. Click on this button and choose from a list of objects you have torn off.

Cancel button Finally, there is a Cancel button to stop operations if they are taking too long or if you’ve changed your mind about performing that action.

Address bar The address bar allows you to type in a path to a directory or file. There is also a pull- down button that allows you to jump to a bookmarked folder.

The Depot or Workspace tree opens with the file or folder selected. P4V opens the appropriate tree, based on the syntax used.

The address bar not only shows navigation, but also follows navigation. This allows you to easily easy cut and paste paths.

Log pane This reports activity in p4 commands and can be helpful as a diagnostic tool.

Status bar The status bar is located at the very bottom of the P4V window. It shows your location as you navigate the Depot and Workspace trees and also shows a barber shop pole when there is server activity. Shortcuts in P4V There are several handy tricks to making your P4V experience better, faster, and more productive.

Opening files quickly Double-click any file or file revision and, if P4V knows the editor for that extension, it opens the file or revision in that editor. This works for both local files and files in the depot.

If you want to open a file in another editor/viewer, context-click it and choose Open With… This allows you to pick another editor or change the default editor for that extension.

You can also drag and drop local files from the Workspace tree onto another program to open it in that editor.

Drag and drop functions In addition to dragging files to an external application, you can use drag and drop within P4V for many other purposes:

Adding files to pending changelists To add files to a pending changelist, drop files onto the changelist in the Pending tab, or onto the Files field of the Submit dialog.

Adding a job to a pending changelist To add a job to a changelist, drag the job from the Jobs tab to the Jobs field of the Submit dialog.

Moving files between changelists To move a file from one changelist to another, drag files from the source changelist to the target changelist on the Pending tab drag files or drag files from the source Submit dialog to the target Submit dialog.

Getting revisions of files You can get revisions of a file or group of files at a particular submitted changelist, client workspace, label, or file revision. Context-click a file or directory and choose Get Revision... This brings up a dialog that allows you to select which revision you’d like to get. Drag the desired submitted changelist, client workspace, label, or file revision to that dialog and drop it on the field where you specify revision.

Using labels To label a file or set of files, drag a file or a folder to a label. Alternately, you can drag the label onto a file or folder.

Integrating files If you have this option set in Preferences, you can integrate from one directory to another by dragging the source directory to the target directory.

Diffing files If you have this option set in Preferences, you can diff two file revisions by dropping a file or a file revision onto another file revision.

Filtering changelists To filter the pending or submitted changelists displayed in the left pane, drag files or folders from the Tree pane to the filter field at the top of the changelist pane. Tools P4V provides a number of graphical tools to help you work better. These tools are useful for performing various SCM tasks, as well as viewing and processing information.

Essential P4V

Diffing files There are several ways to diff two files in P4V. You can drag files/revisions onto one another. You can also select two files and click Diff on the tool bar, choose Tools>Diff from the main menu, or press Ctrl+D.

The diff tool allows you to view the files side by side or in a combined view. You can set options like font, tab spacing, character encoding, and ignore whitespace in the diff tool’s Preferences dialog.

You can also use your favorite diff tool instead by choosing that tool via Preferences in P4V.

Folder diff When viewing the history of a folder, you can bring up folder diff by dragging one revision of a folder onto another.

While using folder diff, you can double-click any of the files to diff the two file revisions.

Resolving There are different reasons why you would need to resolve conflicts in a file: • After you've checked out a file and started working on it, another person changed the file. You can no longer simply submit the file. You have to resolve the differences. • If you integrate a file between branches or to a mirror file, there are possible conflicts needing to be resolved. • If you have a file checked out and then tell P4V to get the latest revision, it won’t overwrite your content and update the file because you are working on it. Instead, P4V schedules a resolve. Whenever you are ready, you can take the next step and perform the resolve. After that, you will have the latest revision, including your changes. If the file in the depot has changed since you had P4V get the latest revision, it will schedule a second resolve. You must complete each scheduled resolve separately.

Resolving can be confusing, but the P4V has a helpful Resolve dialog to step you through the process. You can bring up the Resolve dialog from the following objects by context- clicking and selecting Resolve from the context menu: • a file that needs resolving • a directory, to resolve files in that directory and its subdirectories • a pending changelist containing files that need resolving

Essential P4V

If you have more then one file that needs resolving, use the Resolve dialog to do an Auto- resolve:

If you only have one file, or if you have conflicts remaining after an Auto-resolve, you have to resolve interactively.

The interactive resolve dialog will advise you what to do. When resolving interactively, you can diff files and view file history. You can edit the resulting file, either with a merge tool or with your favorite editor.

The Resolve dialog guides you through the resolve process until you either resolve the conflicts or cancel the process.

Merge If auto-resolving leaves you with conflicts, you need to use a merge tool to resolve your conflicts.

The goal of resolving is to fix possible conflicts between the source and the target file and put the result in a merged file.

The merge tool will present you with four views: • source file • target file • common base of both files • resulting merged file

If you are not interested in the common base, and you can hide this view.

The bottom pane shows you the merged result with the differences and conflicts in color. The color matches the icons representing source/target/base. Click on the icons to the right of each line to choose either one version or the other. If you want both versions, shift-click the associated icons.

Essential P4V

If the conflict is a little more complicated, you can use a combination of selecting text and typing directly. This will disable clicking the icons. You can use Undo to get back to a selection state.

Plus (+) and minus (-) symbols overlaying the icons to the right indicate additions or deletions instead of simple edits.

Revision Graph The history of a file is not necessarily hierarchical. You might have branched a file more than once or a sibling might have developed a life of its own somewhere else. If you want to see the whole picture of a file’s life, you can use revision graph to see the complete file history, branches, and offshoots.

Using revision graph, you can: • see all branches and all integrations • look at the details of every revision • compare revisions

A filter allows you to determine which branches are shown in the revision graph. This limits the amount of data shown in the graph. Click the directory tree icon in the upper left hand corner to access this filter.

To diff two revisions, drag one revision onto another. You can also shift-click to select two revisions in the graph, then click the diff button in the toolbar.

The highlighting feature shows all revisions that directly contributed to the selected revision (shown in yellow) and also all revisions to which that revision later contributed. You can use the filter to show only the highlighted revisions in the graph.

The shapes in revision graph have specific meanings, including edit, add, delete, merge, etc. Click the Legend tab in the lower right pane of the screen to view the meanings of these shapes while using the tool.

Time-lapse View Time-lapse view allows you to look at all the changes made in a file over a specified period of time. To see this in action, set the mode to Multiple revisions.

At the top of time-lapse view, there is a range selector. By default, this shows Revisions, but you can change the scale to Dates or Changelists.

Set the Content range, either by using the slider or entering numbers in the Content range fields, to get a visual of everything that has changed between those revisions.

The two Details panes at the bottom of the screen show details of the beginning and ending selections.

If you are interested in a certain chunk, you can select it in the vertical bar on the left. The selected chunk is highlighted yellow. The Details panes then report on the first and last revision of the selected chunk. If the selected chunk still exists in the current code, the last revision Details pane is empty.

Essential P4V

The Integrations tab allows you to open another time-lapse view window and drill down to the file history in another branch.

The colors in time-lapse view have the following meanings: Black unchanged text Blue added text Red deleted text

The shapes in time-lapse view also have meaning; the curved shapes mean that a chunk of code has been replaced within this range. Conclusion You should be more confident now to explore P4V and use it to your advantage. To learn more about the product while using it, select an item and press F1 for Help. P4V will provide you with the appropriate information. Be sure to hover over items and buttons in P4V and read the tooltips; they might give you just the information you are looking for.

To get up-to-date information about P4V, please visit our website: www.perforce.com.