PowerShell v3 in a Year Day 13 Clear Content

Topic: Clear-Content
Alias: clc

The help for Clear-Content says, "Deletes the contents of an item, such as deleting the text from a file, but does not delete the item." Clear-Content is the antithesis of the Get-Item cmdlet insofar as it focuses on the contents of an object, not on the object itself. Here is a quick demonstration of how to use it. We will first create a small dummy file with the contents of the directory, then, we will call the Clear-Content cmdlet to remove the contents.

PS >dir >. est.txt

To verify we have content in the file, we call dir (Get-ChildItem) and reference the specific file to which we dumped content:

PS >dir . est.txt

    Directory: C:dir

Mode                LastWriteTime     LengthName

----                -------------     ----------

-a---         11/2/2012  11:14 PM       6572 test.txt 

As you can see, the Length (character count) is 6572. That sounds about right for this directory. Now, lets clear out the files contents:

PS >Clear-Content -Path. est.txt

To verify it did the job, we call Get-ChildItem again which displays a .length property of 0.

PS >dir . est.txt

    Directory: C:dir

Mode                LastWriteTime     LengthName

----                -------------     ----------

-a---         11/2/2012  11:15 PM          0 test.txt

As noted in the help, "The Clear-Content cmdlet deletes the contents of an item, such as deleting the text from a file, but it does not delete the item. As a result, the item exists, but it is empty. Clear-Content is similar to Clear-Item, but it works on files instead of on aliases and variables." It is important to keep in mind, as indicated above, it works specifically on files, not, other providers.

To get more specific, here are the two parameter sets for Clear-Content:

• Clear-Content [-Path] <String[]> [-Credential <PSCredential>] [-Exclude <String[]>] [-Filter <String>] [-Force[<SwitchParameter>]] [-Include <String[]>] [-Confirm [<SwitchParameter>]] [-WhatIf [<SwitchParameter>]][-UseTransaction [<SwitchParameter>]] [<CommonParameters>]
• Clear-Content [-Credential <PSCredential>] [-Exclude <String[]>] [-Filter <String>] [-Force [<SwitchParameter>]] [-Include <String[]>] -LiteralPath <String[]> [-Confirm [<SwitchParameter>]] [-WhatIf [<SwitchParameter>]] [-UseTransaction [<SwitchParameter>]] [<CommonParameters>]

For the first set the parameters are:

• Path
• Credential
• Exclude
• Filter
• Force
• Include
• Confirm
• WhatIf
• UseTransaction

The second parameter set has the following choices:

• Credential
• Exclude
• Filter
• Force
• Include
• LiteralPath
• Confirm
• WhatIf
• UseTransaction

Some examples of how to use Clear-Content are listed below:

• This example demonstrates how to clear the contents of a wildcarded selection of .txt files in the C:userswill directory whose name ends with _iis.log. Clear-Content -Path C:userswill*_iis.log
• Here is an example that shows how to clear the contents of all files with a .log extension. The -Force parameter is a switch which, when included, indicates to the command to clear the contents of read-only files as well: clear-content -path * -filter *.log -force.
• Here is an example that looks in the C: emp directory for files whose names begin with Smp, does not include the number 2. The -WhatIf switch suppresses the actual changes from being made and  clear-content c:Temp* -Include Smp* -Exclude *2* -whatif

This is a relatively lightweight cmdlet, but, it is important to have it well-placed in the tool kit. Instead of having to delete files, which sometimes is the fastest way to remove content, calling Clear-Content might be just as effective, if not more so, than, calling Remove-Item. In either case, Clear-Content is a great way to reset the contents of a file object so you have a blank slate. In cases where you are logging and need to clear logs every day, this proves to be the perfect tool for the job.

One caveat I find important to point out any time one is dealing with file system objects (and their related cmdlets) involves some confusion with how -Filter, -Include and -Exclude work. After having fought this battle plenty of times, I found great blog post by Thomas Lee, Get-ChildItem and the–Include and –Filter parameters, which explains some issues folks run into when working with these three parameters. Before you start using this cmdlet heavily be sure to explore how these parameters work (and misbehave). After you get a good feel for their real-world usages of these folk, go to town, but, make use of the -WhatIf parameter a lot as you test this out.