Destroy Command (Team Foundation Version Control)
TFS 2017 | TFS 2015 | TFS 2013
Visual Studio 2019 | Visual Studio 2017 | Visual Studio 2015 | Visual Studio 2013
Use the tf destroy command to destroy, or permanently delete, version-controlled files from Team Foundation version control.
The destroy action cannot be reversed. You must not destroy files that are still needed. Sometimes you have to clean up version control systems. For example, if some files are infected with a computer virus, you have to remove them permanently from version control.
Before you run tf destroy without the /keephistory option, we recommend that you first delete the files you want to destroy. For more information, see Delete Files and Folders from Version Control.
After you delete the files you can synchronize the Team Foundation warehouse. Otherwise, the warehouse will not be synchronized with the destroyed items.
Prerequisites
To use the destroy command, you must belong to the Team Foundation Administrators security group. For more information, see Default TFVC permissions.
Syntax
tf destroy [/keephistory] <itemspec1>[;<versionspec>][<itemspec2>...<itemspecN>]
[/stopat:<versionspec>] [/preview] [/startcleanup] [/noprompt] [/silent] [/login:username,[password]] [/collection:TeamProjectCollectionUrl]]
Parameters
Argument
Argument
Description
itemspec1 [itemspec2...itemspecN]
Specifies the server path of the file or folder to be destroyed. Use multiple itemspec values to delete multiple items. For example, tf destroy $/TeamProject1 $/teamProject2 $/TeamProject3.
Local paths are not supported.
versionspec
Provides a version such as C58 for the /keephistory or /stopat options. The allowed values are date, tip, or a specific changeset. For more information about how Team Foundation parses a version specification to determine which items are within its scope, see Use Team Foundation version control commands.
username
Provides a value to the /login option. You can specify a username value as either DOMAIN UserName or UserName.
TeamProjectCollectionUrl
The URL of the project collection that contains files that you want to destroy (for example, http://myserver:8080/tfs/DefaultCollection).
Option
Option
Description
/keephistory
Optional. Specifies that the history of a file is preserved even as its contents are destroyed. This cannot be specified with the /preview option.
/stopat
Optional. Can be used only if /keephistory is specified also.
Specifies the file version for the file, and the files that follow thereafter, for which the history is preserved.
The default version for /stopat is tip (T) for the latest checked-in version of an item.
You cannot use label or workspace versionspec values to specify an item for /stopat option.
/preview
Displays in the Command Prompt window the files that would be destroyed. When tf destroy runs in the preview mode, the files are not actually destroyed.
Note
The text in the Command Prompt window displays the word "Destroyed" with each file that would be destroyed. However, the file is actually not destroyed when the /preview option is used.
/startcleanup
Forces the TFVC metadata clean-up process to start immediately after the deletion finishes. If the user does not specify /startcleanup, the destroyed metadata clean-up process occurs when the database maintenance cleans up all the files that are no longer referenced by Visual Studio Team Foundation Server. By default, the clean-up is scheduled to run every 5 days. Seven days after the TFVC metadata are cleaned up the content will be deleted by another clean-up process. By default, this content clean-up process runs once each day.
/noprompt
/i
Specifies that the destruction of files is non-interactive. /i is an alias for /noprompt.
/silent
Specifies that, when you destroy files or folders, the output is not written to the command prompt window.
/login
Specifies the user name and password to authenticate the user with Team Foundation Server.
/collection
Specifies the project collection.
Remarks
When you use tf destroy to destroy version-control files, the application tier of Team Foundation Server receives the destroy request and checks to see whether you are a member of the Team Foundation Administrators security group. If you are not a member, the system displays an error-message dialog box that tells you that you do not have sufficient permissions to perform the operation.
After the system verifies your permissions, it runs the destroy command. This command deletes all file references, shelvesets, and pending changes. The actual destruction of files, which is a permanent deletion, happens the next time that the content that is no longer referenced by Team Foundation Server is cleaned up. You can also specify the /startcleanup option to clean up the files immediately after tf destroy runs.
If you run tf destroy without specifying /i and /preview, the system displays a console Yes or No prompt for each filespec value. Otherwise, you can specify Yes to all. If you do not specify /keephistory, you are prompted by an interactive text that warns of pending changes, if they exist. The interactive text points to /preview if you want more information about the changes. If you specify /keephistory, you are also prompted by Yes, No, or All text. If you select Yes or All, the destruction process starts, and the server paths to the destroyed items appear in the Command Prompt window.
Destroyed: <serverItem1>
Destroyed: <serverItem2>
Destroyed: ...
If you specified the versionspec value as a tip, the server paths displayed in the Command Prompt window include deletion IDs. For example, X123 might appear in the Command Prompt window.
If you use the /preview option, the files are not destroyed, but the command-line text displays the files that would be destroyed. For example, if, at the command-line, you type tf destroy /preview $/Test1/MyProject/MyProject/Program.cs, the command window displays this text:
Destroyed: $/Test1/MyProject/MyProject/Program.cs
However, the file is actually not destroyed because you used the /preview option.
For more information on how to find the tf command-line utility, see Use Team Foundation version control commands.
Effects of /keephistory on Other Version Control Operations
If you specify the /keephistory option to retain the history of destroyed files, the files are treated as destroyed by the following Team Foundation version control operations:
Change content If you try to change the content of a destroyed file, for example edit or branch, the system issues an error message that states the content has been destroyed.
Branch, merge, or unshelve If you try to branch, merge, or unshelve destroyed items, the system issues an error message that states the content of the items has been destroyed.
Destroying Previously Deleted Items
If an item has already been deleted, a deletion ID is attached to it and results in a filename change.
Effects of TF DESTROY on TFVC repo Code Search
Code Search does not handle TF DESTROY notifications and so using TF DESTROY for TFVC repos will not automatically delete files in the Search index. As a result, these files appear in the code search results. To avoid these ghost files scenario, users are recommended to delete files before TF DESTROY operation.
Examples
Description
The following example permanently deletes the file a.cs.
Code
C:\pi\ws1>tf destroy $/proj/pi/a.cs
Description
The following example deletes a folder, aFolder, type at the command line:
Code
C:\tf delete $/MyTeamProject/aFolder
Description
To destroy the deleted item, aFolder, you must type at the command line:
Code
tf destroy $/MyTeamProject/sFolder;x123
Where x123 is the deletion ID.