Get-ChildItem: List Files & Folders with PowerShell

Remember the good ol’ days of the DOS dir command? How about the Linux ls command? If so, the Get-childItem is essentially that but taken up a notch.

In fact, we even have dir and ls in PowerShell in the form of an alias. The Get-Childitem PowerShell cmdlet can not only list files and folders on a file system via the PowerShell console or PowerShell script but can also enumerate registry keys and values, certificates in various certificates stores and even Active Directory, to name a few.

If you’re a beginner/intermediate PowerShell scripter, be sure to check out my FREE mini-course on Building a PowerShell Tool! 9,000+ words of deep explanation and insights on how to build a PowerShell tool.

To understand Get-Childitem, first, think of it regarding dir and ls but instead of just files it treats many objects as a child item and enumerates them. You can use the alias or the full command name to use it.

Since this command has been available since PowerShell v1, you can be sure that it will work with your PowerShell version.

Get-ChildItem Traverses a Tree

A file system is a hierarchy. It has a folder structure with files inside of folders and those folders inside of other folders. A file system is like a tree. That tree has a trunk (C:\ for example) and “branches” coming off of it (folders). In fact, we even have a tree command.

PS> tree
Folder PATH listing for volume HD
Volume serial number is 0000007B 22DC:666C
C:.
 \modules
   \AdsiPS
     \1.0.0.2
       \Public
       \AWSPowerShell
<SNIP>

You can point this command at either local paths on the local computer, use a PowerShell remote scriptblock and use Get-ChildItem inside of that or just point it at a UNC path. All work the same. Maybe I just want to list all of the files in the current directory.

PS> dir -Path .
PS> Invoke-Command -ComputerName SERVER1 -Scriptblock { dir -Path . }

PowerShell Providers

Microsoft realized that navigating this “tree” like structure of a file system could be applied to other systems as well. A file system “tree” has folders and files but a registry has keys and values while the certificate system in Windows has stores and certificates inside of those stores. Each of these specific areas can all be represented as a tree thus the PowerShell provider was born. Why all this talk about PowerShell providers? Because the Get-ChilldItem cmdlet is part of the *-Item cmdlets that interact with PowerShell drives that each provider exposes.

The Get-ChildItem cmdlet can output any number of objects on a PowerShell drive and allows you to process each item via the pipeline or perhaps in a PowerShell foreach loop. It understands the concept of a PowerShell drive which allows you to specify a Path of a file system folder, a registry key or a certificate store all in one.

You can see below that this command can enumerate the C:\ folder, the HKEY Current User hive as well as the PowerShell certificate store.

PS> Get-ChildItem -Path C:\


    Directory: C:\


Mode                LastWriteTime         Length Name
----                -------------         ------ ----
d-----         7/2/2017   7:01 AM                AppData
d-----        4/25/2017   4:36 PM                CheckPoint

PS> Get-ChildItem -Path HKCU:\


    Hive: HKEY_CURRENT_USER


Name                           Property
----                           --------
BCD00000000

PS> dir -Path Cert:\


Location   : CurrentUser
StoreNames : {TrustedPublisher, ClientAuthIssuer, Root, UserDS...}

Filtering

The Get-ChildItem PowerShell command cannot only pull all objects on a drive but can filter the information as well through a couple of different parameters: Filter, Include and Exclude. You’ll always want to use the ubiquitous PowerShell Filter parameter when possible. This parameter directly passes the filter syntax to the individual provider. Although much quicker, this syntax solely depends on the provider being queried.

For example, a Filter syntax of Name -eq 'foo' may be completely fine when querying files but won’t work at all when querying the registry because the registry provider doesn’t even have a filter!

PS> dir HKLM:\ -Filter "Name -eq 'foo'"
ls : Cannot call method. The provider does not support the use of filters.
At line:1 char:1 + ls HKLM:\ -Filter "Name -eq 'foo'" +
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~     + CategoryInfo          :
NotImplemented: (:) [Get-ChildItem], PSNotSupportedException     +
FullyQualifiedErrorId :
NotSupported,Microsoft.PowerShell.Commands.GetChildItemCommand

When all else fails though, you always have the Include and Exclude parameters as well.

This command in PowerShell also has a few filesystem-specific parameters like Force which will output hidden files and folders, File and Directory which only finds files or folders. Take a look at the full breakdown of Get-ChildItem via Get-Help or in the Microsoft docs.

Another cool thing about Get-ChildItem is it’s ability to resolve paths when using the wildcard character. In PowerShell, wildcard character typically represents anything. For example, if you’d like to see all files with the .txt file extension, just specify the path to the folder and *.txt.

PS> Get-ChildItem -Path 'C:\*.txt'

We could also filter on file attributes as well. Perhaps we just want to find only the read-only files in a folder.

PS> Get-ChildItem -Path C:\ -Attributes R -File

Summary

This PowerShell command is one of those cmdlets that you’ll use repeatedly. Most of the time, you’ll probably be using the FileSystem provider, but it’s important to remember that this cmdlet is capable of much more. Use it to query files, folders, registry keys, registry values, certificates, Active Directory users, computers or even environment variables, functions and more!

When in doubt, run the Get-PSDrive command to see a list of all of the loaded PowerShell drives that Get-ChildItem can query for you.