PowerShell GCI -Include Parameter
My advice is to avoid the -Include parameter. If you want to filter the output then use the -Filter parameter! The problem with -Include is that it doesn’t do what you think. In the case of Get-ChildItem, -Include operates on the path and not on the individual filenames. To overcome this limitation you need a wildcard* or the -Recurse parameter.
Topics for Get-ChildItem -Include
- Example 1: Let Us Get Some Action with -Include
- Example 2: -Include is a Huge Disappointment
- Example 3: Adjustments to Get -Include Working
- Example 4: Ditch -Include; Prefer -Filter
- Try Get-ChildItem -Exclude Instead
Example 1: Let Us Get Some Action with -Include
Scenario: You want an inventory of only the executables in the Windows System32 folder.
# PowerShell GCI -Include example
Get-ChildItem -Path $env:SystemRoot\System32 -Include *e*
Problem 1: You get a few .exe files, but also an assortment of other file types.
Explanation: You struck lucky, the System32 contains ‘e’!
Example 2: The -Include Parameter is a Huge Disappointment
The same scenario: You want a list of exe files in the Windows System32 folder. This time you try *.exe.
Clear-Host
Get-ChildItem -Path $env:SystemRoot\System32 -Include *.exe
Problem 2: No files are returned. Have you realized why? There is no .exe. in the fullname of the stream of objects created by Get-ChildItem.
Example 3: Adjustments to Get -Include Working
Solution A: Add a *wildcard after the folder name:
# PowerShell -Include working example
Clear-Host
Get-ChildItem -Path $env:SystemRoot\System32\* -Include *.exe
Note 1: Appending \* to the path makes all the difference.
Solution B: Append -Recurse
Clear-Host
Get-ChildItem -Path $env:SystemRoot\System32 -Include *.exe -Recurse
This gets -Include working, but you may not want to ‘Recurse’ through all those subfolders.
Here is function I created to extend what Get-ChildItem can achieve. PowerShell Get-File function.
Recommended: Solarwinds’ Permissions Analyzer – Free Active Directory Tool
I like the Permissions Monitor because it enables me to see WHO has permissions to do WHAT at a glance. When you launch this tool it analyzes a users effective NTFS permissions for a specific file or folder, and takes into account network share access, then displays the results in a nifty desktop dashboard!
Think of all the frustration that this free SolarWinds utility saves when you are troubleshooting authorization problems for user’s access to a resource. Give this permissions monitor a try – it’s free!
Download SolarWinds’ Free Permissions Analyser – Active Directory Tool
Example 4: Ditch -Include; Prefer -Filter
Solution C: Ditch -Include; and substitute a parameter called -Filter.
Clear-Host
Get-ChildItem -Path $env:SystemRoot\System32 -Filter *.exe
Eureka: You get a neat list of all the executables in the System32. No unwanted files from the folders lower down the tree.
Conclusion: Now you know why -Include is my least favorite PowerShell parameter, wherever possible employ the -Filter instead. I confess that I have deliberately not shown -Include in its best possible light, nevertheless it always disappoints me whenever I give it a try.
Further Research on Get-ChildItem
Get-Help for Get-ChildItem
# Research PowerShell Get-Childitem Parameters
Get-Help Get-Childitem -Full
Note 2: This reveals parameters such as -Include and -Filter.
Compare with PowerShell’s -Filter parameter »
»
Summary of Get-ChildItem -Include
I don’t rate the -Include parameter. To date I have not found one use for it. When I want to refine the output I find that -filter is far superior.