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

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.

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
Get-ChildItem -Path $env:SystemRoot\System32\* -Include *.exe

Note 1: Appending \* to the path makes all the difference.

Solution B: Append -Recurse

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.

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.

By admin

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.