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[]]
            [-Depth <UInt32>]  [-Name] [-Directory] [-File] [-Hidden]
               [-ReadOnly] [-recurse] [-force] [-System] [-UseTransaction] [CommonParameters]

      Get-ChildItem [-Attributes FileAttributes] [-Directory] [-File] [-Force] [-Hidden]
         [-ReadOnly] [-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.
       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

   -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.

   -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*'
        
   -exclude string
       Omit the specified items from the Path e.g. '*SS64*'
        
   -filter string
       A filter in the provider's format or language. 
       The exact syntax of the filter (wildcard support etc) depends on the provider.
       Filters are 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 

   -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.
        
   -UseTransaction
       Include the command in the active transaction.

   CommonParameters:
       -Verbose, -Debug, -ErrorAction, -ErrorVariable, -WarningAction, -WarningVariable,
       -OutBuffer -OutVariable.

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)
The way to apply a wildcard recursively to a whole tree of items in PowerShell is to use the -include parameter:
get-childitem c:\music\ -include *.mp3 -recurse

This change in syntax was required because some providers (such as the registry provider) allow backslashes in a value name, separating the -path from the -include string makes it possible to use get-childitem against any provider: files, registry, processes etc.

Examples

Get the child items in the current location:
PS C:\> get-childitem

Get all the .XLS files in a folder and all sub-folders:
PS C:\> $a = get-childitem \\Server64\Work\ -Include *.xls -Recurse
PS C:\> $a.Count

Get all the .XLS files in a folder:
PS C:\> get-childitem \\Server64\Work\* -Include *.xls

Get all the files owned by BWithers:
PS C:\> PS 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 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

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

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

Related:

Wildcards - Match multiple items.
Get-Item - Get a file object or get a registry (or other namespace) object.
Get-Location - Display the current location.
Join-Path -resolve - Combine a path and child-path.


Copyright © SS64.com 1999-2017
Some rights reserved