Get-ChildItem: List and Find Files in CI
Get-ChildItem lists files and folders and, with -Recurse plus -Filter, finds matching files across a tree, the PowerShell equivalent of dir /s or find.
Locating build outputs, collecting test results, or verifying an artifact tree all start with Get-ChildItem. Its filtering and recursion flags decide how fast and precise the search is.
What it does
Get-ChildItem enumerates items in a path. -Recurse descends subdirectories, -Filter applies a fast provider-level wildcard, -Include/-Exclude apply PowerShell-side patterns, and -File/-Directory restrict to one kind. It returns objects you can pipe to other cmdlets.
Common usage
# find every .nupkg in the tree
Get-ChildItem -Path . -Recurse -Filter *.nupkg -File
# collect TRX test results into one place
Get-ChildItem -Recurse -Filter *.trx | Copy-Item -Destination .\results
# total size of build output
(Get-ChildItem .\bin -Recurse -File | Measure-Object Length -Sum).SumOptions
| Parameter | What it does |
|---|---|
| -Recurse | Descend into subdirectories |
| -Filter <pat> | Fast single-wildcard match at the provider level |
| -Include / -Exclude | PowerShell-side patterns (need -Recurse or a trailing \*) |
| -File / -Directory | Return only files or only directories |
| -Force | Include hidden and system items |
| -Path <p> | Where to start (defaults to current directory) |
In CI
Prefer -Filter *.ext over -Include for speed: -Filter is applied by the filesystem provider, while -Include filters after enumeration. Add -File when you only want files (avoids piping directory objects into a copy/hash step). Use -ErrorAction SilentlyContinue when scanning trees that may contain locked paths.
Common errors in CI
-Include returning nothing without -Recurse is the classic surprise: -Include only applies to the leaf of -Path, so it needs -Recurse or a path ending in \*. "Cannot find path ... because it does not exist" means the start directory is wrong (often a relative path from the wrong working dir). "Access to the path is denied" during -Recurse can halt the scan; add -ErrorAction SilentlyContinue to skip locked items.