Get-ChildItem

Get the items and child items in a folder or registry key. If the item is a container, it gets the items inside the container, known as child items. You can use the Recurse parameter to get items in all child containers. Aliases: dir / ls / gci

Syntax
      Get-ChildItem [ [-path] string[] | [-literalPath] string[] ] 
         [-Attributes FileAttributes] [[-filter] string] [-include string[]] [-exclude string[]]
            [-FollowSymlink] [-Depth UInt32] [-Name] [-Directory] [-File] [-Hidden]
               [-ReadOnly] [-recurse] [-force] [-System] [-UseTransaction] [CommonParameters]

Key
   -path string
       The paths to the items from which content is to be retrieved.
       Wildcards are permitted. Default is the current directory (.)

   -literalPath string
       Like Path above, only the value is used exactly as typed. [bug: ignores filters]
       No characters are interpreted as wildcards. If the path includes any escape characters then
       enclose the path in single quotation marks.
       One or more locations can be specified as a string array.

   -Attributes {ReadOnly | Hidden | System | Directory | Archive | Device |  Normal | Temporary | SparseFile | 
                ReparsePoint | Compressed | Offline | NotContentIndexed | Encrypted |  IntegrityStream | NoScrubData}

       Get files and folders with the specified attributes.
       This parameter supports all attributes and complex combinations of attributes.

       For example, to get non-system files (not directories) that are encrypted or compressed, type:
            Get-ChildItem -Attributes !Directory+!System+Encrypted, !Directory+!System+Compressed

       To find files and folders with commonly used attributes, you can use the Attributes parameter, or the 
        -Directory, -File, -Hidden, -ReadOnly, and -System switch parameters.

       A 'Normal' file is a standard file that has no special attributes. This attribute is valid only if it is used alone.

       Use the following operators to combine attributes.
           !    NOT
           +    AND
           ,    OR
       No spaces are permitted between an operator and its attribute. However, spaces are permitted before commas.

       Abbreviations for commonly used attributes:
           D    Directory
           H    Hidden
           R    Read-only
           S    System

   -Depth UInt32
       use with –Recurse to limit the recursion to UInt32 levels.

   -Directory
       Get directories (folders).  
       To get only directories, use -Directory and omit -File.
       To exclude directories, use -File and omit -Directory, or use the -Attributes parameter.      
       alias: ad

   -File
       Get files. 
       To get only files, use -File and omit -Directory.
       To exclude files, use -Directory and omit -File, or use the -Attributes parameter.

   -FollowSymlink  (PowerShell 6.0+)
       Search any directories that are the target of symbolic links in the search path.
       By default, Get-ChildItem displays symbolic links to directories found during recursion, but
       doesn't recurse into them. This is a dynamic parameter and is supported only in the FileSystem provider.

   -Hidden
       Get only hidden files and directories (folders).
       By default, Get-ChildItem gets only non-hidden items, use the -Force parameter to include
       both hidden and non-hidden items in the results.

   -include string
       Include only the specified items from the Path. e.g. 'May*'
       This parameter is only effective when the command includes -Recurse to match files
       or if the string matches the contents of a directory.
       So to match  C:\demo\sample.txt you could use:  GCI -include *sample.txt
       For most providers particularly the filesystem, the -filter parameter is a better/faster way
       to filter results. e.g.  GCI -filter sample.txt

   -exclude string
       Omit the specified items from the Path e.g. '*SS64*'

   -force
       Get all items including hidden or system files, but will not override
       security/file permissions. You can also get hidden files and folders with -Hidden or
       with the Hidden value of the -Attributes parameter.

   -filter string
       A filter in the provider's format or language. 
       The exact syntax of the filter (wildcard support etc) depends on the provider.

       A filesystem -filter will use the old Win32/DOS syntax - see the wildcards page for details.
       Filters are slightly more efficient than -include/-exclude, because the provider
       applies the filter when retrieving the objects, rather than having 
       PowerShell filter the objects after they are retrieved.

   -Name 
       Retrieve only the names of the items.
       This is useful when piping the names of the child items to another command.

   -ReadOnly
       Get only read-only files and directories (folders).  
       To exclude read-only items, use the -Attributes parameter.
       Alias: ar

   -recurse 
       Get the items plus all child items of the location(s).
       Only for paths that point to a container such as C:\Windows or C:\Windows\*
       A path such as *.txt will not have any child items.

   -Depth UInt32

   -System
       Get only system files and directories (folders).
       To exclude system files and folders, use the -Attributes parameter.
       Alias: as 

   -UseTransaction
       Include the command in the active transaction. This option was removed in PowerShell 6.0.

Standard Aliases for Get-ChildItem: dir, list, ls, gci

By default, Get-ChildItem gets only non-hidden items, but you can use the -Directory, -File, -Hidden, -ReadOnly, and -System parameters to get only items with these attributes.

When listing files and sub-directories, get-childitem will return the mode (attributes), last write time, file size (length), and the filename.
Valid modes (attributes) are: d (directory), a (archive), r (read-only), h (hidden), and s (system).

The default path is the current directory ' . '
To specify all the items in the current directory use '*'

Wildcards

When listing a single folder (without recursion), you can do get-childitem c:\music\*.mp3
Unlike the CMD shell, in PowerShell the path filter of c:\music\*.mp3 is applied only to files not folders (or other containers).

To apply a wildcard recursively to a whole tree of items in PowerShell add the -recurse parameter:
get-childitem c:\music\*.mp3 -recurse

or more explicitly:
get-childitem c:\music\ -filter *.mp3 -recurse

Examples

Get the child items in the current location:

PS C:\> get-childitem

Get a plain list of full filenames, like DIR /b without a header, Select just the FullName:

PS C:\> (gci "C:\some folder").FullName > fileListing.txt

If some of the filenames are very long they may be truncated, to avoid this add -expandProperty:

PS C:\> gci "C:\some folder" | select -expandProperty FullName | `
out-file -encoding utf8 'C:\demo\demo.txt'

List all subdirectory names, but only going one level below the given directory:

PS C:\> Get-ChildItem -Directory -Path "C:\some folder" -Recurse -Depth 1 -name

If listing files to the console, then you may need to use Write-Host -width 999 to ensure that nothing gets truncated:

PS C:\> $stuff = gci "C:\some folder" | select -expandProperty FullName
PS C:\> Write-Host -width 999 $stuff

An effect similar to the above can be had by piping the result to format-table –hidetableheaders however Format-Table will also pad the output with spaces.

Get all the .XLS files in a folder:

PS C:\> get-childitem \\Server64\Work\* -filter *.xls

Count all the .XLSX files in a folder and all sub-folders:

PS C:\> $a = get-childitem \\Server64\Work\ -filter *.xlsx -Recurse
PS C:\> $a.Count

Get all the empty directories under the path C:\demo, [ GetFiles().Count would return directories with no files but with sub-folders]:

PS C:\> (gci -Directory C:\demo -r | ?{$_.GetFileSystemInfos().Count -eq 0} | select FullName

Get all the files owned by BWithers:

PS C:\> C:\> get-childitem C:\Work\ -recurse | get-acl | where {$_.Owner -match "BWithers"}

Get all files, including hidden files, in the current directory, but exclude subdirectories,
The second command below uses aliases and abbreviations, but has the same effect as the first:

PS C:\> Get-ChildItem -Attributes !Directory,!Directory+Hidden
PS C:\> dir -att !d,!d+h

Get a list of sub-folder names and store in $folders:

PS C:\> $folders = gci 'C:\YourDir' | Where-Object{($_.PSIsContainer)} | foreach-object{$_.Name}

Measure the size of a folder:

PS C:\> Get-ChildItem C:\Work\ -Recurse -Force | Measure-Object -property length -sum

Measure the size of a folder and display in GB, (to also round the numbers use the -F operator):

PS C:\> (Get-ChildItem C:\Work\ -Recurse -Force | Measure-Object -property length -sum).sum / 1Gb

Get all the certificates in the certificate store, use the dynamic parameter -codesigningcert to get only certificates with code-signing authority. ( see "get-help certificate" for more):

PS C:\> get-childitem cert:\. -recurse -codesigningcert

List the certificates and their thumbprints for the current user:

PS C:\> CD cert:\currentuser\my
PS C:\> Get-ChildItem

“You [humans] think that you an insignificant, while there is a great universe contained in you” ~ Ali ibn Abi Talib

Related PowerShell Cmdlets:

Wildcards - Match multiple items.
Get-Item - Get a file object or get a registry (or other namespace) object.
Get-Location - Display the current location.
Measure-Object - Measure the properties of an object - use this to return the size of a file or folder.
Test-Path - Return true if the path exists, otherwise return false.
Join-Path -resolve - Combine a path and child-path.
Superuser - Find all empty directories.


 
Copyright © 1999-2024 SS64.com
Some rights reserved