One of the most fundamental and useful cmdlets in PowerShell is Get-ChildItem. This cmdlet lists the contents of directories, similar to the dir or ls commands in other operating systems.
In this blog post, we’ll explore how to use the Get-ChildItem cmdlet to retrieve and list files, folders, registry keys, and certificates.
Note. The examples in this post will use PowerShell 7.3. Some parameters do not apply in Windows PowerShell 5.1.
Table of Contents
PowerShell Get-ChildItem Cmdlet Aliases
While it’s true that using the full command when scripting is ideal, command aliases come in handy when running them manually. And like most PowerShell cmdlets, Get-ChildItem has three aliases or shorthand commands that you can use interchangeably: dir, gci, and ls.
PowerShell Get-ChildItem Cmdlet Syntax
The basic syntax of the Get-ChildItem cmdlet is as follows:
Get-ChildItem [[-Path] <string[]>] [[-Filter] <string>] [-Include <string[]>] [-Exclude <string[]>] [-Recurse] [-Depth <uint>] [-Force] [-Name] [-Attributes <FlagsExpression[FileAttributes]>] [-FollowSymlink] [-Directory] [-File] [-Hidden] [-ReadOnly] [-System] [<CommonParameters>] Get-ChildItem [[-Filter] <string>] -LiteralPath <string[]> [-Include <string[]>] [-Exclude <string[]>] [-Recurse] [-Depth <uint>] [-Force] [-Name] [-Attributes <FlagsExpression[FileAttributes]>] [-FollowSymlink] [-Directory] [-File] [-Hidden] [-ReadOnly] [-System] [<CommonParameters>]
As you can see, there are two parameter sets, meaning some parameters cannot be used in the same command.
Let’s break down the essential parameters:
- Path: Specifies the directory path you want to list the contents of. If not provided, the current directory is used as the default.
- Filter: Specifies a filter to apply to the list of items. You can use wildcards (e.g., .txt) to narrow the results.
- Include: Specifies the patterns of items to include. This parameter works in combination with Recurse to retrieve only specified items.
- Exclude: Specifies the patterns of items to exclude. This parameter also works with Recurse.
- Recurse: Retrieves items from all subdirectories recursively.
- Force: Includes hidden and system items in the output.
- File: Retrieves only files.
- Directory: Retrieves only directories (folders).
- Hidden: Retrieves only “Hidden” items.
- ReadOnly: Retrieves only “Read-only” items.
- System: Retrieves only “System” items.
PowerShell GCI: Listing Contents of a Directory
To list the contents of a directory, provide the path to that directory as an argument. For example:
Get-ChildItem C:\Path\To\Directory
This will list all the files and folders in the specified directory.
PowerShell GCI: Listing Only Files or Directories
If you want to list only files or directories, use the -File or -Directory parameter, respectively.
To list only files:
Get-ChildItem C:\Path\To\Directory -File
To list only directories:
Get-ChildItem C:\Path\To\Directory -Directory
PowerShell GCI: Filtering by File Type
You can filter the results based on file type using the -Filter parameter. For instance, to list all text files in a directory:
Get-ChildItem C:\Path\To\Directory -Filter *.txt
PowerShell GCI: Recursively Listing Contents
To list the contents of a directory and its subdirectories, use the -Recurse parameter:
Get-ChildItem C:\Path\To\Directory -Recurse
PowerShell GCI: Limiting Recursion Depth
To list the contents of a directory and its subdirectories while limiting the depth of recursion, -Depth <uint> parameter. For example, the below command limits the recursion to one subfolder only.
Get-ChildItem C:\Path\To\Directory -Depth 1
PowerShell GCI: Listing Contents by Attributes
Files and folders have attributes such as hidden, system, and read-only. You can make Get-ChildItem retrieve items based on them.
By default, Get-ChildItem does not return hidden items. To display them, you can add the -Force switch.
Get-ChildItem C:\Path\To\Directory -Force
To list only hidden, read-only, and system files, append the -Hidden, -ReadOnly, and -System switches.
Get-ChildItem C:\Path\To\Directory -Hidden Get-ChildItem C:\Path\To\Directory -ReadOnly Get-ChildItem C:\Path\To\Directory -System
You can also use the -Attribute parameter and specify the different attributes. For example, run this command to show system, read-only, and hidden files.
Get-ChildItem C:\Path\To\Directory -Attributes System, Hidden, ReadOnly
This example retrieves files that do not have the Archive attribute.
Get-ChildItem C:\Path\To\Directory -Attributes System, Hidden, ReadOnly
How about listing files and folders that do not have the archive attribute?
Get-ChildItem C:\Path\To\Directory -Attributes !Archive
How about listing items that do not have the archive attribute, excluding directories?
Get-ChildItem C:\Path\To\Directory -Attributes !Archive+!Directory
PowerShell GCI: List Registry Items
The PowerShell registry provider exposes the registry like a file system, like:
- Drives are the registry hives.
- Registry keys are folders.
For example, to list the HKCU:registry path using the PowerShell LS command:
ls HKCU:\Software\Microsoft\OneDrive
PowerShell GCI: List Certificates
PowerShell also has a certificate provider that exposes the certificate store as the Cert: drive.
For example, the below command lists the root certificates in the current user’s certificate store.
gci Cert:\CurrentUser\Root\
With that, you can also use the PowerShell GCI command to get certificates that will expire within a specific period. For example, this command lists all local machine certificates that expire within the next ten months.
gci Cert:\LocalMachine\My | Where-Object {$_.NotAfter -lt (Get-Date).AddMonths(10)} | Select-Object ThumbPrint, Subject, NotAfter
Conclusion
Understanding the Get-ChildItem cmdlet in PowerShell opens up a world of possibilities for efficiently managing and exploring files, directories, registry entries, and certificates. With its various parameters and options, you can easily customize your searches, filter results, and retrieve specific attributes.
Whether listing the contents of directories, filtering by file types, recursively exploring subdirectories, or working with attributes, the Get-ChildItem cmdlet provides a powerful tool for navigating and managing your system’s resources.
