title: Confused with -Include parameter of the Get-ChildItem cmdlet
body: <p>From documentation: </p>
  
  <blockquote>
    <p>-Include</p>
    
    <p>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. </p>
    
    <p>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.</p>
  </blockquote>
  
  <p>My first understanding was:</p>
  
  <pre><code>c:\test\a.txt
  c:\test\b.txt
  </code></pre>
  
  <p>So to get 'a.txt' and 'b.txt' I can write:</p>
  
  <pre><code>gci -Path "c:\test\*" -Include "*.txt"
  </code></pre>
  
  <p>And this works. But now consider such hierarchy:</p>
  
  <pre><code>c:\test\a.txt
  c:\test\b.txt
  c:\test\c.txt\c.txt
  </code></pre>
  
  <p>The same command returns:
     a.txt, b.txt, c.txt</p>
  
  <p>The actual logic seems to be:</p>
  
  <blockquote>
    <p>-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.</p>
  </blockquote>
  
  <p>Also, the documentation say:</p>
  
  <blockquote>
    <p>The Include parameter is effective only when the command
    includes the Recurse parameter or the
    path leads to the contents of a
    directory...</p>
  </blockquote>
  
  <p>This is wrong as well. E.g.</p>
  
  <pre><code>gci -Path "c:\test" -Include "*.txt"
  </code></pre>
  
  <p>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:</p>
  
  <pre><code>gci -Path "c:\test" -Include "*t"
  </code></pre>
  
  <p>It returns a.txt, b.txt and c.txt as "*t" matched "test" and matched all child items.</p>
  
  <p>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?</p>