Remove-Item

 

Additional Resources for Remove-Item

Deleting a File or Folder (Or Other Type of Object) http://www.microsoft.com/technet/scriptcenter/topics/msh/cmdlets/remove-item.mspx

 

SYNOPSIS

Deletes the specified items.

 

SYNTAX

Remove-Item [-path] <string[]> [-recurse] [-force] [-include <string[]>] [-exclude <string[]>] [-filter <string>] [-credential <PSCredential>] [-whatIf] [-confirm] [<CommonParameters>]

 

Remove-Item [-literalPath] <string[]> [-recurse] [-force] [-include <string[]>] [-exclude <string[]>] [-filter <string>] [-credential <PSCredential>] [-whatIf] [-confirm] [<CommonParameters>]

 

DETAILED DESCRIPTION

The Remove-Item cmdlet deletes one or more items. Because it is supported by many providers, it can delete many different types of items, including files, directories, registry keys, variables, aliases, certificates, and functions.

 

PARAMETERS

 

-path <string[]>

Specifies a path to the items being removed. Wildcards are permitted. The parameter name ("-Path") is optional.

 

Required?	true
Position?	1
Default value	N/A - The path must be specified
Accept pipeline input?	true (ByValue, ByPropertyName)
Accept wildcard characters?	true

 

-recurse <SwitchParameter>

Deletes the items in the specified locations and in all child items of the locations.

 

The Recurse parameter in this cmdlet does not work properly.

 

Required?	false
Position?	named
Default value	False
Accept pipeline input?	false
Accept wildcard characters?	false

 

-force <SwitchParameter>

Overrides restrictions that prevent the command from succeeding, just so the changes do not compromise security. For example, Force will override the read-only attribute or create directories to complete a file path, but it will not attempt to change file permissions.

 

Required?	false
Position?	named
Default value	False
Accept pipeline input?	false
Accept wildcard characters?	false

 

-include <string[]>

Deletes only the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt".Wildcards are permitted.

 

Required?	false
Position?	named
Default value
Accept pipeline input?	false
Accept wildcard characters?	true

 

-exclude <string[]>

Omits the specified items. The value of this parameter qualifies the Path parameter. Enter a path element or pattern, such as "*.txt". Wildcards are permitted.

 

Required?	false
Position?	named
Default value
Accept pipeline input?	false
Accept wildcard characters?  true

 

-filter <string>

Specifies a filter in the provider's format or language. The value of this parameter qualifies the Path parameter. The syntax of the filter, including the use of wildcards, depends on the provider. Filters are more efficient than other parameters, because the provider applies them when retrieving the objects, rather than having Windows PowerShell filter the objects after they are retrieved.

 

Required?	false
Position?	named
Default value
Accept pipeline input?	false
Accept wildcard characters?	false

 

-credential <PSCredential>

Uses a credential to validate access to the file. <Credential> represents a user-name, such as "User01" or "Domain01\User01", or a PSCredential object, such as the one retrieved by using the Get-Credential cmdlet. If you type a user name, you will be prompted for a password. This parameter appears, but it is not supported in any Windows PowerShell core cmdlets or providers.

 

Required?	false
Position?	named
Default value
Accept pipeline input?	true (ByPropertyName)
Accept wildcard characters?	false

 

-literalPath <string[]>

Specifies a path to the items being removed. Unlike Path, the value of LiteralPath is used exactly as it is typed. No characters are interpreted as wildcards. If the path includes escape characters, enclose it in single quotation marks. Single quotation marks tell Windows PowerShell not to interpret any characters as escape sequences.

 

Required?	true
Position?	1
Default value
Accept pipeline input?	true (ByPropertyName)
Accept wildcard characters?	false

 

-whatIf

Describes what would happen if you executed the command without actually executing the command.

 

Required?	false
Position?	named
Default value
Accept pipeline input?	false
Accept wildcard characters?	false

 

-confirm

Prompts you for confirmation before executing the command.

 

Required?	false
Position?	named
Default value
Accept pipeline input?	false
Accept wildcard characters?	false

 

<CommonParameters>

This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, and -OutVariable. For more information, type, "get-help about_commonparameters".

 

INPUT TYPE

String

 

NOTES

 

For more information, type "Get-Help Remove-Item -detailed". For technical information, type "Get-Help Remove-Item -full".

 

 When specifying multiple values for a parameter, use commas to separate the values. For example, "<parameter-name> <value1>, <value2>".

 

You can also refer to Remove-Item by any of its built-in aliases, " del ", "erase", "rmdir", "rd", "ri", or "rm". For more information, see About_Alias.

 

EXAMPLE 1

 

 

This command deletes all of the files with names that include a dot (.) from the C:\Test directory. Because the command specifies a dot, the command does not delete directories, or files with no file name extension.

 

EXAMPLE 2

 

 

This command deletes from the current directory all files with a .doc file name extension and a name that does not include "1". It uses the wildcard character (*) to specify the contents of the current directory. It uses the Include and Exclude parameters to specify the files to delete.

 

EXAMPLE 3

 

 

This command deletes a file that is both hidden and read-only. It uses the Path parameter to specify the file. It uses the Force parameter to give permission to delete it. Without Force, you cannot delete read-only or hidden files.

 

EXAMPLE 4

 

 

This command deletes all of the CSV files in the current directory and all subdirectories recursively.

 

Because the Recurse parameter in this cmdlet is faulty, the command uses the Get-Childitemcmdlet to get the desired files, and the pipeline operator to pass them to the Remove-Item cmdlet.

 

In the Get-Childitemcommand, the Path parameter has a value of *, which represents the contents of the current directory. It uses the Include parameter to specify the CSV file type, and the Recurse parameter to make the retrieval recursive.

 

If you try to specify the file type in the path, such as "-path *.csv", the cmdlet interprets the subject of the search to be a file that has no children, and the Recurse fails.

 

EXAMPLE 5

 

 

This command deletes the OldApp registry key and all of its subkeys and values. It uses the Remove-Item cmdlet to remove the key. The path is specified, but the optional parameter name (Path) is omitted.

 

The Recurse parameter deletes all of the contents of the OldApp subkey recursively. If the key contains subkeys, and you omit the Recurse paraemter, you are prompted to confirm that the you want to delete the contents of the key.

 

RELATED LINKS

Get-Item

Copy-Item

Move-Item

New-Item

Rename-Item

Set-Item

Clear-Item

Invoke-Item

about_namespace