You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/en-US/Get-PSTree.md
+65-48Lines changed: 65 additions & 48 deletions
Original file line number
Diff line number
Diff line change
@@ -9,7 +9,7 @@ schema: 2.0.0
9
9
10
10
## SYNOPSIS
11
11
12
-
`tree` like cmdlet for PowerShell.
12
+
A PowerShell cmdlet that displays a hierarchical, tree-like view of folder contents, including folder size calculations, inspired by the classic `tree` command.
13
13
14
14
## SYNTAX
15
15
@@ -45,75 +45,85 @@ Get-PSTree
45
45
46
46
## DESCRIPTION
47
47
48
-
`Get-PSTree`is a PowerShell cmdlet that intends to emulate the `tree` commandwith added functionalities to calculate the folders size as well as recursive folders size.
48
+
The `Get-PSTree`cmdlet offers a tree-style visualization of a folder's contents, drawing inspiration from the classic `tree` command. It displays the file system hierarchy, including directories and files, with enhanced functionality to calculate folder sizes—both individual and recursive—making it ideal for analyzing disk usage and organizing file structures. This cmdlet supports filtering by depth and enabling recursive traversal, enabling efficient exploration of file systems on any supported platform. Use it to identify large folders, manage directory layouts, or gain insights into file system organization.
49
49
50
50
## EXAMPLES
51
51
52
-
### Example 1: Get the current directory tree with default parameters values
52
+
### Example 1: Get the current Directory Tree with Default Parameters
53
53
54
54
```powershell
55
55
PS ..\PSTree> Get-PSTree
56
56
```
57
57
58
-
The default parameter set uses `-Depth` with a value of 3. No hidden and system files folder are displayed and recursive folder size is not calculated.
58
+
This example retrieves the directory and file structure of the current directory, using the default parameters: __a depth of 3 levels__and no recursive traversal beyond that limit. It displays both directories and files, including their sizes, but does not include hidden or system items unless explicitly requested through other means.
59
59
60
-
### Example 2: Get the `$HOME`tree recursively displaying only folders
60
+
### Example 2: Display the `$HOME`Directory Tree Recursively, Showing Only Directories
In this example `$HOME`is bound positionally to the `-Path` parameter.
66
+
This example retrieves the complete directory hierarchy under the `$HOME`path, traversing all subfolders recursively and displaying only directories (excluding files).
67
67
68
-
### Example 3: Get the `$HOME`tree 2 levels deep displaying hidden files and folders
68
+
### Example 3: Display the `$HOME`Directory Tree, Limited to 2 Levels, Including Hidden Items
69
69
70
70
```powershell
71
-
PS ..\PSTree> Get-PSTree -Depth 2 -Force
71
+
PS ..\PSTree> Get-PSTree $HOME -Depth 2 -Force
72
72
```
73
73
74
74
> [!TIP]
75
-
> The `-Force` switch is needed to display hidden files and folders. In addition, hidden child items do not add up to the folders size without this switch.
75
+
> The `-Force` switch is required to include hidden files and folders in the output. Additionally, hidden items contribute to folder sizes (including recursive sizes with [`-RecursiveSize`](#-recursivesize), if specified), ensuring a comprehensive view of disk usage.
76
76
77
-
### Example 4: Get the `C:\`drive tree 2 levels in depth displaying only folders calculating the recursive size
77
+
### Example 4: Display the `C:\`Drive Tree, Limited to 2 Levels, Showing Only Directories with Recursive Sizes
### Example 5: Get the `$HOME` tree recursively excluding all `.jpg` and `.png` files
83
+
This example retrieves the directory structure under the `C:\` drive, limited to 2 levels of depth, displaying only directories (excluding files) and calculating their recursive sizes. It provides a controlled view for analyzing disk usage, summing the sizes of all files within each directory and its subdirectories.
84
+
85
+
### Example 5: Display the `$HOME` Directory Tree Recursively, Excluding `.jpg` and `.png` Files
> - The `-Exclude` parameter supports [wildcard patterns](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_wildcards?view=powershell-7.3), exclusion patterns are evaluated using the items `.Name` property.
92
-
> -__Excluded items do not do not add to the folders size.__
93
+
> - The `-Exclude` parameter supports [wildcard patterns](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_wildcards?view=powershell-7.3), and patterns are evaluated using the items’ `.Name` property.
94
+
> - Excluded items, such as `.jpg` and `.png` files in this case, do not contribute to folder sizes, including recursive sizes calculated by [`-RecursiveSize`](#-recursivesize).
95
+
96
+
This example retrieves the complete directory and file hierarchy under the `$HOME` path, traversing all subfolders recursively, while excluding files matching the patterns `*.jpg` and `*.png`. It displays remaining directories and files with their sizes, useful for focusing on specific file types or managing disk space.
93
97
94
-
### Example 6: Get the tree of all folders in a location
98
+
### Example 6: Display the Tree of All Directories in the Current Location
> Output from `Get-ChildItem`can be piped to this cmdlet. Pipeline input is bound to `-LiteralPath` parameter if the items have a `PSPath` property.
105
+
> Output from cmdlets that work with the file system and return `System.IO.FileSystemInfo` objects (e.g., `Get-ChildItem`, `Get-Item`) can be piped to `Get-PSTree`. Pipeline input is bound to the `-LiteralPath` parameter if the objects have a `PSPath` property, enabling seamless traversal of multiple directory structures with default settings (depth of 3, no recursion unless specified).
102
106
103
-
### Example 7: Get the tree of all folders in a location including only `*.ps1` files
107
+
This example pipes the output of `Get-ChildItem` to `Get-PSTree`, retrieving the directory and file structure for each directory in the current location. It displays hierarchies with default depth (3 levels) and folder sizes, excluding hidden or system items unless [`-Force`](#-force) is used.
108
+
109
+
### Example 7: Display the Tree of All Directories in the Current Location, Including Only `.ps1` Files
> Similar to `-Exclude`, the `-Include` parameter supports [wildcard patterns](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_wildcards?view=powershell-7.3), however, __this parameter works only with Files__.
116
+
>
117
+
> - Similar to `-Exclude`, the `-Include` parameter supports [wildcard patterns](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_wildcards?view=powershell-7.3), __but it applies only to files, not directories__.
118
+
> - Only files matching the pattern (e.g., `*.ps1`) are included in the output, while directories are always shown to maintain the hierarchy.
119
+
120
+
This example pipes the output of `Get-ChildItem` to `Get-PSTree`, retrieving the directory structure for each directory in the current location, but including only `.ps1` files within those directories. It displays the hierarchy with default depth (3 levels) and folder sizes, useful for focusing on PowerShell scripts while preserving directory context.
111
121
112
122
## PARAMETERS
113
123
114
124
### -Depth
115
125
116
-
Determines the number of subdirectory levels that are included in the recursion. Default value is 3.
126
+
Specifies the maximum depth of the folder traversal. The default value is 3, limiting the hierarchy to three levels. Use this parameter to control the depth for performance or readability when exploring large directory structures.
Limits output to directories only, excluding files. When specified, the cmdlet displays only`TreeDirectory` objects, omitting `TreeFile` objects, for a focused view of folder hierarchies.
Specifies an array of one or more string patterns to be matched as the cmdlet gets child items.
149
-
Any matching item is excluded from the output.
150
-
Wildcard characters are accepted.
151
-
152
-
Excluded items do not add to the recursive folders size.
158
+
Specifies an array of one or more string patterns to exclude items from the output as the cmdlet traverses the folder structure. Matching items are omitted from the results. [Wildcard characters](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_wildcards?view=powershell-7.5) are accepted.
153
159
154
160
> [!NOTE]
155
161
>
156
-
> - Patterns are evaluated using the object's `.Name` property.
157
-
> - The `-Include` and `-Exclude` parameters can be used together, however the exclusions are applied before the inclusions.
162
+
> - Patterns are evaluated against the `.Name` property of each item.
163
+
> - The `-Include` and `-Exclude` parameters can be used together, but exclusions are applied before inclusions.
Gets items that otherwise can't be accessed by the user, such as hidden or system files.
179
+
Allows the cmdlet to access items that would otherwise be inaccessible, such as hidden or system files and folders. When specified, hidden and system items are included in the output and contribute to recursive folder sizes calculated by [`-RecursiveSize`](#-recursivesize).
Specifies an array of one or more string patterns to be matched as the cmdlet gets child items.
190
-
Any matching item is included in the output.
191
-
Wildcard characters are accepted.
195
+
Specifies an array of one or more string patterns to include only matching items in the output as the cmdlet traverses the folder structure. Matching items are included, while others are omitted. [Wildcard characters](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_wildcards?view=powershell-7.5) are accepted.
192
196
193
197
> [!NOTE]
194
198
>
195
-
> - __This parameter works only on files.__
196
-
> - Patterns are evaluated using the object's `.Name` property.
197
-
> - The `-Include` and `-Exclude` parameters can be used together, however the exclusions are applied before the inclusions.
199
+
> - __This parameter works only on files, not directories.__
200
+
> - Patterns are evaluated against the `.Name` property of each item.
201
+
> - The `-Include` and `-Exclude` parameters can be used together, but exclusions are applied before inclusions.
Note that the value is used exactly as it's typed.
215
-
No characters are interpreted as wildcards.
217
+
Specifies the literal path to the folder to traverse, without interpreting wildcard characters. This parameter accepts an array of paths and can receive input from the pipeline by property name (using the `PSPath` alias). Use this for exact path matching, bypassing wildcard expansion.
Specifies a path to one or more locations. Wildcards are accepted.
232
-
The default location is the current directory (`$PWD`).
233
+
Specifies the path to one or more folders to traverse. Accepts an array of paths, which can include [wildcard characters](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_wildcards?view=powershell-7.5). The default location is the current directory (`$PWD`) if no path is provided.
Gets the items in the specified location and in all child items of the location.
249
+
Enables recursive traversal of all subfolders under the specified path. Use this switch to explore the complete folder hierarchy, but note that it may impact performance on large directories—consider ][`-Depth`](#-depth) for smaller subsets.
This switch enables the cmdlet to calculate the recursive size of folders in a hierarchy.
265
-
By default, the cmdlet only displays the size of folders based on the sum of the file's Length in each directory.
266
-
It's important to note that this is a more expensive operation, in order to calculate the recursive size, all items in the hierarchy needs to be traversed.
265
+
Enables the cmdlet to calculate the recursive size of folders across the entire hierarchy, summing the sizes of all files within each directory and its subdirectories. By default, the cmdlet calculates only the size of files directly within each directory. This is a more resource-intensive operation, as it requires traversing all items in the hierarchy.
267
266
268
-
By default, the size of hidden and system items is not added to the recursive size, for this you must use the `-Force` parameter.
269
-
Excluded items with the `-Exclude` parameter do not add to the recursive size.
267
+
By default, hidden and system items are excluded from recursive size calculations unless [`-Force`](#-force) is specified. Items excluded by the [`-Exclude`](#-exclude) parameter do not contribute to recursive sizes.
270
268
271
269
```yaml
272
270
Type: SwitchParameter
@@ -286,12 +284,31 @@ This cmdlet supports the common parameters. For more information, see [about_Com
286
284
287
285
## INPUTS
288
286
289
-
### String
287
+
### System.String
290
288
291
-
You can pipe a string that contains a path to this cmdlet. Output from `Get-Item` and `Get-ChildItem` can be piped to this cmdlet.
289
+
You can pipe a strings containing file system paths to this cmdlet.
290
+
Output from cmdlets that return `System.IO.FileSystemInfo` objects (e.g., `Get-Item`, `Get-ChildItem`) can be piped to this cmdlet, with pipeline input bound to `-LiteralPath` if the objects have a `PSPath` property.
292
291
293
292
## OUTPUTS
294
293
295
-
### TreeDirectory
294
+
### PSTree.TreeDirectory
295
+
296
+
Returns objects of type `TreeDirectory` representing directories in a hierarchical structure, with `TreeFile` objects included as children. Each `TreeDirectory` object includes properties such as `Name`, `FullName`, `Size`, and `Depth`, reflecting the file system organization and enabling size-based analysis. This prioritizes directories as the primary output type for tree navigation, with files nested within for comprehensive exploration.
297
+
298
+
### PSTree.TreeFile
299
+
300
+
Returns objects of type `TreeFile` representing files within directories, included in the output unless the `-Directory` parameter is specified. Each object includes properties such as `Name`, `FullName`, `Size`, and `Depth`, allowing detailed file analysis within the hierarchical structure. These objects are nested under `TreeDirectory` objects, supporting disk usage tracking and file system navigation.
301
+
302
+
## NOTES
303
+
304
+
This cmdlet requires PowerShell 5.1 or later and supports cross-platform file system exploration on Windows, Linux, and macOS. It may require elevated permissions for certain system folders. Use `-Recurse` or `-RecursiveSize` cautiously with large directories to avoid performance issues, and refer to the [`about_TreeStyle`](./about_TreeStyle.md) help topic for customizing the output format. For Windows-specific registry navigation, see the [`Get-PSTreeRegistry`](./Get-PSTreeRegistry.md) cmdlet
Copy file name to clipboardExpand all lines: docs/en-US/Get-PSTreeRegistry.md
+7-8Lines changed: 7 additions & 8 deletions
Original file line number
Diff line number
Diff line change
@@ -100,7 +100,7 @@ This example uses the registry provider path to explore all keys under `HKEY_USE
100
100
101
101
### -Depth
102
102
103
-
Specifies the maximum depth of the registry traversal. Default value is 3.
103
+
Specifies the maximum depth of the registry traversal. Default value is 3. Use this parameter to control the depth for performance or readability when exploring large registry hives.
Specifies the literal registry paths to traverse, without wildcard expansion. This parameter is mandatory and accepts input from the pipeline by property name (using the `PSPath` alias). Use this for exact path matching, bypassing wildcard interpretation.
135
+
Specifies the literal registry paths to traverse, without wildcard expansion. This parameter accepts input from the pipeline by property name (using the `PSPath` alias). Use this for exact path matching, bypassing wildcard interpretation.
136
136
137
137
> [!TIP]
138
138
> For registry base keys not mapped as PowerShell drives (e.g., `HKCU:\` and `HKLM:\`), you can use the provider path format by prefixing the path with `Registry::`. For example, to traverse all keys under `HKEY_USERS` exactly as specified, use: `Get-PSTreeRegistry -LiteralPath Registry::HKEY_USERS`.
Specifies the registry paths to traverse. Accepts one or more registry paths (e.g., `HKLM:\Software`, `HKCU:\Software`), which can include wildcards. This parameter is mandatory and can accept input from the pipeline. Paths are resolved using PowerShell's registry provider.
154
+
Specifies the registry paths to traverse. Accepts one or more registry paths (e.g., `HKLM:\Software`, `HKCU:\Software`), which can include [wildcard characters](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_wildcards?view=powershell-7.5). This parameter can accept input from the pipeline. Paths are resolved using [PowerShell's registry provider](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_registry_provider?view=powershell-7.5).
155
155
156
156
> [!TIP]
157
157
> For registry base keys not mapped as PowerShell drives (e.g., `HKCU:\` and `HKLM:\`), you can use the provider path format by prefixing the path with `Registry::`. For example, to traverse each key under `HKEY_USERS`, use: `Get-PSTreeRegistry -Path Registry::HKEY_USERS\*`.
@@ -163,7 +163,7 @@ Aliases:
163
163
164
164
Required: False
165
165
Position: 0
166
-
Default value: None
166
+
Default value: $PWD
167
167
Accept pipeline input: True (ByValue)
168
168
Accept wildcard characters: True
169
169
```
@@ -193,7 +193,7 @@ This cmdlet supports the common parameters. For more information, see [about_Com
193
193
### System.String
194
194
195
195
You can pipe strings containing registry paths to this cmdlet.
196
-
Output from `Get-Item` and `Get-ChildItem` can be piped to this cmdlet.
196
+
Output from cmdlets that return `Microsoft.Win32.RegistryKey` objects (e.g., `Get-Item`, `Get-ChildItem`) can be piped to this cmdlet, with pipeline input bound to `-LiteralPath` if the objects have a `PSPath` property.
197
197
198
198
## OUTPUTS
199
199
@@ -207,15 +207,14 @@ Returns objects of type `TreeRegistryValue` representing registry values associa
207
207
208
208
## NOTES
209
209
210
-
This cmdlet is Windows-only and requires PowerShell 5.1 or later. It may require elevated permissions for certain registry hives.
210
+
This cmdlet is Windows-only and requires PowerShell 5.1 or later. It may require elevated permissions for certain registry hives. For file system navigation, see the [`Get-PSTree`](./Get-PSTree.md) cmdlet.
0 commit comments