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.

Answer 2

Try the -filter parameter (it has support for only one extension):

dir -filter *.txt

Answer 3

Tacking on to JaredPar's answer, in order to do pattern matching with Get-ChildItem, you can use common shell wildcards.

For example:

get-childitem "c:\test\t?st.txt"

where the "?" is a wildcard matching any one character or

get-childitem "c:\test\*.txt"

which will match any file name ending in ".txt".

This should get you the "simpler" behavior you were looking for.

Answer 4

I just asked a similar question and got three quick replies concerning the Get-Help for Get-ChildItem.

The answer is in the full description of the command (Get-Help Get-ChildItem -full):

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.

So the following would work without recurse.

PS C:\foo> Get-childitem -path "c:\foo*" -Include *.txt

From Stack Overflow question PowerShell Scripting - Get-ChildItem.

I hope this helps :-)

Answer 5

Including \* at the end of the path should work around the issue

PS C:\logfiles> Get-ChildItem .\* -include *.log

This should return .log files from the current working directory (C:\logfiles)

Alex's example above indicates that a directory with the name foo.log would also be returned. When I tried it, it wasn't but it's 6 years later and that could be from PS updates.

However, you can use the child item Mode to exclude directories I think.

PS C:\logfiles> Get-Childitem .\* -include *.log | where-object {$_.mode -notmatch "d"}

This should exclude anything with the 'directory' mode set.

Answer 6

get-childitem -include only works with -recursive or a wildcard in the path. I consider this a bug [Thought it was different in PS 6].