How Perforce Works

Perforce is an enterprise version management system in which users connect to a shared file repository. Perforce applications are used to transfer files between the file repository and individual users' workstations.

The relationship between Perforce clients and the Server.

This document assumes that the Perforce versioning service has already been installed, configured and running. To set up and configure Perforce, see the Perforce Server Administrator's Guide: Fundamentals.

The Perforce Versioning Service

The Perforce versioning service manages shared file repositories, or depots. Depots contain every revision of every file under Perforce control. Perforce organizes files in depots into directory trees, like a large hard drive. Files in a depot are referred to as depot files or versioned files. The service maintains a database to track change logs, user permissions, and which users have which files checked out at any time. The information stored in this database is referred to as metadata.

Metadata within the Perforce Server.

The Perforce service uses native operating system capabilities to manage the database and the versioned files, and requires no dedicated filesystems or volumes.

Perforce applications

You use Perforce applications to communicate with the versioning service. Perforce applications enable you to check files in and out, manage conflicts, create development branches, track bugs and change requests, and more. Perforce applications include:

  • P4, the Perforce Command-Line Client, for all platforms

  • P4V, the Perforce Visual Client, for Mac OS X, UNIX, Linux, and Windows

  • P4Web, the Perforce Web Client, a browser-based interface to Perforce

  • Swarm, the Perforce code review and social coding application

  • Commons, the Perforce collaborative documentation management application

  • Integrations, or plug-ins, that work with commercial IDEs and productivity software

With Perforce, you never work directly on files in the depot. Instead, you use Perforce applications to manage a specially-designated area of your workstation called a client workspace. A workspace contains a local copy of a portion of a depot.

Workspace mapping.

When you retrieve files into your workspace, your Perforce application requests the files from the shared file repository. To keep network traffic to a minimum, the service keeps track of which files you (and other users) have retrieved. Perforce applications do not require a persistent connection to the versioning service.

To use Perforce, you must configure your Perforce application to connect to a Perforce service, specify a location on your local hard drive to hold your workspace, and select a subset of depot files with which you intend to work.

Connecting to the service

To work with Perforce, you must connect to the shared versioning service. Your Perforce application communicates with the service over TCP/IP, optionally secured with SSL. Perforce applications need to know the protocol, address and port of the Perforce repository with which they communicate.

The address and port are stored in the P4PORT environment variable. Depending on the application you are using, the process of configuring this variable is referred to as setting your port, or connecting to the service.

Setting the port for client to server connections.

The documentation and online help for your Perforce application contain information on how to set your port. If you don't know the port setting used for connecting to your organization's Perforce installation, ask your Perforce administrator.

Mapping files in the depot to your workspace

Perforce applications manage files in a designated area of your local disk, called your workspace. As the name implies, your workspace is where you do most of your work. You can have more than one client workspace, even on the same workstation. The top level directory of any workspace is called the workspace root.

To control where the depot files appear under your workspace root, you must map the files and directories on the shared versioning service to corresponding areas of your local hard drive. These mappings constitute your workspace view.

Workspace views:

  • Determine which files in the depot can appear in a workspace.

  • Map files in the depot to files in the workspace.

Client workspace views consist of one or more lines, or mappings. Each line in your workspace view has two sides: a depot side that designates a subset of files within the depot and a client side that controls where the files specified on the depot side are located under your workspace root.

Mapping files from client to server.

Creating a workspace doesn't transfer any files from the depot to your computer. The workspace and its view merely define the mapping that controls the relationship between the depot and your workspace when files are transferred.

To learn more about how to set up the mappings that define your workspace, see the documentation and the online help for your Perforce application.

Other configuration options

Other options for your workspace enable you to control the default behavior of various operations within Perforce. For instance, you can control carriage return/linefeed translation for cross-platform development, or select a preferred text editor or merge utility for use within Perforce. To learn more about these and other options, see the documentation for your particular Perforce application.