Comparing Version-Controlled Items (Team Explorer Everywhere)

  • Article

You can compare two versions of a file or a folder on a local computer or a version-control server to identify the differences between those versions. You might perform this task, for example, to identify the differences between two branches or between releases of your application. You can use one of several approaches to compare files and folders.

Task

Compare files or folders: You can compare a version of a text or XML file or a folder on the local computer with a version on the version-control server. You can also compare two versions that are on the local computer or two versions that are on the version-control server. You can perform these comparisons from the user interface by default or at a command prompt if you configure an external comparison tool.

Configure comparison tools: If you configure an external tool, you can compare files that are not text or XML, and you can display the results either in the user interface or at a command prompt. You can also configure an external tool if you prefer it to the default tool that the Team Foundation Server plug-in for Eclipse provides.

Important noteImportant
You must configure an external tool before you can compare files or folders at a command prompt.

View changed lines in a single file: By viewing annotations, you can display not only the lines that were changed in a file but also the name of the user who changed each line and the date and time when the line was changed. This view provides no side-by-side comparison.

Required Permissions

To compare an item on the version-control server with an item on the server or on a local computer, your Read permission must be set to Allow. For more information, see the following page on the Microsoft website: Team Foundation Server Permissions.

To compare two files on a local computer, you do not need permissions in Visual Studio Team Foundation Server.

Compare a version on the local computer to the version that you originally checked out from the version-control server

You might want to identify the changes that you have made to one or more files in a local folder since you checked them out of version control.

To compare files or folders by using Project Explorer or Package Explorer

  • In Package Explorer or Project Explorer, right-click the file or folder that you want to compare, point to Team, point to Compare With, and then click Unmodified Workspace Version.

To compare a file with its workspace version at a command prompt

  1. Open a Command Prompt window.

  2. Type tf diff FileName, and then press ENTER.

    Replace FileName with the path of the file that you want to compare. For more information, see Difference Command (Team Foundation Version Control).

    Important

    Before you start this procedure, you must follow the instructions in Configure an External Tool to Compare Items at a Command Prompt.

    The file is compared with the version that was checked out to your local workspace.

To compare a folder and its contents with the unmodified workspace versions at a command prompt

  1. Open a Command Prompt window.

  2. Type tf diff FolderName /recursive, and then press ENTER.

    Replace FolderName with the path of the folder whose contents you want to compare. For more information, see Difference Command (Team Foundation Version Control).

    Important

    Before you start this procedure, you must follow the instructions in Configure an External Tool to Compare Items at a Command Prompt.

    The files in the folder that you specified are compared with the versions that were checked out to your local workspace.

Compare a version on the local computer to a specific version on the version-control server

You can compare a version of an item on a local computer with any of the following versions of that item on the version-control server:

  • The version that is the most recent

  • The version that has a specific version number

  • The version that existed on a specific date

  • The version that has a particular label

  • The version as it existed in a specific changeset

  • The version that you checked out to your local workspace

    Note

    For more information, see Compare a version on the local computer to the version that you originally checked out.

To compare files in Package Explorer or Project Explorer

  1. In Package Explorer or Project Explorer, right-click one of the files that you want to compare, point to Team, point to Compare With, and then click Another Version.

    The Choose Items to Compare dialog box appears.

  2. (Optional) In Selected item (source), specify a different source file.

  3. In Compare to (target), click Browse to specify the file.

    You can also type the path and name of the file to which you want to compare the source file.

  4. To specify a version of the target file other than the most recent, perform one of the following tasks:

    • Click Changeset, and then either specify the number of the changeset or click the ellipses (…) to open the Find Changesets dialog box. For more information, see Search for a Changeset.

    • Click Date, and then specify a date by either typing one or by opening the menu and clicking a date on the calendar.

    • Click Label, and then specify a label by either typing one or by clicking the ellipses (…) to open the Find Label dialog box. For more information, see List, Find, View, Edit, and Remove Labels.

    • Click Workspace Version, and then specify the workspace whose version you want to compare.

  5. Click OK to compare the specified files.

To compare folders from Source Control Explorer

  1. In Source Control Explorer, right-click one of the folders that you want to compare, and then click Compare.

    The Choose Items to Compare dialog box appears. By default, the specified folder on the server is compared with the corresponding folder on your local computer.

  2. To specify a version of the server folder other than the most recent, perform one of the following tasks:

    • Click Changeset, and then either specify the number of the changeset or click the ellipses (…) to open the Find Changesets dialog box. For more information, see Search for a Changeset.

    • Click Date, and then specify a date by either typing one or by opening the menu and clicking a date on the calendar.

    • Click Label, and then specify a label by either typing one or by clicking the ellipses (…) to open the Find Label dialog box. For more information, see List, Find, View, Edit, and Remove Labels.

    • Click Workspace Version, and then specify the workspace whose version you want to compare.

  3. Click OK to start the comparison.

    A progress dialog box appears while the files are compared. The Text Compare window appears when the comparison is finished.

  4. (Optional) In the Text Compare window, use the toolbar buttons to browse the differences between the files.

To compare folders at a command prompt

  1. Open a Command Prompt window.

  2. Type tf diff FirstFolder SecondFolder /recursive, and then press ENTER.

    Replace FirstFolder and SecondFolder with the paths of the folders that you want to compare. For more information, see Difference Command (Team Foundation Version Control).

    Important

    Before you start this procedure, you must follow the instructions in Configure an External Tool to Compare Items at a Command Prompt.

    The files in the specified folders are compared.

Compare two versions on the local computer

In Team Foundation Server plug-in for Eclipse, you can compare two local files or folders only by using Project Explorer or Package Explorer. You cannot perform that type of comparison from Source Control Explorer or at a command prompt.

To compare files or folders by using Project Explorer or Package Explorer

  1. In Package Explorer or Project Explorer, highlight the two files or folders that you want to compare.

  2. Right-click either file or folder, point to Team, point to Compare With, and then click Each other.

Compare two versions on the version-control server

You might want to compare two versions of a file or a folder on the version-control server if for example, you want to identify changes that were made as part of a check-in. In addition, you might want to identify changes that were made between releases of your application.

You can compare server versions from Source Control Explorer or at a command prompt.

To compare two server versions from Source Control Explorer

  1. In Source Control Explorer, right-click one of the files or folders that you want to compare, and then click Compare.

    The Choose Items to Compare dialog box appears. By default, the source is set to an item on your local computer, and the target is set to the equivalent item on your version-control server.

  2. In Selected item (source), click the Browse arrow, click Server Path, and then click Browse.

    You can also specify the source item by typing the path of the source file or folder on the server (for example, $/DefaultAgile/billing-service).

  3. (Optional) To specify a version of the item other than the most recent, perform one of the following tasks:

    1. Click Changeset, and then either specify the number of the changeset or click the ellipses (…) to open the Find Changesets dialog box. For more information, see Search for a Changeset.

    2. Click Date, and then specify a date by either typing one or by opening the menu and clicking a date on the calendar.

    3. Click Label, and then specify a label by either typing one or by clicking the ellipses (…) to open the Find Label dialog box. For more information, see List, Find, View, Edit, and Remove Labels.

    4. Click Workspace Version, and then specify the workspace whose version you want to compare.

  4. In Compare to (target), repeat steps 2-3 to specify the other item that you want to compare, and then click OK to start the comparison.

    A progress dialog box appears while the files are compared. The Text Compare window appears when the comparison is finished.

  5. (Optional) In the Text Compare window, use the toolbar buttons to browse the differences between the files or folders.

To compare files at a command prompt

  1. Open a Command Prompt window.

  2. Type tf diff FirstItem SecondItem, and then press ENTER.

    Replace FirstItem and SecondItem with the paths of the files that you want to compare. In addition, you can specify the version of the files that you want to compare. For example, to compare the version of the file App.java that was in changeset 3200 with the version that has the label “release”, you would use the following syntax: tf diff App.java;C3200 App.java;Lrelease.

    For more information, see Difference Command (Team Foundation Version Control).

    Important

    Before you start this procedure, you must follow the instructions in Configure an External Tool to Compare Items at a Command Prompt.

    The files in the specified folders are compared.

To compare folders at a command prompt

  1. Open a Command Prompt window.

  2. Type tf diff FirstItem SecondItem /recursive, and then press ENTER.

    Replace FirstItem and SecondItem with the paths of the folders that you want to compare. In addition, you can specify the version of the folders that you want to compare. For example, to compare the version of the folder billing-service that was in changeset 3200 with the version that has the label “release”, you would use the following syntax: tf diff billing-service;C3200 billing-service;Lrelease.

    For more information, see Difference Command (Team Foundation Version Control).

    Important

    Before you start this procedure, you must follow the instructions in Configure an External Tool to Compare Items at a Command Prompt.

    The files in the specified folders are compared.

Configure an External Tool to Compare Additional Types of Files

To compare files that are not text or XML, you must configure an external tool to work with the Team Foundation Server plug-in for Eclipse. You might also configure an external tool if you prefer it to the built-in one. You can use any comparison tool that supports, as command-line arguments, the full paths of the two files that you want to compare. When you configure a comparison tool, you specify one or more types of files to compare, the path to the tool, and the syntax of the tool. You specify the syntax of the tool by using arguments such as the tokens in the table that appears later in this topic.

When you start a comparison, you provide specific values, such as file paths, for those tokens. The Team Foundation Server plug-in for Eclipse then invokes the external tool and passes to it the appropriate arguments for the tool's syntax, replacing the tokens with the values that you provided. The external tool then performs the actual comparison, and the results appear in the plug-in.

When you specify the syntax for the tool, you use white space to delimit the arguments, such as tokens. If an argument includes one or more spaces, you must enclose the argument in quotation marks (“”). If an argument contains one or more quotation marks, you must add another quotation mark immediately after any quotation mark within the argument. For example, you could specify the following argument:

"This "" embeds a double quote"

You do not have to enclose a % token in quotation marks, even if its value might contain spaces.

Tokens

The following table describes the tokens that you use when you specify the syntax of an external tool:

Tokens

Required or Optional

Description

%1

Required

The path of the source file

%2

Required

The path of the target file

%5

Unused, but retained for compatibility with the Visual Studio client for Visual Studio Team Foundation Server.

Diff command-line options (not used)

%6

Optional

Label for the source file

%7

Optional

Label for the target file

To configure a comparison tool for additional types of files

  1. On the Window menu, click Preferences.

    The Preferences dialog box appears.

  2. Expand the Team node, expand the Team Foundation Server node, and then click Compare Tools.

    In the results pane, a list of the configured external comparison tools appear. By default, no tools are configured.

  3. To associate one or more types of files with a comparison tool, follow these steps:

    1. Click Add.

      The Add External Compare Tool dialog box appears.

    2. In File Types, specify the file name extensions for which you want to use this comparison tool.

      You can specify multiple extensions, separated by commas, or use the wildcard character (*) to specify all types of files.

  4. To associate all folders with a comparison tool, follow this step:

    • In Directory Command, click Add.

      The Add External Compare Tool dialog box appears.

  5. In Command, specify the syntax of the comparison tool that you want to use.

    This syntax includes the path of the comparison tool and the arguments that it accepts. You can click Browse to specify the path of the comparison tool.

  6. Click OK to finish the configuration.

  7. Click OK to close the Preferences dialog box.

Example

For example, you might specify the following syntax to specify the OtherDiff tool for Java files:

C:\Program Files\OtherDiff\otherdiff.exe %1 %2

You might also be able to specify labels for each file. If you do not specify these labels, the tool will show names of temporary files, which might be difficult to read.

To provide labels, you might specify the following syntax:

C:\Program Files\MyDiff\mydiff.exe %1 –title1=%6 %2 /title2=%7

If you specify this syntax, %7 specifies the label for file %2, and %6 specifies the label for file %1.

Configure an External Tool to Compare Items at a Command Prompt

If you want to compare files or folders at a command prompt, you must first configure an external tool that will compare the items. By default, the Cross-platform Command-Line Client for Team Foundation Server has no comparison tool. When you configure a tool, you specify its syntax by using tokens in the table that appears earlier in this topic. For the most recent information about how to specify this syntax, open a command prompt, and type tf help diff. When you use the tf diff command, you specify values that are passed to the external tool instead of the tokens, and the external tool then compares the files or folders.

Note

You can abbreviate tf difference as tf diff.

When you configure an external tool for the tf diff command, you must use the tokens %1 and %2 to represent the paths of the source and target files.

You can use the %6 and %7 tokens to specify a human-readable label for the source and target files. If the values of these tokens might contain spaces, you must enclose the values in quotation marks.

Examples

Comparison tool

Value of the TF_DIFF_COMMAND environment variable

GNU diff

 
diff -u "%1" "%2"

GNU diff with labels

 
diff -u --label "%6 / %7" "%1" "%2"

SourceGear DiffMerge

 
diffmerge --title1="%6" --title2="%7" "%1" "%2"

Identify File Changes by Viewing Annotations

You can view annotations for a version-controlled file to determine who made changes and what lines they changed in all earlier versions of the file. When you view annotations, the file appears only in its current state. You do not display a side-by-side comparison of two versions of the file.

To perform these procedures, your Read permission must be set to Allow. For more information, see the following page on the Microsoft website: Team Foundation Server Permissions.

Important

In the Team Foundation Server plug-in for Eclipse, you can use the Annotate command only from Project Explorer or Package Explorer. You cannot use the Annotate command from Source Control Explorer.

To view file annotations

  • In Project Explorer or Package Explorer, right-click the file for which you want to view annotations, point to Team, and then click Annotate.

    An annotation window appears and displays the content of the file that you specified. Along the left edge of the window, a colored channel indicates which lines have been changed.

    If you point to any section of the colored channel, information about the changeset appears in a tooltip. You can press F2 to open a window to browse the changeset information.

    You can customize the display of the revision information if you right-click it, point to Revision, and then click an option.

See Also

Tasks

Resolve Conflicts between Two Files (Team Explorer Everywhere)

Other Resources

Using Version Control (Team Explorer Everywhere)