How does the Get-ChildItem -Exclude Parameter work?

7
votes

How does the Get-ChildItem -Exclude parameter work? What rules does it follow?

The Get-Help for Get-ChildItem isn't detailed at all:

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.

And on Stackoverflow and elsewhere the general consensus seems to be it's too difficult to use and we should all just pipe the output of Get-ChildItem to Where-Object instead.

While I'm willing to use Where-Object I'm curious as to the rules -Exclude follows.

For example, I have a folder with the following sub-folders:

HsacFixtures
HsacFixturesBuild
RestFixture
RestFixtureBuild

If I execute the following command:

Get-ChildItem $rootFolderPath -Exclude HsacFixturesBuild -Directory

it returns the results expected:

HsacFixtures
RestFixture
RestFixtureBuild

However, if I add a -Recurse parameter: 

Get-ChildItem $rootFolderPath -Exclude HsacFixturesBuild -Directory -Recurse

Then it returns sub-folders in the HsacFixturesBuild folder.

I've also tried HsacFixturesBuild\ and HsacFixturesBuild\*, which have the same results.

So does -Exclude only apply to immediate children, and not to grand-children or deeper sub-folders?

2
powershell
get-help Get-ChildItem -full, has examples and details. – Kory Gill
@KoryGill: Thanks but I'd already checked help -full. There's only one example with -Exclude and the parameter description is very brief (see the quote in my question). It wasn't enough to understand the rules it operates under. – Simon Tewsi
@SimonTewsi, Exclude filters on the name of the object. So even though the object is a grandchild the exclude only looks at the object name, not the path. – Nkosi

2 Answers

10
votes

Exclude omits child objects based on the Name,

For files, gets the name of the file. For directories, gets the name of the last directory in the hierarchy if a hierarchy exists. Otherwise, the Name property gets the name of the directory

not the FullName,

which gets the full path of the directory or file

So even though the object is a grandchild in a recursive call, the exclude only looks at the object's Name, not the FullName so the exclude wont affect omission unless the child objects share a common substring of the name that happens to be part of the exclude parameter

Source Get-ChildItem

Example 3: Get all child items using an inclusion and exclusion

This command lists the .txt files in the Logs subdirectory, except for those whose names start with the letter A. It uses the wildcard character (*) to indicate the contents of the Logs subdirectory, not the directory container. Because the command does not include the Recurse parameter, the command does not include the content of directory automatically; you need to specify it.

Windows PowerShell

PS C:\> Get-ChildItem –Path "C:\Windows\Logs\*" -Include "*.txt" -Exclude "A*"
4
votes

With respect to Get-ChildItem,-exclude parameter works on the objects name

It could be understood better from the following example: Consider the following folder structure

enter image description here

First we use -exclude parameter without recurse. enter image description here

As we could see in the above image, based on objects name , folder was excluded

Now we add recurse parameter to the above statement as follows enter image description here

Now we see could see that sub-folders of folder is still present, because the exclusion was applied at objects name

Hope this HElps.