11

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?

alex2k8
  • 39,732
  • 56
  • 158
  • 214

6 Answers6

14

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.

JaredPar
  • 673,544
  • 139
  • 1,186
  • 1,421
  • I am using PowerShell-v2.0-CTP3, and your example produces empty set. – alex2k8 Apr 26 '09 at 17:21
  • @alex2k8, Not sure what to say here. I've tried this example on 1.0 and a later 2.0 build, both produce the same results. – JaredPar Apr 26 '09 at 17:25
  • @Jared, this is strange. Please, can you try gci -path c:\* -in *. I see children of the c:\ and all it's subfolders one level down. Here is the similar description http://www.eggheadcafe.com/software/aspnet/32624832/getchilditem-include-qu.aspx – alex2k8 Apr 26 '09 at 23:33
9

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

dir -filter *.txt

Shay Levy
  • 107,077
  • 26
  • 168
  • 192
  • 5
    Filter is slightly different because it is a provider specific implementation. It's typically more efficient because it occurs before the data is returned. But it does have a different implementation for every drive provider in PowerShell. Hence there can be subtle differences in the matching algorithm. – JaredPar Apr 26 '09 at 17:59
  • I agree, though in this case we're talking about the file system provider. Thnaks for the comment. – Shay Levy Apr 27 '09 at 06:32
5

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.

Community
  • 1
  • 1
Steven Murawski
  • 10,299
  • 36
  • 51
  • Isn't the issue here that you can only get a single extension? -Include is string[] allowing for multiple matching variations. Thanks, Ben – Bennett Dill Sep 02 '09 at 21:29
2

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 :-)

Community
  • 1
  • 1
Bennett Dill
  • 2,835
  • 4
  • 37
  • 37
  • Ben, actually my question was a bit different. Notice, that your example will return .txt files from the foo folder, BUT it can also unexpectedly return files and even folders from for example "c:\foo\dir.txt" directory. Try such hierarchy: c:\foo\dir.txt\file.txt and c:\foo\dir.txt\dir2.txt\file2.txt. You'll get: file.txt and dir2.txt! – alex2k8 Sep 02 '09 at 23:05
0

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.

Nathan Tuggy
  • 2,239
  • 27
  • 28
  • 36
Stephquan
  • 1
  • Including \* at the end of the path does not always work. I know of no way to specify an -Include value to match files that have no filename extension. Specifying * as an -Include pattern will match such files, but makes Get-ChildItem act recursively. If -Include behaved the same way as Exclude, it would be easy. – MikeOnline Aug 05 '15 at 00:44
0

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

js2010
  • 13,551
  • 2
  • 28
  • 40