PowerShell Get-childItem

The Get-ChildItem cmdlet gets the items and the child items in one or more locations. If an item is a container, it gets the items inside the container, known as the child items. A location can be a registry hive, file system registry, or a certificate store.

This cmdlet does not display the empty directories. The gci, dir, ls are the aliases for this cmdlet.

Use the -Recurse parameter to get the items in all child containers and use the -Depth parameter to limit the number of levels to recurse.

Syntax

Get-ChildItem
[[-Path] <string[]>] 
[[-Filter] <string>]
[-Recurse] 
[-Depth <uint32>] 
[-Include <string[]>] 
[-Exclude <string[]>]
[-Name] 
[-Force] [-Directory] 
[-Attributes <FlagsExpression[FileAttributes]>][-FollowSymlink] 
[-File]
[-Hidden]
[-System]
[-ReadOnly]
[<CommonParameters>]

Parameters

-Attribute

This parameter gets the files and folders with the specified attribute, and it supports all the attributes and allows you to specify a complex combination of attributes.

This parameter supports the following properties:

• Archive, Device, Directory, Encrypted, IntegrityStream, Hidden, NotContentIndexed, Normal, Offline, NoScrubData, ReadOnly, ReparsePoint, Compressed, System, SparseFile, and Temporary.

Use the following operators to combine the attributes:

• ! (NOT)
• + (AND)
• , (OR)

Note: Do not use the space between an operator and its attributes but use it after commas.

Use the following abbreviations for common attributes:

• D (Directory)
• H (Hidden)
• R (Read-only)
• S (System)

-Depth

The -Depth parameter was added in the PowerShell 5.0 and allowed you to control the depth of recursion. By default, the cmdlet get-ChildItem displays the content of the parent directory.

This parameter determines the number of subdirectory levels which are included in the recursion and shows the content.

-Directory

The -Directory parameter is used to get the list of the directories. We can also use the -Recurse parameter with the Directory

-Exclude

The -Exclude parameter is specified as a string array, a property. It also specifies those items which cmdlet excludes from the operation. The value of -Exclude parameter qualifies the -Path parameter.

Enter a pattern or a path element, such as A* or *.txt. Wildcard characters are permitted.

-Include

The -Include parameter specifies as a string array, a property. It also specifies those items which cmdlet includes in the operation. The value of -Include parameter qualifies the Path parameter. Enter a pattern or a path element, such as '*.txt'.

This parameter is effective only when a cmdlet includes the contents of an item, such as 'C:\Windows\*', where the wildcard character '*' specifies the contents of the C:\Windows directory.

-File

The -File parameter is used to get a list of files. We can also use the -Recurse parameter with the -File.

-Filter

The -Filter parameter specifies a filter to qualify the -Path parameter. This parameter is more efficient than other parameters because a provider applies them when the cmdlet retrieves the object, rather than having PowerShell filters the object after they are retrieved. The string of filter is passed to .NET API to enumerate the files, and the API supports ? and * wildcards.

-Force

The -Force parameter allows us to get the items which cannot be accessed by the user, such as system or hidden files. This parameter does not override the file/security permissions.

-Hidden

The -Hidden parameter or the -attribute parameter with the Hidden property is used to get only the hidden items.

-Path

The -Path parameter is used to specify a path to one or more location. The default location is the current directory '.'. Wildcards are permitted.

-LiteralPath

The -LiteralPath parameter is also used to specify a path to one or more location. Unlike the -Path parameter, the value of this parameter is used exactly as it is typed. If the path includes any escape character, then enclosed it in quotation marks. No characters are interpreted as the wildcards. Single quotations mark tells the Windows PowerShell not to interpret any character as an escape sequence.

-Name

The -Name parameter is used to retrieve only the name of items in the location. The output of this parameter is a string object which can be sent down the pipeline to other commands. Wildcards characters are accepted.

-Recurse

The -Recurse parameter is used to get the items in the specified location, and all the child items of the location.

-System

Use the -System parameter or -Attribute parameter with the System property to gets only the system files and directories.

-ReadOnly

Use the -ReadOnly parameter or -Attribute parameter with the Readonly property to get only the read-only items.

-FollowSymlink

The -FollowSymlink parameter is used to search the directories which target those symbolic links. It is a dynamic parameter. It is supported only in the FileSystem provider.

Examples

Example 1: To get the child items in the current location

This cmdlet (get-childItem) in this example gets the child items in the current directory or location. It displays all the file and subdirectory names. If an item does not have child items, this cmdlet does not return any output and return to the PowerShell prompt.

By default, this cmdlet lists the mode, LastWriteTime, size(length) of the file, and the name of the item.

Example2: To get the child item for a given path

This example displays the child items for a given path which is given in the cmdlet using the -Path parameter.

Example 3: To get the name of child items in a given directory or location

This example displays only the name of items or files in a given directory by using the -Name parameter. This cmdlet uses the -Path parameter to specify the directory.

Example 4: To get the child items in the current directory and its subdirectories

This example uses the cmdlet get-childItem with the -Recurse parameter to search the current directory and its subdirectories.

Example 5: To get the items using the Depth parameter

This example uses the -Depth parameter to determine the number of subdirectory levels which are included in the recursion. Those Directories which are empty are excluded from the output.

The cmdlet get-chilItem uses the -Path parameter to specify C:\users. The -Depth parameter specifies two levels of recursion.

The cmdlet get-childItem -Path c:\users -Depth 1 displays the content of directory which is specified by the -Path parameter and one level of a subdirectory.