[UPDATE 8/9/2007]  I fixed the broken link to the power tools page. 

[UPDATE 9/8/2006]  TFPT is now available in its own small download: http://go.microsoft.com/?linkid=5422499!  You no longer need to download the VS SDK.  You can find more information about the September ’06 release here.

Back at the start of October, I wrote about the tfpt.exe power toy.  The beta 3 version has been released with the October SDK release.  In the future, we plan to have a better vehicle for delivering it.

Here’s the documentation, minus the screenshots, in case you are trying to decide whether to download the SDK.  The documentation is included in the SDK release as a Word document, including screenshots of the various dialogs (yes, most commands have a GUI, but you can still use the commands from scripts by specifying the /noprompt option).

Review  The only command not documented is the review command, which is very handy for doing code reviews.  When you run “tfpt review” you get a dialog with a list of your pending changes that you can check off as you diff or view each one.

I hope you find these useful.  Please leave a comment, and let us know what you think.

Team Foundation PowerToys

Introduction

The Team Foundation PowerToys (TFPT) application provides extra functionality for use with the Team Foundation version control system. The Team Foundation PowerToys application is not supported by Microsoft.

Five separate operations are supported by the TFPT application: unshelve, rollback, online, getcs, and uu. They are all invoked at the command line using the tfpt.exe application. Some of the TFPT commands have graphical interfaces.

Unshelve (Unshelve + Merge)

The unshelve operation supported by tf.exe does not allow shelved changes and local changes to be merged together. TFPT’s more advanced unshelve operation allows this to occur under certain circumstances.

If an item in the local workspace has a pending change that is an edit, and the user uses TFPT to unshelve a change from a shelveset, and that shelved change is also an edit, then the changes can be merged with a three-way merge.

In all other cases where changes exist both in the local workspace and in the shelveset, the user can choose between the local and shelved changes, but no combination of the changes can be made. To invoke the TFPT unshelve tool, execute

tfpt unshelve

at the command line. This will invoke the graphical interface for the TFPT unshelve tool:

Running TFPT Unshelve on a Specified Shelveset

To skip this dialog, you can specify the shelveset name and owner on the command line, with

tfpt unshelve shelvesetname;shelvesetowner

If you are the owner of the shelveset, then specifying the shelveset owner is optional.

Selecting Individual Items Within a Shelveset for Unshelving

If you specify a shelveset on the command line as in “Running TFPT Unshelve on a Specified Shelveset,” or if you select a shelveset in the window above and click Details, you are presented with the Shelveset Details window, where you can select individual changes within a shelveset to unshelve.

You can check and uncheck the boxes beside individual items to mark or unmark them for unshelving. Click the Unshelve button to proceed.

Unshelve Conflicts

When you press the Unshelve button, all changes in the shelveset for which there is no conflicting local change will be unshelved. You can see the status of this unshelve process in the Command Prompt window from which you started the TFPT unshelve tool.

There may, however, be conflicts which must be resolved for the unshelve to proceed. If any conflicts are encountered, the conflicts window is displayed:

Edit-Edit Conflicts

To resolve an edit-edit conflict, select the conflict in the list view and click the Resolve button. The Resolve Unshelve Conflict window appears.

For edit-edit conflicts, there are three possible conflict resolutions. 

• Taking the local change abandons the unshelve operation for this particular change (it would be as if the change had not been selected for unshelving).
• Taking the shelved change first undoes the local change, and then unshelves the shelved change. This results in the local change being completely lost.
• Clicking the Merge button first attempts to auto-merge the two changes together, and if it cannot do so without conflict, attempts to invoke a pre-configured third-party merge tool to merge the changes together. The local change is not lost by choosing to merge – if the merge fails, the local change remains.

The Auto-Merge All Button

The Auto-Merge All button is enabled when there are edit-edit conflicts remaining that are unresolved. Clicking the button goes through the edit-edit conflicts and attempts to auto-merge the changes together. For each conflict, if the merge succeeds, then the conflict is resolved. If not, then the conflict is marked as “Requires Manual Merge.” In order to resolve conflicts marked as “Requires Manual Merge,” you must select the conflict and click the Resolve… button. Clicking the Merge button will then start the configured third-party merge tool. If no third-party merge tool is configured, then the conflict must be resolved by selecting to take the local change or take the shelved change.

Generic Conflicts

Any other conflict (a local delete with a shelved edit, for example) is a generic conflict that cannot be merged.

There is no merge option for generic conflicts. You must choose between keeping the local change and taking the shelved change.

Aborting the Unshelve Process

Because the unshelving process makes changes to the local workspace, and because the potential exists to discover a problem halfway through the unshelve process, the TFPT Unshelve application makes a backup of the local workspace before starting its execution if there are pending local changes. This backup is stored as a shelveset on the server. In the event of an abort, all local pending changes are undone and the backup shelveset is unshelved to the local workspace. This restores the workspace to the state it was in before the unshelve application was run.

The backup shelveset is named by adding _backup and then a number to the name of the shelveset that was unshelved. For example, if the shelveset TestSet were unshelved, the backup shelveset would be named TestSet_backup1. Up to 9 backup shelvesets can exist for each shelveset.

With the backup shelveset, changes made during an unshelve operation can be undone after the unshelve is completed but before the changes are checked in, by undoing all changes in the workspace and then unshelving the backup shelveset:

tf undo * /r

tf unshelve TestSet_backup1

Rollback

Sometimes it may be necessary to undo a checkin of a changeset. This operation is directly not supported by Team Foundation, but with the TFPT rollback tool you can pend changes which attempt to undo any changes made in a specified changeset.

Not all changes can be rolled back, but in most scenarios the TFPT rollback command works. In any event, the user is able to review the changes that TFPT pends before checking them in.

To invoke the TFPT rollback tool, execute

tfpt rollback

at the command line. This will invoke the graphical user interface (GUI) for the TFPT rollback tool. Please note that there must not be any changes in the local workspace for the rollback tool to run. Additionally, a prompt will be displayed to request permission to execute a get operation to bring the local workspace up to the latest version.

The Find Changesets window is presented when the TFPT rollback tool is started. The changeset to be rolled back can be selected from the Find Changesets window.

Specifying the Changeset on the Command Line

The Find Changesets window can be skipped by supplying the /changeset:changesetnum command line parameter, as in the following example:

tfpt rollback /changeset:3

Once the changeset is selected, either by using the Find Changesets window or specifying a changeset using a command-line parameter, the Roll Back Changeset window is displayed.

Each change is listed with the type of change that will be counteracted by a rollback change.

To rollback a:	The tool pends a:
Add, Undelete, or Branch	Delete
Rename	Rename
Delete	Undelete
Edit	Edit

Unchecking a change in the Roll Back Changeset window marks it as a change not to be rolled back. There are cases involving rolling back deletes which may result in unchecked items being rolled back. If this occurs, clear warnings to indicate this are displayed in the command prompt window. If this is unsatisfactory, undo the changes pended by the rollback tool.

When the changes to roll back have been checked appropriately, pressing the Roll Back button starts the rollback. If no failures or merge situations are encountered, then the changes should be pended and the user returned to the command prompt:

Merge scenarios can arise when a rollback is attempted on a particular edit change to an item that occurred in-between two other edit changes. There are two possible edit rollback scenarios: 

1. An edit is being rolled back on an item, and the edit to roll back is the latest change to the content of the item.

    

This is the most common case. Most rollbacks are performed on changesets that were just checked in. If the edit was just checked in, it is unlikely that another user has edited it in the intervening time.

To roll back this change, an edit is pended on the item, and the content of the item is reverted to the content from before the changeset to roll back.

 

2. An edit is being rolled back on an item, and the edit to roll back is not the latest change to the content of the item.

    

This is a three-way merge scenario, with the version to roll back as the base, and the latest version and the previous version as branches. If there are no conflicts, then the changes from the change to roll back (and only the change to roll back) are extracted from the item, preserving the changes that came after the change to roll back.

 

In the event of a merge scenario, the merge window is displayed:

To resolve a merge scenario, select the item and click the Merge button. An auto-merge will first be attempted, and if it fails, the third-party merge tool (if configured) will be invoked to resolve the merge. If no third-party merge tool is configured, and the auto-merge fails, then the item cannot be rolled back:

The Auto-Merge All button attempts an auto-merge on each of the items in the merge list, but does not attempt to invoke the third-party merge tool.

Failures

Any changes which fail to roll back will also be displayed in the same window.

Online

With Team Foundation, a server connection is necessary to check files in or out, to delete files, to rename files, etc. The TFPT online tool makes it easier to work without a server connection for a period of time by providing functionality that informs the server about changes made in the local workspace.

Non-checked-out files in the local workspace are by default read-only. The user is expected to check out the file with the tf checkout command before editing the file. When working in this

When working offline with the intent to sync up later by using the TFPT online tool, users must adhere to a strict workflow:

 

• Users without a server connection manually remove the read-only flag from files they want to edit. Non-checked-out files in the local workspace are by default read-only, and when a server connection is available the user must check out the file with the tf checkout command before editing the file. When working offline, the DOS command “attrib –r” should be used.
• Users without a server connection add and delete files they want to add and delete. If not checked out, files selected for deletion will be read-only and must be marked as writable with “attrib –r” before deleting. Files which are added are new and will not be read-only.
• Users must not rename files while offline, as the TFPT online tool cannot distinguish a rename from a deletion at the old name paired with an add at the new name.
• When connectivity is re-acquired, users run the TFPT online tool, which scans the directory structure and detects which files have been added, edited, and deleted. The TFPT online tool pends changes on these files to inform the server what has happened. 

   

To invoke the TFPT online tool, execute

 

tfpt online

at the command line. The online tool will begin to scan your workspace for writable files and will determine what changes should be pended on the server.

By default, the TFPT online tool does not detect deleted files in your local workspace, because to detect deleted files the tool must transfer significantly more data from the server. To enable the detection of deleted files, pass the /deletes command line option.

When the online tool has determined what changes to pend, the Online window is displayed.

Individual changes may be deselected here if they are not desired. When the Pend Changes button is pressed, the changes are actually pended in the workspace.

Important Note: If a file is edited while offline (by marking the file writable and editing it), and the TFPT online tool pends an edit change on it, a subsequent undo will result in the changes to the file being lost. It is therefore not a good idea to try pending a set of changes to go online, decide to discard them (by doing an undo), and then try again, as the changes will be lost in the undo. Instead, make liberal use of the /preview command line option (see below), and pend changes only once.

Preview Mode

The Online window displayed above is a graphical preview of the changes that will be pended to bring the workspace online, but a command-line version of this functionality is also available. By passing the /preview and /noprompt options on the command line, a textual representation of the changes that the TFPT online tool thinks should be pended can be displayed.

tfpt online /noprompt /preview

Inclusions

The TFPT online tool by default operates on every file in the workspace. Its focus can be more directed (and its speed improved) by including only certain files and folders in the set of items to inspect for changes. Filespecs (such as *.c, or folder/subfolder) may be passed on the command line to limit the scope of the operation, as in the following example:

tfpt online *.c foldersubfolder

This command instructs the online tool to process all files with the .c extension in the current folder, as well as all files in the foldersubfolder folder. No recursion is specified. With the /r (or /recursive) option, all files matching *.c in the current folder and below, as well as all files in the foldersubfolder folder and below will be checked. To process only the current folder and below, use

tfpt online . /r

Exclusions

Many build systems create log files and/or object files in the same directory as source code which is checked in. It may become necessary to filter out these files to prevent changes from being pended on them. This can be achieved through the /exclude:filespec1,filespec2,… option.

With the /exclude option, certain filemasks may be filtered out, and any directory name specified will not be entered by the TFPT online tool. For example, there may be a need to filter out log files and any files in object directories named “obj”.

tfpt online /exclude:*.log,obj

This will skip any file matching *.log, and any file or directory named obj.

GetCS (Get Changeset)

The TFPT GetCS tool gets all the items listed in a changeset at that changeset version.

This is useful in the event that a coworker has checked in a change which you need to have in your workspace, but you cannot bring your entire workspace up to the latest version. You can use the TFPT GetCS tool to get just the items affected by his changeset, without having to inspect the changeset, determine the files listed in it, and manually list those files to a tf.exe get command.

There is no graphical user interface (GUI) for the TFPT GetCS tool. To invoke the TFPT GetCS tool, execute

tfpt getcs /changeset:changesetnum

at the command line, where changesetnum is the number of the changeset to get.

UU (Undo Unchanged)

The TFPT UU tool removes pending edits from files which have not actually been edited.

This is useful in the event that you check out fifteen files for edit, but only actually make changes to three of them. You can back out your edits on the other twelve files by running the TFPT UU tool, which compares hashes of the files in the local workspace to hashes the server has to determine whether or not the file has actually been edited.

There is no graphical user interface (GUI) for the TFPT UU tool. To inv