Learning Perforce SCM — Save 50%
A comprehensive guide to the world's leading enterprise configuration management system with this book and ebook
In this article by Robert Cowham and Neal Ralph Firth, authors of the book Learning Perforce CRM, we will explain regarding the file information. File information is the key to understanding the history of a repository, how a code base or set of files has evolved, and what is happening to it now.
File information is exposed in many parts of the P4V interface. In this article, we will cover how to make the most efficient use of the Perforce reporting commands to examine the information associated with a file. More importantly, we'll explain how to interpret this information to maximize the value it provides you.
In this article we will cover:
- Properties of files
- File versions and their relationship to changelists
- Finding files in the repository
- The many ways of referencing file versions
- Comparing different versions of files and folders
- Examining how file content has evolved over time
- Perforce file types and how they impact usage and workspaces
(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.
|A comprehensive guide to the world's leading enterprise configuration management system with this book and ebook|
eBook Price: $26.99
Book Price: $44.99
Showing differences between file revisions
The easiest way to compare two revisions of a file is to drag-and-drop one revision onto another from the History tab for a file, as shown here:
In the preceding example, I have clicked on revision 75 of the file RELNOTES and am about to drop it on to revision 77.
If I complete the drop, then P4V runs the diff tool P4Merge on those 2 revisions.
The P4V diff tool – P4Merge
This is the built-in diff tool which is installed with P4V. Following on from the previous section we can see an example diff:
The title bar shows which revisions are being compared (#75 and #77 in this case).
In this example, we can see lines and blocks of text which have been changed, including particular parts of those lines which are highlighted in grey.
The summary is shown in the status bar at the top:7 diffs.
Navigating between diffs
You can scroll through the two files, or click on the arrow icons in the toolbar to go to the next or previous diff, as shown:
You can also find the Next Diff and Previous Diff options in the Search menu
More P4Merge options
Navigate to the Edit | Preferences menu option and consult the help information for more details.
We recommend you explore the tool further on your own. In our experience it is powerful and capable. However, personal preference may lead you to want to use a different tool, this can be easily configured by going to P4V's Edit | Preferences | Diff menu option.
Showing folder/directory differences
In a similar way as for files, drag-and-drop of one changelist on top of another in the History tab will show us a folder diff, as shown:
In the preceding example, I clicked on changelist 830 and am about to drop it onto changelist 709. Completing the drop action causes P4V to run the Folder Diff tool, which performs a recursive diff on all files in the folder and any sub-folders.
The folder diff tool – recursive folder differences
This is a very powerful tool which works well and performs quickly even for folders with tens of thousands of files in them.
Following on from the previous section we can see an example diff:
The two Path: options show which folders are being compared. In this case, the same folder is being compared against itself, but at two different points in time. As this statement implies, it is also possible to compare two different folders (we will cover this later in the article).
The summary information at the top-right gives us an overall idea of how many files are different. In this example, only one file has different contents.
However, there are two unique files which means they have either been added or deleted. On the right-hand side c.txt#1 (highlighted) has been added between changelist 709 and 830. The file execmac.c#1 on the left-hand side has been deleted between the changelists.
Filtering the folder diff view
We can filter the view to only show the files that are actually different. This can be very useful when there are lots of files which are the same and we want to focus only on the differences.
As shown in the screenshot, the toolbar icon in the top left condenses the view and removes identical file pairs.
Explore the other toolbar icons yourself or consult the help.
Showing individual file diffs
If a row is highlighted (in blue) then it means the file contents are different. In this case, there will be a Diff Row option on the right-click menu:
Clicking that option will run P4Merge on the two file versions.
Double-clicking the row is a shortcut action to perform the same diff.
Other options for comparing files or folders
We have seen the basic use of drag-and-drop for comparing files or folders, primarily from the History tab. It is worth noting that you can change drag-and-drop behavior by going to Edit | Preferences | Behavior | Enable diff comparisons on file-to-file drag and drop.
There are a number of other useful options for comparisons which we will discuss in this section.
Showing local changes for edited files
This option makes more sense now that we know that the have revisions (or #have) is the revision currently synced to our workspace. So we are comparing any local changes we have made with the revision we last synced to. Note that this is not necessarily the same as the latest (or #head revision), since someone might have checked in a new revision since we checked our revision out.
Ctrl + D as a useful shortcut for diffing
The Ctrl + D shortcut is useful in other situations than just for diffing edited files. As we can see in the following screenshot, on the right-click menu for the History tab, Ctrl + D is a shortcut for Diff Against Previous Revision:
The same shortcut key also works if you click on a revision in Revision Graph.
Diff against for files
On several right-click menus, including the screenshot in the previous section, you can see Diff Against… as an option. This will show you the following dialog:
As you can see in this screenshot, there are many powerful options for comparing the same file against itself. All of the various ways of designating a revision can be compared against other revisions. For example, you can compare the #head (latest) revision of a file against the revision valid at a particular date and time. You could also compare the file at one date against the version valid at another date, for example, the beginning and end of a month.
Behind the scenes, P4V translates each revision specifier such as date/time or label or workspace, into a valid revision and compares one revision against another. Obviously, if you end up comparing the same revision against itself, there will be no differences to see and you will see a warning message instead.
Using Diff against for different files
In the following example I used Ctrl + click to select two different files, and can then select Diff Against… on the right-click menu:
In this instance, the two files will be put in the 1st Path: and 2nd Path: fields for the dialog in the previous screenshot. All of the other options remain the same.
Diff against for folders
The same Diff Against… action is on the right-click menu for folders. In a similar way as for files, this allows you to compare the same folder against itself at a different point in time. Thus you could see what happened in the month of March.
Equally, we can Ctrl + click on two folders and compare them from the right-click menu (or the standard shortcut key).
P4V time-lapse view
The Time-lapse View tool is available on the right-click menu for files.
It is a bit like a diff on steroids! It allows you to see how a file has evolved since it was first added to the repository.
We encourage you to play with this tool and work out how it will best help you to understand how a file has changed over time.
Every line in the file is shown (line numbers are displayed here, they can be toggled off) and the boxes on the left-hand side show which revision was the last one to affect that line or block of lines. In this example, there are 26 revisions, but the first line was last modified as part of revision 22 (the figure on the left-hand side of the line). The block consisting of lines 2 and 3 was last changed in revision 6.
In the preceding screenshot, Mode: Single revision and Scale: Revisions show us everything in terms of revisions. We can change these options, for example:
We have now changed the scale to Dates, and can see in the toolbar how the file has evolved over time (rather than over revisions as per the previous screenshot). Alternatively, we can set the scale to Changelists and colour the text (in green):
The tool now has the toolbar icon toggled to Show aging of text. The more recent blocks of text are colored in a darker shade of green than the older ones, it can almost start to look psychedelic! How much you like this view depends on your own personal tastes.
Play around with some of the other modes and toolbar icons and find out which options you prefer.
Some people swear by the Time-lapse View, and others seldom go near it, see how well it works for you. In our experience it can be incredibly useful at times, even if we tend to use ordinary diffs between two revisions most of the time.
In this article we provided in-depth coverage of some key concepts. Once you grasp these concepts, you can really start to appreciate the power of the reporting options available to you. The ability of Perforce to show comparisons between a folder tree that contains a thousand or more files can be hugely valuable. Precision file diffs and the time-lapse view make the analysis of changes a straightforward task that would be hard to accomplish using other methods.
Resources for Article :
- Working with local files (Simple) [Article]
- Setting Up Oracle Order Management [Article]
- Installing and customizing Redmine [Article]
|A comprehensive guide to the world's leading enterprise configuration management system with this book and ebook|
eBook Price: $26.99
Book Price: $44.99
About the Author :
Neal Ralph Firth assumed both individual contributor and management roles during the design, test, and development of both hardware and software used in stand-alone, embedded system, and real-time environments in his early career. Since the late 90's he has focused on source control and the automation of test and build systems. He first encountered Perforce in its early days while investigating source control solutions for one of his first consulting customers. He subsequently became a Perforce Consulting Partner and a Perforce Certified Trainer as soon as those certifications were available to him. He has consulted for hundreds of companies and organizations, and trained thousands of Perforce users and administrators across the US and Canada.
His career has had a focus on automation and the tools that make people more productive. His early work with hardware microcode simulation was chronicled as part of Tracy Kidder's Pulitzer prize winning book "The Soul of a New Machine". He has presented papers and has spoken at conferences in the US, the United Kingdom, and Germany. He has published articles on hardware, software, and business topics. Hardware topics include peer reviewed IEEE articles on microcode. Software articles have dealt with the application of automated processes with a focus on legacy tool integrations and tool migrations.
As the principal provider of Perforce related services for VIZIM Worldwide, Neal's focus is on the migration of information between SCM products and integrations with legacy systems. He developed the framework for VIZIM's full history migration tool sets and authored the ClearCase and VSS-specific versions of those tools. He has created many Perforce-specific integrations for features such as the Perforce Defect Tracking gateway and IDEs such as JDeveloper.
Robert Cowham is from a software development background with experience in roles from programming to testing and project management. He came across Perforce as a user in the early days of the company when there were only four employees. He subsequently became one of the two pre-qualified Perforce Consulting Partners, and became a Perforce Certified Trainer as soon as that program was implemented. Since then he has consulted for many companies and organizations, and trained thousands of users around the globe, from California to Japan, including giving training courses in German, French, and Italian.
He has also written a number of integrations with Perforce. This includes P4OFC, which integrates with Microsoft Office, and is still provided as an officially-supported public download. APIs developed by him include P4COM, a COM based API for use on Windows, and P4Python which he subsequently handed over to Perforce to support. He has also written various full history migration tools for customers to get them into Perforce.
He has long had an interest in all aspects of configuration management and was for several years a coauthor with Brad Appleton and Steve Berczuk of the Agile SCM column in the online CM Journal. He was Chair of the specialist group for Change, Configuration and Release Management of the British Computer Society for seven years, organizing many events and conferences, and is still active on the committee. He regularly speaks at industry events.
As Services Director for Square Mile Systems, Robert now also works with configuration management of infrastructure and data centers, applying the
same principles to the physical world.
Robert has practiced the Japanese martial art of Aikido for over 20 years, and runs a dojo near his home in London. He has even managed to combine his interests with a well-received presentation on "Black belt SCM techniques," including physical demonstrations of the principles involved!