Previous Table of Contents Next
Perforce 2013.3: P4VS User's Guide



Chapter 2
This chapter discusses how to manage files using P4VS.
Putting a project or solution under Perforce source control
P4VS requires that your work be included in a project or solution file.
To put existing projects or solutions solutions under Perforce source control:
1.
Make sure that your projector solution and all files included in it are in the workspace (your client directory) being used by your Perforce service connection.
2.
To put new projects or solutions under Perforce source control:
1.
When you create a new project using the New Project page, select Add to Perforce SCM under the Browse button.
When you click OK (and after you run any wizards), the Open Connection dialog appears.
Enter your Perforce connection settings. Make sure that your project or solution files are in the workspace (your client directory) being used by your Perforce service connection.
2.
Adding files to the depot
To add a file to the depot, you must perform two actions:
1.
2.
To open a file for add:
1.
In the Solution Explorer, browse to the file you want to add. If a file does not reside in the depot, its icon is marked with a blue question mark.
2.
Context-click the file and select Mark for Add. A P4VS dialog opens asking you to add the files to the Perforce depot.
3.
4.
Click OK. The file icon in Solution Explorer displays a red plus sign indicating that it is open for add.
To submit the changelist:
1.
In the Solution Explorer, context-click the file and select Submit.
2.
In the Submit Files dialog, enter a description of the change and click Submit. The new file is added to the depot..
If you add a file to a solution that is already under Perforce control, you are prompted to put the new file under Perforce control. If you enabled the Automatically add new files to Perforce option and disabled the Prompt for changelist when checking out or adding files option under Tools > Options > Source Control, the file is marked for add and placed in a changelist without any prompting. For more information about these options, see Setting Perforce preferences.
For more information, see Checking in files and working with changelists.
Opening a project or solution in the Perforce depot
To open a project or solution that has been checked into a Perforce depot:
1.
Go to File>Perforce>Open Solution/Project in Perforce Depot.
2.
In the Choose Solution/Project in Depot dialog, expand the tree to find the solution or project you want to open.
Select Filter by client workspace to limit the depot tree to the solution and project files that are included in the current workspace view.
If you cannot expand and view the contents of the depot tree, you are not connected to a Perforce service. Click Open Connection to connect.
3.
Click the file and click OK to open it in Visual Studio.
Retrieving files from the depot
You can retrieve the most recent revision or any previous revision of a file from the depot to your workspace. In the Solution Explorer, open the folder containing the file you want to retrieve. The icons indicate the status of the files; see This chapter provides an overview of P4VS, the Perforce Plugin for Visual Studio, as well as instructions for installing and setting it up. for details.
To get the latest revision:
1.
2.
Select Revisions>Get Latest Revision.
To get a previous revision:
1.
2.
In the Get Revision dialog, specify the revision you want:
Under Get or replace the following files/folders, you can select specific files or folders to retrieve.
To to specify a revision by changelist number, label, workspace, or date, choose the method from the Specify revision using: drop-down list and specify the value in the edit field.
Select Force Operation to retrieve the selected revision into your workspace even if the workspace already has the file. This option does not affect open files.
Select Only get revisions for files listed in changelists to retrieve only those files that are included in changelists.
If you are specifying a revision by label, you can ensure that your workspace contains only the labeled file revisions by selecting Remove files from workspace if they are not in label.
3.
Click Get Revision to retrieve the files to your workspace.
Checking out and editing files
Before you edit a file, you must check it out of the Perforce depot.
To check out and edit a file:
1.
If necessary, retrieve the correct revision to your workspace. For more information, see Retrieving files from the depot.
2.
Checkout <filename> to check out only the selected file
Checkout All in Project to check out the project file and all files in the project
Checkout All in Solution to check out the solution file and all files in the solution
When you check a file out, it is placed in a changelist.
3.
4.
To check your revised version back into the depot so that other users can view your changes and edit it, context-click the file and choose Submit...
In the Pending Changelist dialog, enter a description of your changes and submit the changelist that contains the file. For more information, see Checking in files.
To display a file without checking it out, double-click the file icon. It opens in read-only mode.
To lock a file to prevent others from checking it out while you are working on it, context-click the file icon and select Manage Files>Lock. To unlock it, context-click and select Manage Files>Unlock.
When you try to edit or save a file that is checked into Perforce, P4VS asks if you want to check it out (and save it, if you are attempting a save). It also gives you the following options:
Don't show this dialog again (always use the default changelist): always check out (when opening for edit) or check out and save (when saving edits) and add to the default changelist, without prompting from P4VS.
Do this for all files being saved (or edited): if your save or edit operation involves multiple files, select this option to check out (when opening for edit) or check out and save (when saving) all files in the current operation without having the P4VS dialog prompt you for each file individually.
Checking in files and working with changelists
To check in a file, you must submit a changelist. Whenever you mark files for add or delete, check them out, integrate (merge or copy), or schedule them for resolve, the files are added to changelists. Perforce changelists are lists of actions to be performed on files. The actions in the changelist are performed when you submit the changelist. Pending changelists are changelists that have yet to be submitted. Changelists are assigned unique numbers by the Perforce service. In addition, a default changelist is maintained for each client workspace. If submission of the default changelist fails, the Perforce service assigns it a number.
Checking in files
To check in files (submit a changelist):
1.
Open the Submit dialog by doing one of the following:
Context-click the file icon of a file that is checked out, marked for add, or marked for delete, and choose Submit... to open the Submit Files dialog.
Go to View>Pending changelists, context-click a changelist, and choose Submit... to open the Submit Files dialog.
Note that the Submit Changelist and Submit Files dialogs are functionally identical; they differ only in how you access them.
2.
In the Submit Changelist or Submit Files dialog, enter a description or edit the existing description, and select the files you want to check in.
You can also perform the following actions:
Revert unchanged files in the changelist (removing the unchanged files from the changelist, canceling the check-out, and leaving them synced to the version you originally checked out) or submit only changed files (moving the unchanged files to the default changelist after the current changelist is submitted).
3.
(Optional) Click Save to save your changelist options without checking in files.
4.
Click Submit to check in your files.
Displaying changelists
To display changelists:
1.
Go to View>Pending changelists or View>Submitted changelists to open the Pending or Submitted tool windows.
To change the order in which columns are displayed, drag the column headings right or left to the desired position. To sort by column, click the sort arrow on a column heading.
2.
Enter your filter criteria in the Folder/file, User, and Workspace fields.
To filter by file, enter the full path of the file in the workspace. The filtering process is case-sensitive.
Click Filter.
3.
Editing changelists
You can edit and perform actions on a pending changelist using the Pending tool window and the Pending Changelist dialog.
To edit a changelist from the Pending tool window:
1.
Go to View>Pending changelists.
2.
3.
To edit a changelist from the Pending Changelist dialog:
1.
Go to View>Pending changelists.
2.
Open the Pending Changelist dialog by context-clicking the changelist in the viewer and selecting Edit Pending Changelist 'changelist name'.
3.
4.
Click OK to save your changes.
Restricting access to changelists
By default, all users can view a pending or submitted changelist, regardless of whether they are permitted access to the files in the changelist by the protections table. To prevent users from seeing a changelist, check the Restrict Access to Changelist option when you edit a pending or submitted changelist.
This option enables the following restrictions:
Moving a file to another changelist
To move a file from its current changelist to another one, do one of the following:
Context-click the file in Solution Explorer and select Manage Files>Move to another Changelist... .
In the dialog that opens, select the changelist you want to move the file to.
Setting changelist display preferences
To minimize the time it takes P4VS to handle very large changelists, limit the number of files displayed in a changelist by setting the Maximum number of files displayed per changelist field in the Perforce preferences under Tools>Options>Source Control. See Setting Perforce preferences.
You can still submit changelists with more than the specified number of files, but the file lists are displayed as follows:
Pending and Submitted tabs display "There are ### files in this changelist."
Details tab displays the list of files in a simple text box (with no P4VS file badges).
Resolving conflicting changes
Conflicts occur when you attempt to integrate a file into an existing codeline or to submit a changelist containing a file that another user has edited and submitted while you had the file checked out. When the conflict occurs, Perforce schedules the file for resolve. Conflicts must be resolved before you can submit the changelist that contains the conflicting file.
When you attempt to submit a changelist containing a file that must be resolved, a Perforce Command Error is returned: "Merges still pending--use 'resolve' to merge files." When you return to the Solution Explorer, you will see a red question-mark badge next to the file icon in Solution Explorer : (You may need to context-click the file icon and select Refresh to see the question-mark badge).
If there is a yellow triangle badge on any file, get the latest revision of that file by context-clicking it and selecting Revisions>Get Latest Revision. This will not overwrite the copy of the file that is in your workspace. After you have the latest revision, you can resolve the file. You can resolve files individually or attempt to resolve multiple files at once.
Note on terminology: In the P4VS Resolve dialog, Target is the file in your workspace and Source is the file in the depot.
Resolving multiple files
When there are multiple files in a changelist that need to be resolved, it is recommended that you first try to resolve them automatically.
To resolve multiple files at once, automatically:
1.
2.
In the Resolve dialog, select Auto resolve multiple files.
The dialog displays the Files to Resolve. As files are resolved, they are removed from this list.
3.
Select whether to Merge binary files as text when resolving content.
If you select this option, P4VS treats binary files like text files and attempts a textual merge between the source and target files.
4.
Select a Resolve method:
Safe automatic resolve (no merging): Accepts the source file (the file in the depot) if it has the only changes. Accepts the target file (the file in your workspace) if it has the only changes. Doesn't resolve if both the source and target have changed.
Automatic resolve (allow merging): Accepts the source if it has the only changes. Accepts the target file if it has the only changes. Merges changes if both the source and target have changed and there are no conflicts.
Accept Source: Replaces the copy of the file in your workspace with the version that is in the depot, discarding your changes.
Accept Target: Accepts the file that is in your workspace, overwriting the version that is in the depot when you submit the file.
Automatic resolve (allow merging with conflicts): Accepts the source if it has the only changes. Accepts the target file if it has the only changes. Creates a merged file if both the source and target have changed, even if there are conflicts. Where there are conflicts, both versions are included with text notations indicating the conflicts.
5.
(Optional) Select Set as Auto Default to set your selections as the default for auto-resolving multiple files.
6.
Click Auto Resolve.
7.
To resolve multiple files one at a time (recommended when there are conflicts):
1.
Select Interactively resolve files one at a time.
2.
Resolving individual files
To resolve an individual file:
1.
2.
Select Interactively resolve files one at a time.
The Resolve dialog displays the Files to Resolve. If you are resolving multiple files one at a time, select the file you want to resolve. The files are removed from this list as they are resolved.
3.
Select whether to Merge binary files as text when resolving content.
If you select this option, P4VS treats binary files like text files and attempts a textual merge between the source and target files.
4.
View the Recommended action.
P4VS recommends an action, based on the differences and conflicts in the files selected. It also displays:
5.
Select a Resolve method:
Accept Source: Replaces the copy of the file in your workspace with the version that is in the depot, discarding your changes.
Accept Target: Accepts the file that is in your workspace, overwriting the version that is in the depot when you submit the file.
Accept Merged: Replaces the file in your workspace with the merged result of the target file (in your workspace) and source file (in the depot).
Run merge tool: Opens your chosen merge tool, enabling you to edit the file and save the merged result.
6.
Select any Additional Actions that apply:
Open File: Enables you to open either version of the file individually or the merged result file in any editor.
Diff: Opens your diff tool to diff the files with each other or with the base file. It also enables you to diff the source, target, and base file with the merged file.
File History: Displays the revision history of either file.
Time-lapse View: Displays the history of either file using the Time-lapse View tool.
Revision Graph: Displays the history of either file using the Revision Graph tool.
7.
The default diff and merge tool for P4VS is P4Merge. You can set diff and merge preferences, including configuring the diff and merge tool of your choice, on the Perforce - Diff/Merge node under Tools>Options>Source Control.
Deleting files
To delete a file from the depot, you must delete it using Visual Studio, mark it for delete using P4VS, then submit the changelist containing the marked file. When you delete a file, a new revision marked "deleted" is stored in the depot and the file is removed from your workspace. Previous revisions in the depot are not affected.
To delete a file:
1.
P4VS asks if you want to mark the file for delete.
2.
3.
Click Yes.
P4VS marks the file for delete and it is placed in a changelist.
4.
If you want to keep a file in your project but avoid adding it to Perforce control, use Ignore Lists. For more information, see Excluding Files from Perforce Control.
Excluding Files from Perforce Control
Your workspace may include files that you do not want to add to the Perforce repository, such as files used or generated by automated build processes.
You can use Visual Studio to exclude a file from a solution by context-clicking the file in Solution Explorer and selecting Exclude from Project in the context menu. If the file is under Perforce control, P4VS prompts you to mark the file for delete, and after submitting the changelist that includes the deletions, the file is removed from both the project and the Perforce repository.
You can also use Ignore Lists in P4VS to specify files or filetypes that you want to keep in your project but do not want to add to the Perforce repository. An Ignore List is a file in your local workspace directory that contains a list of file names or file types to ignore. For example, you can create an Ignore List called .p4ignore in your project folder that contains the following:
*.swp
*~
tmp/*
.p4ignore.txt
(Note that the Ignore List file itself is included in the list.)
You can add an Ignore List file at any level of the solution hierarchy in your workspace. If you set your P4IGNORE environment variable to the file name of the Ignore List file, P4VS will not mark the listed files and filetypes for add, nor will it prompt you to do so.
Ignore Lists only affect commands that search for and add new files. If you have already marked a file for add, P4VS will no longer ignore it, even if it or its filetype appear in an Ignore List.
You can add Ignore Lists at any folder level in your workspace (or solution). P4VS applies the rules in the Ignore List at the deepest folder level relative to the file being checked, along with the rules in any Ignore Lists found in parent folders (although you can use the ! character to override higher-level rules.)
The syntax for ignore rules is not the same as Perforce syntax. Instead, it is similar to that used by other versioning systems:
# at the beginning of a line denotes a comment
! at the beginning of a line excludes the file specification
* wildcard matches substrings
For example:
Exclude bar.exe from being ignored
While you can set your local P4IGNORE environment variable and add Ignore Lists manually, P4VS provides preferences and context menu options to simplify the process of adding and editing Ignore Lists.
Setting Ignore List preferences
Go to Tools>Options>Source Control>Perforce - Ignoring Files to set Ignore List preferences, including the Ignore List file name. The file name you enter in your preferences is set by P4VS as the local P4IGNORE environment variable and used for all of your Ignore Lists. For more information about setting Ignore List preferences, see Setting Perforce preferences.
Adding a file to an Ignore List
To add a file to an Ignore List in Solution Explorer, context-click the file and select Manage Files>Add to Ignore List. P4VS adds the file to the Ignore List in the current folder. If there is no Ignore List file in the current folder, P4VS creates one.
In Visual Studio 2012, P4VS denotes an ignored file with a gray circle glyph next to the file icon. In Visual Studio 2008 and 2010, P4VS denotes an ignored file by removing the blue question mark glyph: .
Removing a file from an Ignore List
To remove a file from an Ignore List in Solution Explorer, context-click the file and select Manage Files>Remove from Ignore List. P4VS adds an exclusionary (!) line for the file in the Ignore List in the current folder, which overrides any Ignore Lists in parent folders.
Editing Ignore Lists
To edit an Ignore List in Solution Explorer, context-click any file in the same folder and select Manage Files>Edit Ignore List. P4VS opens the Ignore List file for edit. If there is no Ignore List file in the current folder, P4VS creates one. Use Edit Ignore List when you want to add file types using wildcard expressions.
Comparing files using diff
You can compare file revisions using the diff tool associated with P4VS. The default diff tool is P4Merge, which is included with P4V. To associate a different diff tool, go to Tools>Options>Source Control>Perforce - Diff/Merge. For more information, see Setting Perforce preferences.
To diff two files or file revisions:
1.
In the Solution Explorer, Submitted tool window, Submit Changelist dialog, Pending tool window, or Pending Changelists dialog, context-click the file whose revisions you want to diff.
You can also diff two file revisions from the File History tool window by dragging one revision row onto another.
2.
Diff>Diff Against...: compare any two files or revisions of a file.
Diff>Diff Against Have Revision: compare the file version in your workspace against the depot revision that you retrieved most recently. This selection opens P4Merge (or your preferred diff tool, if it is not P4Merge) without first opening the Diff dialog.
Diff Against Previous Revision (from Submitted tool window only): compare the revision you selected against the version in the previous changelist. This selection opens P4Merge (or your preferred diff tool, if it is not P4Merge) without first opening the Diff dialog.
3.
Path: the two files you want to diff. If you choose Workspace version on local disk, you can ensure that all files in the workspace (including files within the client mapping that are not under Perforce control) are displayed by using local syntax. To display only files under Perforce control, use depot syntax
Workspace version on local disk: the file revision in your client workspace, including any changes you made after retrieving it from the depot and editing it.
Latest revision: the revision that was most recently submitted to the depot (the head revision).
Have revision: the revision you most recently retrieved. Does not include any edits you made after retrieving it from the depot.
Specify revision: enables you to designate the desired revision using a revision number, changelist number, date, label, or workspace.
4.
Click Diff. P4VS launches P4Merge (or your preferred diff tool, if it is not P4Merge), displaying the differences between the files at the specified revision.
For more information about diffing files with P4Merge, see the P4Merge help.
Changing Perforce file types
Perforce file types determine how a file is stored in the depot and synced (retrieved) to the workspace, and whether it can be diffed.
To change a file's Perforce file type (or other storage attributes):
1.
Context-click the file and choose Manage Files > Change Filetype...
The Change Filetype dialog is displayed.
2.
If the file was not checked out, P4VS checks it out and makes the change.
3.
For details about file types and attributes, see the Perforce Command Reference.
Renaming and moving Files
When you rename or move a file using the Visual Studio Rename option, P4VS prompts you to add the renamed or moved file to a changelist. When you do, P4VS automatically marks the new file name or location for add and the old file name or location for delete. When you submit the changelist, the Perforce service creates an integration record that links the renamed or moved object to its deleted predecessor, preserving its history.
To rename a file:
1.
The file name in Solution Explorer becomes writable.
2.
3.
4.
\<path>\<old_filename> to:
\<path>\<new_filename>
5.
Click Save to Changelist to save the changes.
6.
If you click Yes, Visual Studio renames all references, and P4VS prompts you to add the changes to a changelist. Follow the steps listed here to complete the process of submitting those changes to the Perforce depot.
7.
The changelist includes Add operations for the new file name and Delete operations for the old file name.
For more information about submitting changelists, see Checking in files and working with changelists.
To move a file from one location to another:
1.
2.
3.
\<path>\<old_filename> to:
\<path>\<new_filename>
4.
Click Save to Changelist to save the change.
5.
The changelist includes Move/Add operations for the new file location and Move/Delete operations for the old file location.
For more information about submitting changelists, see Checking in files and working with changelists.
When you revert a rename or move operation in P4VS, Visual Studio continues to show the new file name or location despite the fact that Perforce has reverted it to the original name or location, unless you select Update related projects when reverting moved files in the P4VS preferences. For more information, see Setting Perforce preferences.
Displaying the revision history of a file or folder
To display a file's revision history:
1.
Open the File History tool window by doing one of the following:
2.
View file revisions in the File History tool window by clicking the triangle to the left of the file name.
3.
4.
5.
6.
This launches P4Merge (or your preferred diff tool, if it is not P4Merge), which displays the differences between the two file revisions. For more information about diffing files with P4Merge, see the P4Merge help.
Shelving files
Shelving enables you to store copies of open files temporarily in the Perforce repository without checking them in. Shelving is useful for a variety of purposes, including taking and restoring snapshots of in-progress work and reviewing other users' code before it's checked in. When you shelve a file, a copy is placed in a pending changelist from which other users can unshelve it. Pending changelists that contain shelved files are indicated by a red triangle marked by a file icon: . When the changelist is expanded, shelved files are indicated by a file icon with a check-mark: .
When managing shelved files, note the following
Basics: To be shelved, a file must be checked out. However, you cannot unshelve a checked-out file.
Submitting shelved files: As of Perforce Server 2013.1, you can submit a shelved file directly. For previous versions of Perforce Server, you must first unshelve a file to submit it, then delete the shelved copy. (Unshelving does not delete the shelved copy.)
Managing changelists: You cannot move a shelved copy to another pending changelist. If you revert a file after shelving it, the copy remains shelved in the changelist until you delete it. Only the changelist owner can reshelve or delete files that are shelved in the changelist. For Perforce Server releases that predate version 2013.1, you cannot submit a changelist that contains shelved files; you must delete the shelved copies before submitting. Starting with Perforce Server 2013.1, you can submit shelved files directly, but your changelist must contain only shelved files.
File history: No file history is created when you shelve or unshelve files.
Diffing: You can diff shelved copies by right-clicking the shelved file in the Pending dialog (View>Pending Changelists) and selecting Diff Against Source Revision or Diff Against Workspace File.
Shelving checked-out files
To shelve checked-out files in a pending changelist:
1.
Open the Shelve dialog by doing one of the following:
Go to View>Pending Changelists. On the Pending dialog, context-click the changelist and select Shelve....
In the Solution Explorer, context-click a file that is in a pending changelist and select Shelve....
2.
In the the Shelve dialog, select the files you want to shelve.
3.
Revert checked-out files after they are shelved. The files in your workspace will revert to the head revision in the depot.
4.
Click Shelve.
5.
P4VS shelves the file in the selected changelist or, if you are shelving files in the default changelist, creates a new changelist.
Unshelving files
After shelving a file, you (or another user) can unshelve it, which restores the shelved copy to your workspace and opens it in the changelist of your choice. Unshelving does not remove files from the shelf. To unshelve a file that was shelved by another user, you must have permission to check out the file. When you unshelve a file that was shelved by another user, it is copied to one of your changelists, from which you can edit and submit the file.
To unshelve files in a pending changelist:
1.
Context-click the file in the changelist and select Unshelve.... P4V displays the Unshelve dialog.
2.
Check the files you want to unshelve and click Unshelve and any other desired options. The shelved file is copied to your workspace and opened in the specified changelist.
Shelved files remain shelved until you delete them from the pending changelist. To delete a shelved file from a pending changelist, context-click the file and select Delete. You can also context-click the pending changelist and select Delete Shelved Files....
Submitting shelved files
As of Perforce Server 2013.1, you can submit shelved files directly.
If there are non-shelved files along with shelved files in a pending changelist, you must first revert the non-shelved files or move them to another changelist. You cannot submit shelved files from a task stream..
To submit shelved files in a pending changelist, context-click the changelist and choose Submit Shelved Files...


Previous Table of Contents Next

Perforce 2013.3: P4VS User's Guide
Copyright 2012-2013 Perforce Software.