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

• perations.

• 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
• pened 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

path, //project/subproject/whatever.cc, will be copied to c:\workspaces\project\subproject\whatever.c. You can change the right hand path to be whatever you want. Your client spec sets up this arrangement. Once it is in place you don’t often think about

• it. You just find the files you want in the depots, sync them, and expect to find them

under your client’s root directory, in the subdirectories as mapped in your client spec. A note about P4Win: it doesn’t often give you a pop-up if there is a problem. Instead, it prints warnings and errors in the bottom pane, so look there after an operation to see if it succeeded. 7.3 Syncing Files To “sync” in Perforce means to copy a version of file from the server to your client

• workspace. You can sync entire filesystems in one operation, or just one file. The server

doesn’t push newly modified files out to you, you have to ask for them by requesting a

• sync. P4Win displays information to let you know whether you’re up to date or not: after

each filename you see numbers such as #7/7. This means you have version 7 out of the 7 versions of the file. If you see #5/7, it means that two new versions of the file have been checked into the server since you last sync’ed, your copy is out of date. In addition to the version numbers, a yellow exclamation mark appears over the icon for the file if you don’t have the head (latest) revision. A green dot on the icon means that you are up to date. To sync files, right click on the folder or file in the depot pane, and choose Sync->Sync to Head Revision. You can also get older revisions with the other choices, or force the file to be copied again to your workspace. Before you can edit a file in Perforce, you have to have sync’ed a copy of the file to your workspace. When files are sync’ed to your workspace they are always read-only. Perforce won’t overwrite a writable version of a file, it assumes that you made it writable to edit it and want to keep the edits. You can sync to a label, see section 9.1, or a changelist number or even a date and time. Be aware that syncing a top level depot such as boxer:1800 //ai/… can involve hundreds

• f thousands of files and 10’s of gigabytes copied to your machine. It is better to sync at

the lowest level that gives you what you need. Syncing //…, all depots, is almost always a mistake unless you have edited your client spec view carefully to give only what you need. 7.4 Opening a File for Edit Right click on the file in the depot pane, and select Open for Edit. You can do the same with folders, it opens all files below that point for edit. The file is now writable in your workspace, and others will be able to see that you have it open for edit. The red checkmark next to the file in the depot pane indicates that you have it open for edit. Other users will see a blue checkmark, which indicates that someone else has it open. Other symbols displayed in P4Win use the same meaning for red and blue, yours and theirs.

7.5 Perforce Concept #2:The Changelist (submitting a changed file) Once you’ve opened a file for edit, P4Win will look something like the example below: If the right hand pane isn’t the Pending Perforce Changelists pane, click on the blue and red triangles icon, or choose Changelist->View Pending Changelists. The changelist is a concept relatively unique to Perforce. Everything that you have opened for edit or for

• ther modification will be listed in a changelist, usually the Default changelist. This

makes it easy to see what files you are actively working with. It also allows you to check in a group of files in one operation, by “submitting” the changelist. In fact, Perforce only allows you to submit changelists, not individual files. Let’s say I’ve now edited the file TEST.txt from the screen above, and want to submit the changes so that other users can get the new version of the file. I right click on “Default” and choose Submit, to submit the Default changelist. The following window comes up:

You must edit the Description to complete the submission. Provide information about the change, it will be very helpful to those in the future who read the history of changes to the file. If there are multiple files in the changelist, but you are not ready to submit all of them, you can un-checkmark them in the Files box. Click Submit. Your new version of the file will be copied to the server to become a new revision that all users (with access) can see. Perforce automatically gives a unique changelist number to this submission, which you can use to retrieve versions of the files that were submitted. 7.6 Adding a New File to Perforce To add a file to Perforce, create or copy it into your client’s workspace. Then drag and drop the file from Windows Explorer onto a changelist in P4Win. Click OK on the panel asking about how you want to add it; you will probably never need other than the default

• ptions. Then submit the changelist as described above. Once the submit is finished, the

file will be read-only. This can help you keep track of which files you have added. Drag and drop works for folders as well as files, it will add all files in that folder and subfolders below.

It’s important to be aware of the distinction between files that you have synced into your workspace, and files that you have copied or created there. If you’ve synced them, they are version controlled files and you have to treat them specially, see section 8.1, Do’s and Don’ts. If you created or copied the file there, it’s yours to rename, delete, whatever you

• want. Perforce is unaware of the file. You are responsible for backing the file up. So it’s a

good idea to check it into Perforce, which is backed up nightly. Note that you can’t create an empty folder in Perforce. You make a new folder in your workspace, put a file in it, and add the file to Perforce. All folders above the file will then appear in the Perforce depot. 7.7 Diff’ing and Reverting Files Let’s say you have opened a text file for edit, made changes, and are ready to submit it. It’s always a good idea to diff the file against the version in the server’s depot to make sure it has the changes you want before you submit it. Right click on the file in either the depot or changelist pane, and choose “Diff vs. depot” or “Diff file against depot”. You’ll get a color coded listing, lines in red have been removed from your version, and lines in blue have been added. If you have made changes to a file, but decide you want to leave the file as it is, you can “revert” the file. Right click on the file in either pane and click Revert. The open of the file will be canceled, and your copy will be refreshed from the most recent version on the

• server. Any changes you made to the file will be discarded.

7.8 History and Properties of Files Right click on a file in the depot pane, and choose “Revision History”. This is a powerful tool that shows you a list of all previous revisions of the file, with the changelist numbers, associated comments, date, username, etc. You can diff any two revisions of a text file; use the Ctrl key with a right click to pick two revisions. At the bottom left, or midway down the panel on the right, is a checkbox for “Show branching history”. If you don’t checkmark this, you will only see revision history back to when the file was created or branched to its current location. The branching history lets you see deeper into the file’s “genealogy”. If you see a blue checkmark by a file, it means someone else has it open for edit. Right click and choose Properties to find out who it is. See section 7.11 for a chart of symbols such as the blue checkmark. 7.9 Deleting a File In Perforce, to delete a file is to remove it from active use, both in the depot and in your client workspace. It is not really gone, you can still see it by choosing View->Show Deleted Depot Files. You can un-delete it. Only a project super-user such as the Perforce admin for the project can completely remove the file and all its history, with the “obliterate” command. Think before checking in binaries, every byte will be backed up every night for who knows how many years before a consensus decides that it can be

• bliterated. Most of our Perforce storage is used for binaries.

7.10 Renaming or Moving a File or Folder Right click on a file in the depot pane and choose Rename. You will see a panel like the

• ne below, for example:

Edit the New Name line. If you provide a new filename, it is a rename operation, if you change the path, it is a move operation. The Preview button can be helpful if you want to make sure that Perforce will do what you want. Note that Rename sits on top of Perforce’s integrate command. The end result of the

• peration is a branch of the original file, and a deletion of the original file, these two
• perations will appear in your changelist when you confirm the panel above.

7.11 Symbols Perforce uses a number of small icons to help you easily interpret P4Win’s file displays. Here is a breakdown:

• 8. Do’s and Don’ts

8.1 Use only Perforce to rename, move, and delete version controlled files 8.2 Check in often, back up your edited copy 8.3 Sync only what you need 8.4 Perforce security 8.5 Revert unchanged files 8.6 Don’t waste space 8.1 Use only Perforce to rename, move, and delete version controlled files As mentioned earlier, files that you sync to your workspace from Perforce need to be treated differently than other files. If you rename, move, or delete these files with Windows Explorer, for instance, the Perforce server doesn’t know it. Next time you try to sync or edit these files, the server and the client (and you) will be confused, and you’ll have a mess to clean up. The fact that files are read-only when initially sync’ed can help you keep track of your own files that you are preparing to add, for instance, since they will be writable. 8.2 Check in often, back up your edited copy Once you’ve submitted a file, you will always be able to retrieve it from the Perforce server even if your client machine is destroyed. So don’t work on files for long on your client machine without submitting them, unless you have your own backup scheme in

• place. If you’re concerned that your intermediate changes might break things, work on a

branch and integrate your changes back to the main area when they work properly. This allows you to submit new versions as often as you want without affecting others. See section 9.5, Working on a branch. 8.3 Sync only what you need When you create a new client spec, it has the unfortunate default of including every depot in the Perforce instance. If you were to try to sync the entire client spec, you could be asking for 40 gb of files on midway:1700, InDesign, for instance. To sync only what you need, navigate the depot pane, find what you need, right click on it to sync only that area and below. 8.4 Perforce security This is a big topic with ongoing developments. Your local Perforce admin will be distributing information about this to account holders as policies are clarified. For now, it is in your, and Adobe’s, best interest if you set a password. Make it something strong, use letters and numbers, use at least 6 characters. When we upgrade to the next Perforce release in the spring of 2004, you will not be able to access Perforce without a password. Don’t use other’s accounts, and don’t share your password with others. Adobe’s source code is vitally important, but it is only as secure as the weakest link (or missing or bad password). 8.5 Revert unchanged files

Perforce makes the assumption (perhaps not a good one) that if you open a file for edit, and then submit it without making any changes, you really do intend to end up with two identical revisions of the file in the Perforce database. In the case of binaries, this is a tremendous waste of space since Perforce can’t store the revision as a set of diffs with the previous revision; it has to store the whole thing. Before submitting a large set of files, right click on the changelist and select “Revert Unchanged Files”. It will give you a list of files that have not changed. You can trust this list; accept it and you will be left with the files that actually do need to be submitted or reverted. 8.6 Don’t waste space In many projects, users work in their own sandboxes, rather than modifying mainline code directly, until they are ready for their changes to go out to everyone. A common mistake is for a user to sync a copy of the files on the mainline, copy the files to their sandbox workspace, and then add them to Perforce as new files. The right way to do this is to branch the mainline files into the sandbox, see section 9.5. The Perforce server intelligently uses new space only for files that are changed on your sandbox branch, and creates links back to the mainline for the ones that are unchanged. This also sets up a relationship between the mainline files and the branched files so that you can easily get the latest changes out to your branch and integrate your changes back into the mainline. Another big space-waster is adding binary files to Perforce that don’t absolutely need to be there, as mentioned in 8.5. Most of our Perforce storage space is used by binaries, even though there are several times as many text files. Once there are in there, it takes a special obliterate operation by a Perforce admin to get rid of them, and usually a fair amount of time and effort to find out whether they really are needed or not.

• 9. More Operations

You will probably not need these operations right away, but most people eventually need them. 9.1 Lock 9.2 Label 9.3 The command line 9.4 Changing your client spec 9.5 Working on a branch 9.1 Lock Once you have opened a file for edit, you can right click on the filename in P4Win, and choose “Lock”. This prevents anyone from submitting another version of the file before you have submitted yours. It doesn’t prevent them from opening the file for edit,

• however. Don’t lock files unless you know you need to; if you leave files locked and go
• n sabbatical anyone else who wants to change the file in the meantime will be unhappy.

9.2 Label A label is a named list of particular revisions of multiple files. It might indicate a set of files that went into a release, or a point from which a new branch was created. Usually they are created by release engineers. You can sync to a label. Let’s say you want to get the source files that went into last night’s build, labeled “Current_Build”. You would right click on the folder you want to update, choose “Sync->Sync to Revision, Label, Changelist, or Date”, and enter the label name. Note that this will remove Perforce controlled files from your workspace that aren’t in the label. To keep existing files, and

• nly add or update what is in the label, enter the label name twice, separated by a comma.

For instance, “Current_Build,Current_Build”. 9.3 The command line Anything you can do from P4Win can be done from the MS-DOS command line, using the p4 commands. The same commands and syntax work on Windows, Mac, and Unix

• platforms. Type “p4 help” to get started. Another document on how to work from the

command line is in the works. If you would like to see what the equivalent p4 command is for a command you issue via P4Win, in P4Win checkmark Settings->Options- >Perforce Objects -> Show p4 commands in the status pane. Where this is found varies a bit in different P4Win releases. 9.4 Changing your client spec If you make changes to the mappings in your client spec involving where the files go on your local machine, you will get a pop-up afterwards that asks if you want to sync to #have. Do this. If you don’t, the server has to look up each file in each sync operation to see if it has a record of it being in the old place vs. the new place. It will degrade your performance quite a bit. Sync’ing your whole client spec using “redo sync to same revision” (sync to #have) is a good thing to do if you are wondering about your

• performance. Simply adding or removing a depot to the client spec doesn’t require this

sync. Create a new client spec for use on each project, rather than trying to use the same client spec for multiple projects. This will minimize the need to change it. 9.5 Working on a branch This is a topic that will be picked up a document with a deeper scope than this quick start

• guide. Use of branches is often project specific, so it is best to ask your project’s Perforce

admin for advice before creating a branch. Whenever you are tempted to add files to Perforce that are already in Perforce elsewhere, you should be using a branch. Operations with branches are called integrations. Even a simple rename is a branch operation in Perforce, done by integrating the file to a differently named file, and deleting the original.

• 10. Where to get more help.

P4Win has pretty good help built in. More experienced Perforce users on your team and your project’s Perforce admin are probably the next place to go. If you don’t know who

your Perforce admin is, you can look the contact up at http://perforce.sea.adobe.com. There are additional links to help resources there. There are IS Knowledge Base docs on Perforce help resources and how to install Perforce

• n Windows:

Overview of Perforce at Adobe: http://isweb.corp.adobe.com/isweb/iskb.nsf/docs/IS005D46 Installing or Upgrading Perforce on Windows:

http://isweb.corp.adobe.com/isweb/iskb.nsf/docs/IS005CC2

More Knowledge Base docs are planned. They will cover use of the command line, multiple platforms, and more advanced topics. http://perforce.com is Perforce’s corporate website, and has user manuals, etc. If the Perforce server and port you are attempting to contact are not responding, you can check the IS Alerts page, (link on the Inside Adobe home page), to see if an outage has been reported. You can call the Service Desk number on the Alerts page to report an

• utage at any time of the day or night. Be aware that large Perforce projects have nightly

backups that can take from up to 2 hours, which your Perforce admin will know about.