Perforce Quick Start Guide for Windows First draft for knowledge - PDF document

Perforce Quick Start Guide for Windows First draft for knowledge base For general access, not IS internal Version 1.0 Stanton Stevens 10/24/03 – updated 1/16/04 Document index: (should be links to sections) 1. Introduction 2. What needs to be done before using this guide. 3. VERY quick start list of steps. 4. What is Perforce and Source Code Management? 5. Perforce server and client model 6. Creating a client 7. Basic operations 8. Do’s and don’ts 9. More operations 10. Where to get more help. 1. Introduction This document will help you configure your Windows Perforce client so that you can begin using Perforce for version control. It will explain what version control is, and how it is done via Perforce. General operations in Perforce will be described, with screen shots. 2. What needs to be done before using this guide: Before you can configure your Perforce client, you will need to: 1. Determine which Adobe Perforce project you want to access. The correct way to specify this is by server name and port number. For example: boxer:1800, alaska.corp.adobe.com:1700, redcloud.corp.adobe.com:1850, etc. See < Overview of Perforce at Adobe > 2. Arrange with the project’s Perforce admin to give you access. 3. Install a Perforce client on your machine. See < Installing or Upgrading Perforce in Windows > for more information. When these things are in place, you are ready to configure your client and begin using it. This document will cover how Perforce works and then specific screenshots of common operations.

3. VERY Quick Start list: If you are in a really big hurry, and already have some knowledge about Perforce, here is how to get started in as few words as possible: 1. Open P4Win. 2. Make sure it is pointed at the correct machine:port, use Settings->Switch Port Client user if necessary. 3. Click ClientSpec->New. 4. Edit the root path, delete unneeded view paths, save. 5. Find the files in the left hand pane list that you want, right click on folder or file names, sync to head revision. 6. You are ready to right click on files to open them for edit. 7. Use the Changelist window to manage what you have in progress, right click on a changelist and choose Submit to check in your changes. 8. To add new files to Perforce, drag and drop the files onto changelists, they will then be opened for add and ready for submission. 9. Only use Perforce to move, rename, or delete files that are under source code control. Using Windows Explorer to do these things will cause you big headaches. 4. What is Perforce and Source Code Management? SCM – Source Code Management Perforce is an SCM tool, which means it is all about keeping track of files. It not only keeps all the old revisions of files so that you can look back to see what changed, it helps prevent people from overwriting the changes that someone else makes to a file. It lets you use a label to group an exact set of file revisions for building, for handing over to QE, for a release, etc. Files in Perforce storage are backed up nightly. Perforce has its own access controls, but if you have access to a Perforce instance, you can work with files on Windows, UNIX, and Mac platforms, the command line interface is the same on all of them. 5. Perforce server and client model Perforce Concept #1: It is a Client – Server system. You operate as a client of the Perforce server. The server has a database of all the files, with their past revisions. You use your client to get copies of a certain set of revisions of files, usually the “head” or latest revisions of the files you are working with. These files are copied to your local machine in a “sync” operation. The place on your machine where you keep these copies is called your “client workspace”. When you sync the files, they are initially read-only in your workspace. When you open them for edit using Perforce, they become writable. When you “submit” your changed files or add new files, they are copied back to the server and the local copies are again made read-only. You configure your client mainly for the following reasons:

1. The server needs to know where to copy files to on your local machine. 2. The client specifies what files you are interested in so that you don’t end up syncing 100 gb of files when you really want just one folder. Once you’ve configured your client, you will probably not need to change it often. If you start a new project, create a new client for it. There are a couple of client options that you might want to change, especially if you are accessing the server through a narrow bandwidth network, but we’re going to focus on basic client use that applies to everyone. 6. Creating a client Start P4Win. If the installation succeeded it should be at Start->Programs->Perforce- >P4Win. Ignore the error message about no client, you are about to create one. Make sure that you are pointed at the correct Perforce server and port. In the window header you should see the machine and port name that you used at installation, redcloud:1680 for example. If this is incorrect, use Settings->Switch Port Client User to fix it. Choose ClientSpec->New. Enter a name for your client. A good format for a name is user_machine_project. This makes it easy to see what the client is for and where you can use it. It groups your clients in the client listing, and it helps the admin know who to contact about the client. You will then see the client spec. configuration window, example below:

Edit the Root field. This is the path to your local workspace, where you want Perforce to copy files, and where you will work with them. Every client spec must have its own unique path, things get very messy if two client specs are both trying to use c:\ for the root path, for example. Something typical would be: c:\workspace\projectname Edit the View field. This contains a list of “depots” or top-level Perforce folders. Delete depots for projects that you aren’t interested in, by deleting the line. Delete depots marked “remote”, you won’t need them and it can save you a lot of time later. Click “Update” to complete the client spec creation.

It is a good idea to make this new client your default client, so that it is used automatically when you start P4Win. To do this, choose ClientSpec->View Client Specs. Right click on your new client spec, and choose Set Default Client to yourclientname. You can also choose to edit the client spec, which will present the same window as you saw at client creation. 7. Basic operations (these should be links to the appropriate subsection) All of these operations can be done from the command line on any platform. For this document, we’ll use screen grabs showing how to do it with P4Win. 7.1 Setting Your Password and User Data 7.2 Navigating the Perforce Filesystem 7.3 Syncing Files 7.4 Opening a File for Edit 7.5 Perforce Concept #2: the Changelist 7.6 Adding a New File to Perforce 7.7 Diff’ing and Reverting Files 7.8 History and Properties of Files 7.9 Deleting a File 7.10 Renaming or Moving a File or Folder 7.11 Symbols 7.1 Setting your Password and User Data Choose “User->Set Password for username”. Adobe’s source code is precious, protect it with a password. Don’t share your password with anyone, that way you will always know it was really you who did what the Perforce history says was done in your name. You can set your password for multiple Perforce projects at the same time using the IS Perforce website: http://perforce.sea.adobe.com. Log in with your Adobe email name and password. This will also tell you which Perforce projects you have an account in. 7.2 Navigating the Perforce Filesystem There are two views of the Perforce file storage, the server view and the client view. The large pane of the left side of P4Win is showing you the server view, how the files are stored in the server. Top level folders in Perforce are called “depots”, and are written as //depot_name/…; … is a wildcard meaning everything below that folder. In P4Win, the folders below can be expanded similar to Windows Explorer. In Perforce, you can refer to a file by its depot (server) path, such as //project/subproject/whatever.cc, or by the client path. In the client spec you just created, the “View” box lists how the depot paths map to your local client paths. For instance, if you have a line in your View box like: //project/subproject/… //myclient/project/subproject/… it means that files found on the server in //project/subproject will be copied to your local machine under your root path, also part of the client spec, followed by /project/subproject. So if your root path is c:\workspaces, the file at the following server