Confused with -Include parameter of the Get-ChildItem cmdlet

Question

From documentation:

-Include

Retrieves 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.

The Include parameter is effective only when the command includes the Recurse parameter or the path leads to the contents of a directory, such as C:\Windows*, where the wildcard character specifies the contents of the C:\Windows directory.

My first understanding was:

c:\test\a.txt
c:\test\b.txt

So to get 'a.txt' and 'b.txt' I can write:

gci -Path "c:\test\*" -Include "*.txt"

And this works. But now consider such hierarchy:

c:\test\a.txt
c:\test\b.txt
c:\test\c.txt\c.txt

The same command returns: a.txt, b.txt, c.txt

The actual logic seems to be:

-Include used to match all entities specified by -Path. If matched element is a file - return it. If matched element is a folder, look inside and return matching first level children.

Also, the documentation say:

The Include parameter is effective only when the command includes the Recurse parameter or the path leads to the contents of a directory...

This is wrong as well. E.g.

gci -Path "c:\test" -Include "*.txt"

It returns nothing, while without -Include I get folder content. So -Include is definitely "effective". What really happens here? The -Path specify the "c:\test", and the -Include tries to match this path. As "*.txt" does not match "test", so nothing returned. But look at this:

gci -Path "c:\test" -Include "*t"

It returns a.txt, b.txt and c.txt as "*t" matched "test" and matched all child items.

After all, even knowing how Include works now, I don't understand when to use it. Why do I need it look to inside subfolders? Why should it be so complex?

Answer 1

You're confusing the use of -include. The -include flag is applied to the path, not the contents of the path. Without the use of the recursive flag, the only path that is in question is the path you specify. This is why the last example you gave works, the path c:\test has a t in the path and hence matches "*t".

You can verify this by trying the following

gci -path "c:\test" -in *e*

This will still produce all of the children in the directory yet it matches none of their names.

The reason that -include is more effective with the recurse parameter is that you end up applying the wildcard against every path in the hierarchy.