Perforce 2012.1: P4SCC User's Guide

Chapter 4

Microsoft Visual Studio

This chapter describes how to perform Perforce source code control tasks in the Visual Studio environment using P4SCC. .

Note	As of June 2012, the preferred Perforce plug-in for Microsoft Visual Studio is P4VS, The Perforce Plugin for Visual Studio. For more information, see the P4VS User's Guide.

This chapter assumes that the Perforce SCC Plug-in is installed and that your client machine can communicate with the Perforce server. For details about configuring settings, see Configuring IDEs with plug-ins.

This screen illustrations in this chapter show Visual C++, but the same dialogs are displayed regardless of which Visual Studio IDE you use. The wording of menu options varies slightly among various version of Visual Studio, but the sequence of operations and dialogs in the tasks is the same.

Note	The version control dialogs displayed for check in, check out, and undo checkout include comment fields, but these comment fields are not stored by the Perforce SCC Plug-in. To avoid displaying the check in dialog, choose Check-in Now.

Configuring Visual Studio with Perforce

Before you can associate any Project or Solution with Perforce, you must configure Visual Studio to use the Perforce plug-in.

Perform the following steps:

1.	From within Visual Studio, choose Tools>Options.

2.	Select Source Control>Plug-in Selection.

3.	In the Current source control plug-in drop list, select Perforce SCM.

After you have configured Visual Studio to work with the Perforce SCC Plug-in, project settings are specific to the project you are working on. Visual Studio retains project settings from session to session and it is not necessary to re-enter them.

When you create a project you intend to manage with Perforce, specify a location that resides within the root folder of the workspace you intend to use as illustrated in the following figure.

Basic versioning tasks

This section tells you how to perform the following tasks.

•	Adding a project to the depot.

•	Adding files

•	Checking files out

•	Retrieving files from the depot

•	Checking files in

•	Resolving file conflicts

•	Diffing files

•	Reverting files

•	Miscellaneous tasks

Also note that the Exclude from source control option is intended for files that, by nature, do not belong under source code control (such as build outputs).

Adding a project to the depot

Make sure your Visual Studio projects reside within your Perforce client workspace.

If you are adding a solution that contains a large number of projects, you can avoid specifying settings manually for every project by choosing the Options > Connection tab setting Bind to the workspace that matches your Perforce environment settings and setting P4CLIENT and P4PORT to the desired server and workspace.

To add a Visual Studio project to your depot, perform the following steps:

1.	In the Solution Explorer, right-click the project and choose Add Solution to Source Control. If you enabled the Show the Perforce Connections option on the Preferences > Connection tab, the Open Connection dialog is displayed, as shown in the following figure.

2.	On the Open Connection dialog, enter the required settings as follows:

•	Server: the name of the host computer running the Perforce server in which you want to store the project.

•	Port: the port number on which the specified Perforce Server accepts commands.

•	User: the Perforce user name you want associated with the version management operations you perform on the project. To choose from a list of users defined for the specified server, click Browse.

•	Password: the user's password, if any.

•	Workspace: the Perforce workspace associated with the version management operations you perform on the project. You must save the project in a folder under the workspace root. To choose from a list of workspaces defined for the specified server, click Browse...

3.	Click OK to dismiss the dialog.

4.	In the Solution Explorer, right-click the solution and choose Check In...

(If the Visual Studio Check In dialog is displayed, dismiss it.) The Perforce Submit Changelist dialog, listing files, is displayed.

5.	Enter a description in the description field and click Submit. Your files are added to the depot. (Using Perforce, you can verify that the default changelist has been submitted and the files are now in the depot.)

Checked-in files are displayed with a lock icon. If you attempt to edit a file that is not checked out, a check-out dialog is displayed.

Adding files

When you add a file to a project, you must also add it to source control as follows:

1.	To open a file for add, choose Add New|Existing Item.

2.	To submit a file, select the file and choose Check In Now.

To list the files that are opened for add, choose Show Pending Checkins.

Checking files out

To check out files:

1.	In the Solution Explorer pane, right-click the desired file (or the project, if you want to check out all its files) and choose Check Out For Edit... The Check Out dialog is displayed.

2.	Click Check Out. In the Solution Explorer pane, files are displayed with a check mark, as shown in the following figure.

The checked-out files are listed in the Pending Checkins pane.

If you branch a project using Perforce, the Visual Studio bindings must be corrected to correspond to the project's new location. To correct bindings for a branched solution, you must perform the following steps the first time you check out the branched project.

To check out a newly-branched project (first time only):

1.	Choose File> Source Control > Open from Source Control.... The Open Connection dialog is displayed.

2.	Specify connection settings for the server that contains the project you want to check out and click OK. The Open Project dialog is displayed.

3.	Browse to the branched project you want to open and double-click its .sln file.

4.	If the newly-branched files are present in your workspace, Visual Studio displays the following dialog:

5.	Click Overwrite. Visual Studio displays the Open Solution dialog.

6.	Double-click the .sln file. Visual Studio displays the following dialog.

7.

Click OK.

The project now contains correct binding information.

Retrieving files from the depot

To get the most recent revision of a file from the depot, right-click the file in the Solution Explorer pane and choose Get Latest Version.

To retrieve revisions prior to the head (latest) revision, you can sync from the Revision History dialog or perform the following steps:

1.	In the Solution Explorer pane, right-click the file and choose View History. The History dialog is displayed, listing the revisions in the depot.

2.	Right-click the desired revision and choose Get This Revision.

Note	If you retrieve a file that you already have checked out, for example, to obtain changes checked in by another user, Perforce requires you to resolve the file, to ensure that you don't inadvertently overwrite other users' changes.

To sync all files for a project that resides in the depot:

1.	Choose File > Source Control > Open from Source Control... The Open Connection dialog is displayed.

2.	Enter the settings that specify the server where the project is stored and the client workspace and user with which you want to check the project files out, and click OK. The Perforce Open Project dialog is displayed.

3.	Browse to the .sln file for the project you want to sync and click OK. The project files are synced to your workspace.

Checking files in

After editing checked-out files, you must check them into the depot. Your edited files become the head revision in the depot. (If your changes conflict with changes previously submitted by another user, the check-in fails and the differences must be resolved using Perforce.).

To check in files, perform the following steps:

1.	In the Solution Explorer pane, right-click the file and choose Check In Now. The Submit Changelist dialog is displayed.

2.	Enter a description of your changes and click Submit.

In the Solution Explorer pane, the check marks are replaced by locks, indicating that the submitted files were checked in.

Note	To produce meaningful change history, check in related files together. For example, if you changed two different files to fix a bug, check them both in at the same time. The files are submitted in the same changelist.

To view all your pending changelists, click the Manage Changelists button on the Submit Changelist form. P4SCC displays a dialog listing your pending changelists. In this dialog, you can move files among changelists by dragging and dropping them.

Resolving file conflicts

If you encounter conflicts when checking in files, (for example, from multiple users working on the same files,) you must resolve the conflicts before you can submit the files. Perforce notifies you that resolution is required by displaying the following message in the Pending Changelist dialog:

To resolve file conflicts:

1.	Right-click the file that has conflicts and choose Get Latest Revision.

The file is now scheduled for resolve, indicated by the message "Resolve this file before submitting."

2.	Right-click the file and choose Resolve... The Resolve dialog is displayed, describing the extent of the file differences and listing the following options:

•	Accept Merge: merge both files and accept the result, including both the changes you made and the changes made by other users.

•	Accept Yours: check your changes in, overwriting the most recently checked-in version.

•	Accept Theirs: discard your changes and preserve the other user's changes.

•	Run Merge Tool: launch the merge utility so you can view the differences between your version and the most recently checked-in version. Using the merge utility, you can select individual passages or enter new changes to create the final version that you check in.

•	Other choices: you can view either file (Open File...), diff your file with the conflicting file, display the file's revision history either textually or graphically.

After you choose how the files are resolved, the Submit Changelist dialog is redisplayed.

3.	Enter a description of your changes and click Submit. Your changes are checked in.

Diffing files

To diff a file you are editing with the head revision in the depot, right-click the file and choose Compare Versions....

To diff two revisions of a file, perform the following steps:

1.	In the Solution Explorer pane, right-click the file and choose File > History. The History dialog is displayed, listing the revisions in the depot.

2.	To diff two revisions, drag one revision to the other.

The diff utility is launched, displaying file differences.

Reverting files

To discard changes you've made to a checked-out file and reload the head revision from the depot:

1.	In the Solution Explorer pane, right-click the file and choose Undo Checkout... The Undo Checkout dialog is displayed, listing the files to be reverted.

2.	Check the files you want to revert and click Undo Checkout.

In the Solution Explorer pane, the reverted files are displayed with a lock icon, indicating that they are no longer checked out. The head revision is copied from the depot to your workspace, overwriting any changes you made to the workspace file.

You can also revert unchanged files from the Pending Changelist dialog.

Which files do I put in the depot?

Visual Studio adds all appropriate files when the project is first added to source control, so, in general, don't change the contents of the changelist that is created when you choose Add to Source Control.

Miscellaneous tasks

To view the Perforce commands issued by the plug-in, choose View>Other Windows>Output and display the Source Control pane.