Unlock the Power of Directory Navigation with Get-ChildItem in PowerShell

Common Scenarios to use this Cmdlet

When I’m working, issues commonly arise that require locating and manipulating files and folders. This can include finding and removing certain objects or generating a report. Given a root folder and a problem, we can use the Get-ChildItem PowerShell Cmdlet as our tool to achieve our goal. When navigating file systems, tasks like locating duplicates, tracking down specific file types, or auditing folder contents become routine. Get-ChildItem is indispensable for these scenarios, simplifying complex operations efficiently.

An Overview of Get-ChildItem

The Cmdlet Arguments

There are a few arguments but in combination they can be used for a broad scope of tasks.

Downside of Using Get-ChildItem

These arguments should seem familiar to you if you have used other Management cmdlets. These are powerful arguments, but it’s important to note that Get-ChildItem can be slow when traversing directories recursively, especially over network shares (UNC paths). This slowness is due to several factors, but most importantly Object Fetching. Get-ChildItem fetches an entire .NET object of data about each file. So, every file you recursively output is creating an instance of a FileSystemInfo class. Pulling this data over the network wire adds to the time required for fetching properties and other details. This Stackoverflow discussion explains in detail the performance issues, but it is somewhat over my head.

Setting up our Environment

First, I want to setup an environment where I can use the arguments such as depth and filter. I wanted to practice recursive functions in PowerShell, and created directories recursively and adding files to the directory at each depth was challenging for me and took a bit for me to put together. Yet, using recursion simplified my initial function dramatically and made it less confusing for me.

function CreateAndEvenlySortDirectories($number, $depth, $limit){

    if($number -le $limit){

        $currentDir = $PSScriptRoot

        for($i = 0; $i -le $depth; $i++){
            $dirPath = join-path $currentDir "dir$i"

            if( -not (test-path $dirPath)){
                New-Item -path $dirPath -ItemType Directory 1>$null
            }
            # is set at each iteration of the outer loop so file will be created
            $currentDir = $dirPath
        }
        New-Item -ItemType File -Name "file$number.txt" -Path $currentDir 1>$null
        CreateAndEvenlySortDirectories ($number + 1) ($number % 4) 21
    }else{
        Write-Output "Script Completed."
    }
}
CreateAndEvenlySortDirectories 0 0 21

Function Explanation

The CreateAndEvenlySortDirectories function accepts three parameters, the number at the current recursive call, the depth, which you can modify by changing the modulus devisor, and the limit. The great thing about this is it’s scalable, so the higher the limit and the modulus divisor, the more depth you can achieve. In the function if the $number is greater than the limit, we will end the code. In this call, I start the depth at zero and within the loop – one iteration initially due to less than or equal to comparison operator- we parse and test for the path. If it does not exist, we create it and then set the $currentDir outside the loop scope to $dirPath. Once the loop iterations are complete, we exit the loop scope and create a new file named file$number in $currentDir. Then it recursively calls the function, adding one to $number and taking the modulus of the incremented number, and passing in with a modulus divisor four. It’s cool because you can view the file number placement based on the modulus value when calling the function. It’s kind of like a wave, so the iterations with continue to change, and we set the path and add the file to it, the recurse. I couldn’t figure out a way to not use a loop to traverse the nested directories if they existed in this context but leave a comment or Contact me if you have a solution or any advice! We are always learning.

Get-ChildItem Examples

We ran the function above in a terminal. With our directory structure configured as such with text files nested in each, let’s start.

dir0
  - dir1
    - dir2
      - dir3
        - dir4

What It Returns and How its Useful

We will run a simple command to retrieve all the files and directories in the root path with no depth. -Depth 0 is the defalt value so you don’t need it.

get-childItem -Path .\dir0\ -Depth 0

You’ll see Mode, LastWriteTime, Name and Length file properties. Remeber though, Get-ChildItem returns instances of FileInfo instances. So if you run

get-childItem -Path .\dir0\ -Depth 0 | select *

You will see all the properties of the class instance you can use. I don’t know all of them but I’m sure they can be useful. Also, Get-ChildItem returns an array, so you can retrieve an index from the array. I will retrieve the instance of the FileInfo class.

PS C:\Users\hola\Desktop> (get-childItem -Path .\dir0\ -Depth 0 | select *)[0]


PSPath            : Microsoft.PowerShell.Core\FileSystem::C:\Users\hola\Desktop\dir0\dir1
PSParentPath      : Microsoft.PowerShell.Core\FileSystem::C:\Users\hola\Desktop\dir0
PSChildName       : dir1
PSDrive           : C
PSProvider        : Microsoft.PowerShell.Core\FileSystem
PSIsContainer     : True
Mode              : d-----
BaseName          : dir1
Target            : {}
LinkType          :
Name              : dir1
FullName          : C:\Users\hola\Desktop\dir0\dir1
Parent            : dir0
Exists            : True
Root              : C:\
Extension         :
CreationTime      : 3/2/2024 2:14:58 PM
CreationTimeUtc   : 3/2/2024 7:14:58 PM
LastAccessTime    : 3/2/2024 2:14:58 PM
LastAccessTimeUtc : 3/2/2024 7:14:58 PM
LastWriteTime     : 3/2/2024 2:14:58 PM
LastWriteTimeUtc  : 3/2/2024 7:14:58 PM
Attributes        : Directory

Decent and useful object of properties we can use at work.

Retrieve Specific File Extension in a Directory

We can also use Get-ChildItem to search for specific file in a directory using -Include argument. When using the Include argument, pass in the *.(file extension) and also use the wildcard * after the directory – so -Path .\dir0* – unless you’re using the Recurse argument. Since it returns an array of objects, we can pass in the -Name argument to only retrieve that property, then validate a file is within that directory using the -in Comparison Operator. With a few lines of code, we can traverse the ocean and detect our file.

$txtFilesInRoot = get-childItem -Path .\dir0\* -Include *.txt -Name
Write-Output $txtFilesInRoot.GetType()

# IsPublic IsSerial Name                                     BaseType
# -------- -------- ----                                     --------
# True     True     Object[]                                 System.Array

Write-Output ("file5.txt" -in $txtFilesInRoot)
# True

#----This will retrieve every file recursively from the root path specified.
Get-ChildItem -path .\dir0 -File -Name -Recurse

Comparing the Creation Date of a FileInfo Instance

You can also search for a directory names recursively, replacing the -File argument with -Directory. Here is a real-world example using Get-ChildItem to determine the creation date of a folder

$directorySearch = (Get-ChildItem -path .\dir0 -Directory -Recurse) -match 'dir2'
$timeRange = 10 # minutes

if($null -ne $directorySearch){

    foreach($dir in $directorySearch) {
        # $timeRange.GetType()
        Write-Output("{0} was detected" -f $dir.FullName)
        $createdAtBool = $dir | Select-Object @{n="WasCreatedTenMinutesAgo"; e={($_.CreationTime) -ge (Get-Date).AddMinutes(-$timeRange)}}
        Write-Output("{0} was 10 minutes ago: {1}." -f $dir.Name, $createdAtBool.WasCreatedTenMinutesAgo)
    }
}

# Output 
C:\Users\hola\Desktop\dir0\dir1\dir2 was detected
dir2 was 10 minutes ago: True.

In this code we are trying to match a directory, dir2. If $directorySearch isn’t $null, we can loop through the array, create a Calculated Property that returns a boolean value. This value is returned by comparing the CreationTime property of the FileInfo instance to a DateTime instance we declared. I subtracted 10 minutes, but you can mess around with it.

Exclude Overriding Include Get-ChildItem Cmdlet

Another important point to make here is that the -Exclude argument always wins over the -Include. So if you were searching for a specific file with -Include, and that file happed to be a file extension you were excluding, then it would not output. Let’s take this example.

Write-Output "----- ALL TXT FILES IN dir0\"
Get-ChildItem -path .\dir0\* -Include *.txt -Name
Write-Output "----- ALL TXT FILES EXCLUDING file0.txt dir0\"
Get-ChildItem -path .\dir0\* -Include *.txt -Exclude file0* -Name
if($null -eq (Get-ChildItem -path .\dir0\* -Include *.txt -Exclude *.txt)){
    Write-Output "----- EXCLUDE BEATS INCLUDE"
}

Conclusion

In this blog post, we’ve taken a closer look at a handy tool in PowerShell called Get-ChildItem. I tried to create some useful real-world examples, but identifying when to use this and implementing a solution will assist your workload. Imagine it as a virtual explorer for your computer’s files and folders, allowing you to search and retrieve specific types of items with ease. So, next time you find yourself buried in a sea of files or folders, remember the trusty Get-ChildItem cmdlet—it’s your virtual guide to navigating through the digital landscape effortlessly. Any information or advice about this post? Leave a comment or Contact Me!