(For more resources related to this topic, see here.)
Every file has properties. Some of these properties relate to how files are represented in your workspace. Some relate to the history of the file. Still others will impact how Perforce can manage that file.
While various file properties are exposed in different parts of the P4V interface, the Files tab in the view pane provides you with the maximum amount of detail with the minimum effort.
The following screenshot shows a file selected in the tree panel along with the information that would be presented in the Files tab:
The Files tab presentation has two primary sections. The upper section presents information for the files in a folder using a tabular format. This provides a useful, easy to use, and comparative presentation. The lower section provides information specific to a single file selected in the upper tabular section. This provides you with the ability to focus on additional details once you’ve identified files of interest using the tabular upper section.
The tabular section presents a selected set of the information available for a file. As you’ll see shortly, the information selected is under your control.
The Details tab provides all of the available information, and shows in addition the explicit mapping between the Workspace and Depot locations of the file. These locations can be seen in various parts of the P4V interface.
The Checked Out By tab provides details about all of the workspaces that have a file checked out. These are the full details. You will see summaries of this information in the tree panel hover tips.
The Preview tab shows the contents of text files. This is particularly useful when browsing repository files that are not currently present in your workspace.
Customizing the tabular display
While the tabular section of the Files tab is useful, without order it is still just a collection of data. P4V allows you to sort on any of the displayed columns. It also allows you to select which columns are displayed to help you focus on important factors.
You can reorder the columns by clicking on a column header, dragging it, and dropping it in the position you desire. You can also select the column displayed in the table by right-clicking on the header bar and then checking the columns you want displayed, as shown in the following screenshot:
Note the triangle indicator in the Name column header. This specifies that the table entries are sorted based on the value in the Name column. A triangle pointing upwards sorts in ascending order, a triangle pointing downwards sorts in descending order.
Sorting on either the Latest Changelist or Date Last Submitted columns allows you to quickly identify more recently or least recently changed files.
Explaining the # characters
The # character is the Perforce notation indicating the file revision. So foo.txt#3 indicates revision (or version) 3 of the file foo.txt. Using this notation saves a lot of screen space and reduces visual clutter. It’s also the versioning notation you’ll see in the log panel or which you would use on the command line.
But what about things like #5/5, #3/5, #0/5 or even #25 of 25? Not to worry, long division and set theory are not involved. This is simply a notation that indicates the version of the file in your workspace and the maximum number of file versions the server knows about. So #5/5 would indicate that you have version 5 of the file in your workspace and that is the most up-to-date version the server knows about. Likewise, #3/5 would indicate that you have version 3 of the file in your workspace, yet the server knows about two more recent versions: 4 and 5. While #0/5 indicates that you have no version of the file in your workspace. Finally, the #25 of 25 notation has replaced the “/” with “of” to increase readability.
0 is the workspace version of deleted files and files marked for add, but not yet submitted.
Showing deleted files
The deleted files are visible in the depot tree only if you turn on the filter to show them, as we see in the following screenshot:
The filter Show Deleted Depot Files has been checked. As a result, we can see a file execmac.cwhere the latest revision is 2, and the tooltip (as well as the icon) shows us that it is deleted at head revision. As we will discuss later in this article, the head revision is the latest revision in the repository.
This filter is not available if you have selected the Workspace tab since deleted files do not exist locally.
Type and filetype
P4V understands two separate type concepts relating to files. Knowing the difference and how they apply will come in handy.
One concept is known as type and refers to an association based on the file name extension. This is managed by the operating system on the local workstation. For example, Windows might associate the .docx extension with the Microsoft Word application. The server maintains no information about type. By default, this relationship is used by P4V to select the tool to use when it opens a file for you. For example, if you ask P4V to open a file called foo.html and you have a web development tool installed, it may launch that tool. If you don’t have such a tool, then it might launch a browser. Not to worry, you can override this behavior.
The other concept is known as filetype, and refers to the information Perforce uses to define workspace population characteristic, control P4V processing, and define server storage parameters. The server maintains filetype information on a per-revision basis. When a file is first added it is assigned a filetype. That filetype persists until it is explicitly changed. Most of the time, you will not need to worry about specifying a particular filetype. P4V uses several techniques to assure that the appropriate filetype is established when a file is first added (including defaults configured by your administrator). Of course you can always explicitly specify a filetype, but that is for advanced users.
The two basic filetypes are text and binary. Perforce knows that text files have line endings. When it populates your workspace with a text file it automatically adapts the line endings within the file to the encoding appropriate for your operating system. It is also understood that text files can be compared in ways that humans can understand. On the other hand, binary files are treated as a collection of bytes. They receive no special processing when populating your workspace, and it is understood that they can’t usually be compared in ways that humans would understand.
Filetype can also specify other attributes of files, such as making files always writable in workspaces. They can also set the executable bit on Linux/Unix for shell scripts or executable binaries.
Understanding file versions and history
In this article, we are going to first look at how to get older revisions of files into our workspace and how to understand the history of a file or a set of files. That includes understanding how file revisions relate to changelists, and the state of the repository as of a particular date and time.
We often need to have a look at older versions of files. When looking at a project, you may need to reproduce an older release, or understand a particular baseline which is a set of files or a complete folder or tree.
Getting different revisions of files
On the right-click menu for a file or folder there is a Get Revision…option, as shown in the following screenshot:
Clicking on the preceding option brings up the following dialog:
Various actions are possible with this dialog. For now, we will focus on choosing between Get latest revision and Specify revision using:.
Get latest revision updates the workspace files with the highest revision of the files known to the server. This is also known as getting or syncing to the head revision. The head version is a special version with its own reference #head. You will see #head in the log pane and in various error and status reports.
Specify revision using: updates the workspace files with either explicit revisions or revisions that are implied from a context such as date/time, label, or changelist.
Don’t worry that you don’t know what all of the Specify revision using: choices are or what they do. Take a moment to scan through the choices. Note the Browse… results. They are designed to reduce typing errors to get you the specific revision you’re interested in.
How file revisions relate to changelists
The following screenshot shows the history of fileos2.c using the Revision Graph tool, which is available on the right-click menu for the currently selected file within the tree pane (right-click, then select Revision Graph). Note that for clarity we have turned off various panes within the tool to show the minimum necessary, and included the Legend option to explain the shapes:
This shows us the association between revisions of a file and the changelists in which those revisions were submitted to the repository. In this example, revision 3 was part of changelist 294, and revision 2 was part of changelist 279. The file was first created and thus added to the repository as revision 1 in changelist 220.
It is fairly clear that a Get latest would give us revision 3 of the file in our workspace. Similarly, if we Specify revision using: changelist 279 we would get revision 2 of the file.
So what would you expect if we chose changelist 280? Doing a get which specifies a changelist gives us the state of the repository at the point of that changelist. In this case, it will give us revision 2. Revision 2 is the latest revision up to or including the specified changelist. In fact for this file, getting any changelist between 279 and 293 inclusive, will give us revision 2.
What would we expect if you do a get which specifies changelist 100? The preceding history shows us that this file did not exist in the repository as of that changelist. Therefore, a get of that changelist would remove the file from our workspace because it didn’t exist as of that changelist. Using Perforce terminology, we would have revision 0, or the revision which does not exist, in our workspace.
Removing version 0 files from a workspace is designed to avoid the inevitable user errors that would occur if you had to delete the file yourself.
Potentially surprising get revision results!
Following on from the preceding examples, what would you expect if you tried to get changelist 9999999 or some equally large number, for which a changelist doesn’t yet exist? Hopefully, it is not a big surprise that we just get the latest revision of the file. In the preceding case, revision 3. As we saw previously, even though the changelist doesn’t directly contain this file, the file still associates revisions with every changelist, even those that don’t yet exist.
This large changelist technique is actually just an obscure version of get latest. Obscure is not usually a good engineering practice.
But watch out! What will happen if we try to get revision 5 of this file? For this file, revision 5 does not exist. Therefore the get request treats this as if you requested revision 0 so it will remove the file from the workspace.
Be very careful getting more than one file as of a specific version number. When more than one file is involved, this gets that version of every file that has that many versions or more and removes (#0) the rest. This is usually not what you want.
Changelists and folders
People don’t always realize that the Revision Graph… right-click option can also apply to folders. The folder view shows all of the files at one time, as seen in the following screenshot:
In the preceding screenshot, the cursor is hovering over changelist 370, and the 3 files in the folder that had new versions created by that changelist are highlighted.
What would we get if we synced the entire folder to changelist 370? By default, we would get the files in that particular changelist and the version for every other file in the folder as of that changelist. In the preceding screenshot that would be version 3 of Jamfile.html, which was submitted in changelist 369. But, index.html at version 0 would be removed from the workspace because it didn’t exist until changelist 383.
Therefore, we can see that a changelist can be used in two ways:
- To refer to the set of files submitted in that changelist
- To refer to the state of the entire repository (or any part of it such as a folder), up to and including that changelist
When waxing philosophical, we sometimes refer to this as the particle nature versus the wave nature of changelists!
Get revision options
We haven’t yet covered the options in the Get Revision… dialog shown in the following screenshot. They provide functionality that can be difficult to achieve using other techniques.
The preceding screenshot shows the output on clicking Preview. We see what the results would be, without actually affecting anything in our workspace. This can help avoid surprises and perhaps prevent unnecessary mistakes.
The Force Operation (replace file even if you already have the revision specified)checkbox, if checked, will update the files in our workspace to the specified revisions, even if P4V thinks we already have those revisions. You need to force operations when files have been removed from the workspace without coordinating that removal with Perforce.
Following on from the discussion in the previous section about a Get Revision, always getting files up to or including the changelist, we can modify this behavior by checking Only get revisions for files listed in changelist. With this option you update your workspace with only the file versions created by that changelist. If the following changelist is discovered to cause a problem, then it can be very useful to get a workspace into the state immediately before that changelist.
Referencing a specific date and/or time
The Get Revision dialog allows us to specify a date and time, as shown in the following screenshot:
Every submitted changelist has an associated date and time of submission. The value specified in this dialog will give the same results as if you were to do a get specifying the changelist that was submitted precisely at or most closely before the specified date and time.
Most people prefer to reference using changelist numbers rather than date and time. Changelists are unique and unambiguous. More than one changelist may be submitted within the one second granularity of date and time tracking. And communicating date and time across time zones is error prone at best.
Referencing a label
As stated in the preceding section, we can also do a get relative to a particular label:
You can type the name of the label in directly. However, most people prefer to select an appropriate label from the choices presented when you click on the Browse…button.
Most Perforce users don’t use labels. They use changelists.
Files in another workspace
You can also reference file versions in another workspace:
As previously stated, we can type the workspace name in the field or browse to select a workspace.
This feature is most useful when you’re trying to resolve scenarios where it works/ fails in my workspace. Most people use it with Preview so that they don’t impact their current workspace. However, it does require that both workspaces reference the same depot files. This is only likely to be true for continuous build and code review environments.
The path of currently selected files or folders is shown in the address bar at the top of the screen, as per the following screenshot:
You can turn off the address bar by right-clicking on it and unchecking the option.
There is also a shortcut key (Ctrl + C) which copies the full path of the currently selected file or folder to the clipboard. This can be useful for documentation purposes. Depending on whether you have the depot or workspace tab showing, you might get:
Or, depending on your workspace definition:
Finding files – an introduction to wildcards
It is easy to find files with certain characters in their names by going to the Search | Find File… menu option. This will give you the Find File tab, as shown in the following screenshot:
In the preceding screenshot, we had a particular folder selected, and that is copied to the Search in: field. Sharp eyed readers will have noticed that the full path contains some extra characters: //depot/Jam/MAIN/…. In this instance, P4V has added the … wildcard to the directory path (this wildcard is also known as an ellipsis).
This wildcard means that all subfolders should be included in the search. We will look at more wildcard options in the next section of this article.
You can also drag-and-drop directory paths from the tree pane on the left-hand side to the Search in field and the contents will be appropriately updated.
If we enter, for example, unix into the Names matches any of the following field and click on Find, we might get results as shown in the following screenshot:
In this particular example, we can see that there are three files in that folder (or in any subfolders) containing unix in their filename.
By default, the results do not include any files where the latest revision is marked as deleted. You can change this by checking Include deleted depot files.
Note that it is possible to filter the results further using the Submission date or changelist option:, for example:
When working with dates you can search for particular periods of time, as seen here:
We invite you to explore this powerful feature on your own!
The history of both files and folders can be seen via the History tab. You can go to the View | History menu option or click on the appropriate toolbar icon.
This tab can show the history for the currently selected file or folder in the tree pane. You can right-click on a file in the tree pane and select File History. If you have a folder selected the menu option is Folder History.
The history for a file might be:
In this example, we can see the basic history information for the selected file. For each revision we see information such as Changelist and Date Submitted. As previously seen with the File Properties tab, by right-clicking the column headers you can select other columns to be displayed.
When this tab is displayed, clicking to select another file in the tree pane will cause the tab to be updated dynamically.
The icon for revision 8 in the preceding screenshot has a highlight around it, this shows that this revision is the one currently present in the workspace.
The History tab also has a details tab which can be shown if you wish, by dragging the splitter bar upwards with the mouse, as shown here:
For a folder, the History tab shows all changelists that have affected files in that folder or any of its subfolders. This acts in the same way for a depot. An example is shown here:
Notice that there is no column for revisions as they only apply to files, not to folders.
If you drag-and-drop a column header onto another one (left or right), you can change the order they are displayed in.