Merge pull request #39 from santisq/38-improve-how-include-works

Improves how `-Include` works

Author: santisq

CHANGELOG.md

@@ -1,5 +1,79 @@
 # CHANGELOG
 
+- __01/19/2025__
+  - Big code refactoring, this update improves readability and simplicity.
+  - Updates to `-Include` and `-Exclude` parameters, with this update the patterns are evaluated using the
+  object's `.Name` property instead of `.FullName`.
+  - In addition to the above, this update improves how the cmdlet displays trees when `-Include` is used.
+  Before, the cmdlet would display trees where no file was matched by the include patterns. Now, only trees having files matched by the include patterns are displayed.
+
+    ```powershell
+    # PSTree v2.2.0
+    PS ..\pwsh> Get-PSTree ..\PSTree -Include *.ps1, *.cs -Exclude *tools, *output
+
+      Source: C:\User\PSTree
+
+    Mode            Length Hierarchy
+    ----            ------ ---------
+    d----         29.57 KB PSTree
+    -a---          1.34 KB ├── build.ps1
+    d----          0.00  B ├── .github
+    d----          4.10 KB │   └── workflows
+    d----          4.11 KB ├── .vscode
+    d----        229.32 KB ├── assets
+    d----          0.00  B ├── docs
+    d----         12.55 KB │   └── en-US
+    d----         13.63 KB ├── module
+    d----          0.00  B ├── src
+    d----         11.50 KB │   └── PSTree
+    -a---          1.06 KB │       ├── Cache.cs
+    -a---          2.65 KB │       ├── CommandWithPathBase.cs
+    -a---          2.98 KB │       ├── PSTreeDirectory.cs
+    -a---          1.42 KB │       ├── PSTreeFile.cs
+    -a---          1.69 KB │       ├── PSTreeFileSystemInfo_T.cs
+    -a---        524.00  B │       ├── PSTreeFileSystemInfo.cs
+    -a---        404.00  B │       ├── TreeComparer.cs
+    d----          0.00  B │       ├── bin
+    d----          6.54 KB │       ├── Commands
+    d----          3.63 KB │       ├── Extensions
+    d----          1.14 KB │       ├── Internal
+    d----         16.83 KB │       ├── obj
+    d----          9.28 KB │       └── Style
+    d----         17.87 KB └── tests
+    -a---        765.00  B     ├── FormattingInternals.tests.ps1
+    -a---          6.15 KB     ├── GetPSTreeCommand.tests.ps1
+    -a---          1.77 KB     ├── PSTreeDirectory.tests.ps1
+    -a---        920.00  B     ├── PSTreeFile.tests.ps1
+    -a---          2.63 KB     ├── PSTreeFileSystemInfo_T.tests.ps1
+    -a---          4.90 KB     └── TreeStyle.tests.ps1
+
+    # PSTree v2.2.1
+    PS ..\pwsh> Get-PSTree ..\PSTree -Include *.ps1, *.cs -Exclude tools, output
+
+      Source: C:\User\PSTree
+
+    Mode            Length Hierarchy
+    ----            ------ ---------
+    d----          1.34 KB PSTree
+    -a---          1.34 KB ├── build.ps1
+    d----          0.00  B ├── src
+    d----         10.70 KB │   └── PSTree
+    -a---          1.06 KB │       ├── Cache.cs
+    -a---          2.65 KB │       ├── CommandWithPathBase.cs
+    -a---          2.98 KB │       ├── PSTreeDirectory.cs
+    -a---          1.42 KB │       ├── PSTreeFile.cs
+    -a---          1.69 KB │       ├── PSTreeFileSystemInfo_T.cs
+    -a---        524.00  B │       ├── PSTreeFileSystemInfo.cs
+    -a---        404.00  B │       └── TreeComparer.cs
+    d----         17.10 KB └── tests
+    -a---        765.00  B     ├── FormattingInternals.tests.ps1
+    -a---          6.15 KB     ├── GetPSTreeCommand.tests.ps1
+    -a---          1.77 KB     ├── PSTreeDirectory.tests.ps1
+    -a---        920.00  B     ├── PSTreeFile.tests.ps1
+    -a---          2.63 KB     ├── PSTreeFileSystemInfo_T.tests.ps1
+    -a---          4.90 KB     └── TreeStyle.tests.ps1
+    ```
+
 - __09/12/2024__
   - Added `TreeStyle` type and `Get-PSTreeStyle` cmdlet for rendering output.
   - Added Pester tests for `TreeStyle`.
@@ -8,7 +82,7 @@
 - __09/03/2024__
   - Makes `Depth` property public for `PSTreeFileSystemInfo` instances.
   - Makes `GetParents()` method private, absolutely no reason to have it public.
-  - Added properties `ItemCount` and `TotalItemCount` to `PSTreeDirectory` instances, requested in [__Issue #34__][2].
+  - Added properties `ItemCount` and `TotalItemCount` to `PSTreeDirectory` instances, requested in [__Issue #34__][21].
 
     ```powershell
     PS ..\PSTree> pstree -Recurse -Force -Directory | Select-Object Hierarchy, Depth, ItemCount, TotalItemCount -First 15
@@ -275,4 +349,4 @@ d----     └── Format                     1.83 Kb
 [18]: https://github.com/jborean93/
 [19]: /docs/en-US/Get-PSTree.md
 [20]: https://www.powershellgallery.com/
-[2]: https://github.com/santisq/PSTree/issues/34
+[21]: https://github.com/santisq/PSTree/issues/34

README.md

@@ -48,7 +48,7 @@ Compatible with __Windows PowerShell v5.1__ and [__PowerShell 7+__](https://gith
 ```powershell
 PS ..\PSTree> Get-PSTree | Select-Object -First 20
 
-   Source: C:\path\to\PSTree
+   Source: C:\User\Documents\PSTree
 
 Mode            Length Hierarchy
 ----            ------ ---------
@@ -77,101 +77,93 @@ d----          0.00  B ├── src
 ### Exclude `tools` and `tests` folders
 
 ```powershell
-PS ..\PSTree> Get-PSTree -Exclude *tools, *tests  | Select-Object -First 20
+PS ..\PSTree> Get-PSTree -Exclude tools, tests  | Select-Object -First 20
 
-   Source: C:\path\to\PSTree
+   Source: C:\User\Documents\PSTree
 
 Mode            Length Hierarchy
 ----            ------ ---------
-d----         31.20 KB PSTree
--a---          4.64 KB ├── .gitignore
+d----         33.23 KB PSTree
+-a---          4.75 KB ├── .gitignore
 -a---        137.00  B ├── .markdownlint.json
--a---          2.16 KB ├── build.ps1
--a---          7.90 KB ├── CHANGELOG.md
+-a---          1.34 KB ├── build.ps1
+-a---         18.08 KB ├── CHANGELOG.md
 -a---          1.07 KB ├── LICENSE
--a---          8.10 KB ├── PSTree.build.ps1
--a---          5.96 KB ├── README.md
--a---          1.23 KB ├── ScriptAnalyzerSettings.psd1
-d----          0.00  B ├── src
-d----         10.30 KB │   └── PSTree
--a---        931.00  B │       ├── ExceptionHelpers.cs
--a---        439.00  B │       ├── PSTree.csproj
--a---          1.06 KB │       ├── PSTreeDirectory.cs
--a---          4.01 KB │       ├── PSTreeExtensions.cs
--a---        517.00  B │       ├── PSTreeFile.cs
--a---        399.00  B │       ├── PSTreeFileSystemInfo.cs
--a---          1.51 KB │       ├── PSTreeFileSystemInfo_T.cs
--a---        897.00  B │       ├── PSTreeHelper.cs
--a---        619.00  B │       ├── PSTreeIndexer.cs
+-a---          7.85 KB ├── README.md
+d----          0.00  B ├── .github
+d----          4.10 KB │   └── workflows
+-a---          4.10 KB │       └── ci.yml
+d----          4.11 KB ├── .vscode
+-a---        275.00  B │   ├── extensions.json
+-a---          1.39 KB │   ├── launch.json
+-a---          1.02 KB │   ├── settings.json
+-a---          1.43 KB │   └── tasks.json
+d----        229.32 KB ├── assets
+-a---         10.00 KB │   ├── EscapeSequence.png
+-a---         78.08 KB │   ├── Example.After.png
+-a---         73.89 KB │   ├── Example.Before.png
+-a---         67.35 KB │   └── TreeStyle.png
 ```
 
-### Include `.ps1` and `.cs` files and exclude some folders
+### Include `.ps1` and `.cs` files and exclude `tools` folder
 
 ```powershell
-PS ..\PSTree> Get-PStree -Include *.ps1, *.cs -Exclude *output, *tools, *docs, *module
+PS ..\PSTree> Get-PStree -Include *.ps1, *.cs -Exclude tools
 
-   Source: C:\path\to\PSTree
+   Source: C:\User\Documents\PSTree
 
 Mode            Length Hierarchy
 ----            ------ ---------
-d----         33.15 KB PSTree
--a---          2.35 KB ├── build.ps1
--a---          8.10 KB ├── PSTree.build.ps1
-d----         13.29 KB ├── tests
--a---        765.00  B │   ├── FormattingInternals.tests.ps1
--a---          5.89 KB │   ├── GetPSTreeCommand.tests.ps1
--a---          1.51 KB │   ├── PathExtensions.tests.ps1
--a---          1.38 KB │   ├── PSTreeDirectory.ps1
--a---        920.00  B │   ├── PSTreeFile.tests.ps1
--a---          2.09 KB │   └── PSTreeFileSystemInfo_T.tests.ps1
+d----          1.34 KB PSTree
+-a---          1.34 KB ├── build.ps1
 d----          0.00  B ├── src
-d----         12.15 KB │   └── PSTree
--a---        931.00  B │       ├── ExceptionHelpers.cs
--a---          4.09 KB │       ├── PathExtensions.cs
--a---        900.00  B │       ├── PSTreeCache.cs
--a---          1.06 KB │       ├── PSTreeDirectory.cs
--a---          1.66 KB │       ├── PSTreeExtensions.cs
--a---        517.00  B │       ├── PSTreeFile.cs
--a---        399.00  B │       ├── PSTreeFileSystemInfo.cs
--a---          1.61 KB │       ├── PSTreeFileSystemInfo_T.cs
--a---        626.00  B │       ├── PSTreeIndexer.cs
-d----         16.53 KB │       ├── obj
-d----          1.15 KB │       ├── Internal
-d----          6.43 KB │       ├── Commands
-d----          0.00  B │       └── bin
-d----          4.07 KB ├── .vscode
-d----          0.00  B └── .github
-d----          4.17 KB     └── workflows
+d----         10.70 KB │   └── PSTree
+-a---          1.06 KB │       ├── Cache.cs
+-a---          2.65 KB │       ├── CommandWithPathBase.cs
+-a---          2.98 KB │       ├── PSTreeDirectory.cs
+-a---          1.42 KB │       ├── PSTreeFile.cs
+-a---          1.69 KB │       ├── PSTreeFileSystemInfo_T.cs
+-a---        524.00  B │       ├── PSTreeFileSystemInfo.cs
+-a---        404.00  B │       └── TreeComparer.cs
+d----         17.10 KB └── tests
+-a---        765.00  B     ├── FormattingInternals.tests.ps1
+-a---          6.15 KB     ├── GetPSTreeCommand.tests.ps1
+-a---          1.77 KB     ├── PSTreeDirectory.tests.ps1
+-a---        920.00  B     ├── PSTreeFile.tests.ps1
+-a---          2.63 KB     ├── PSTreeFileSystemInfo_T.tests.ps1
+-a---          4.90 KB     └── TreeStyle.tests.ps1
 ```
 
 ### Get the `src` tree recursively displaying only folders
 
 ```powershell
 PS ..\PSTree> Get-PSTree .\src\ -Recurse -Directory
 
-   Source: C:\path\to\PSTree\src
+   Source: C:\User\Documents\PSTree\src
 
 Mode            Length Hierarchy
 ----            ------ ---------
 d----          0.00  B src
-d----         10.30 KB └── PSTree
-d----         16.53 KB     ├── obj
+d----         11.50 KB └── PSTree
+d----          0.00  B     ├── bin
 d----          0.00  B     │   └── Debug
-d----         88.02 KB     │       └── netstandard2.0
-d----          1.13 KB     ├── Internal
-d----          5.68 KB     ├── Commands
-d----          0.00  B     └── bin
-d----          0.00  B         └── Debug
-d----         33.31 KB             └── netstandard2.0
-d----         33.11 KB                 └── publish
+d----         56.49 KB     │       └── netstandard2.0
+d----         56.29 KB     │           └── publish
+d----          6.54 KB     ├── Commands
+d----          3.63 KB     ├── Extensions
+d----          1.14 KB     ├── Internal
+d----         16.83 KB     ├── obj
+d----          0.00  B     │   └── Debug
+d----        112.44 KB     │       └── netstandard2.0
+d----          9.28 KB     └── Style
 ```
 
 ### Display subdirectories only 2 levels deep
 
 ```powershell
 PS ..\PSTree> Get-PSTree .\src\ -Depth 2 -Directory
 
-   Source: C:\path\to\PSTree\src
+   Source: C:\User\Documents\PSTree\src
 
 Mode            Length Hierarchy
 ----            ------ ---------
@@ -188,7 +180,7 @@ d----          0.00  B     └── bin
 ```powershell
 PS ..\PSTree> Get-PSTree .\src\ -Depth 2 -Directory -RecursiveSize
 
-   Source: C:\path\to\PSTree\src
+   Source: C:\User\Documents\PSTree\src
 
 Mode            Length Hierarchy
 ----            ------ ---------
@@ -207,4 +199,4 @@ d----         66.42 KB     └── bin
 
 ## Contributing
 
-Contributions are more than welcome, if you wish to contribute, fork this repository and submit a pull request with the changes.
+Contributions are welcome, if you wish to contribute, fork this repository and submit a pull request with the changes.

docs/en-US/Get-PSTree.md

@@ -18,7 +18,7 @@ schema: 2.0.0
 ```powershell
 Get-PSTree
     [[-Path] <String[]>]
-    [-Depth <UInt32>]
+    [-Depth <Int32>]
     [-Recurse]
     [-Force]
     [-Directory]
@@ -33,7 +33,7 @@ Get-PSTree
 ```powershell
 Get-PSTree
     [-LiteralPath <String[]>]
-    [-Depth <UInt32>]
+    [-Depth <Int32>]
     [-Recurse]
     [-Force]
     [-Directory]
@@ -71,7 +71,8 @@ In this example `$HOME` is bound positionally to the `-Path` parameter.
 PS ..\PSTree> Get-PSTree -Depth 2 -Force
 ```
 
-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.
+> [!TIP]
+> 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.
 
 ### Example 4: Get the `C:\` drive tree 2 levels in depth displaying only folders calculating the recursive size
 
@@ -85,23 +86,28 @@ PS ..\PSTree> Get-PSTree C:\ -Depth 2 -RecursiveSize -Directory
 PS ..\PSTree> Get-PSTree $HOME -Recurse -Exclude *.jpg, *.png
 ```
 
-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 tested against the items `.FullName` property. Excluded items do not do not add to the folders size.
+> [!NOTE]
+>
+> - 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.
+> - __Excluded items do not do not add to the folders size.__
 
 ### Example 6: Get the tree of all folders in a location
 
 ```powershell
 PS ..\PSTree> Get-ChildItem -Directory | Get-PSTree
 ```
 
-`DirectoryInfo` and `FileInfo` instances having the `PSPath` Property are bound to the `-LiteralPath` parameter.
+> [!TIP]
+> Output from `Get-ChildItem` can be piped to this cmdlet. Pipeline input is bound to `-LiteralPath` parameter if the items have a `PSPath` property.
 
 ### Example 7: Get the tree of all folders in a location including only `*.ps1` files
 
 ```powershell
 PS ..\PSTree> Get-ChildItem -Directory | Get-PSTree -Include *.ps1
 ```
 
-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__.
+> [!IMPORTANT]
+> 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__.
 
 ## PARAMETERS
 
@@ -110,7 +116,7 @@ Similar to `-Exclude`, the `-Include` parameter supports [wildcard patterns](htt
 Determines the number of subdirectory levels that are included in the recursion.
 
 ```yaml
-Type: UInt32
+Type: Int32
 Parameter Sets: (All)
 Aliases:
 
@@ -147,8 +153,8 @@ Excluded items do not add to the recursive folders size.
 
 > [!NOTE]
 >
-> - Patterns are tested against the object's `.FullName` property.
-> - The `-Include` and `-Exclude` parameters can be used together and the inclusions are applied after the exclusions.
+> - Patterns are evaluated using the object's `.Name` property.
+> - The `-Include` and `-Exclude` parameters can be used together, however the exclusions are applied before the inclusions.
 
 ```yaml
 Type: String[]
@@ -186,9 +192,9 @@ Wildcard characters are accepted.
 
 > [!NOTE]
 >
-> - Patterns are tested against the object's `.FullName` property.
-> - This parameter focuses only on files, the inclusion patterns are only evaluated against `FileInfo` instances.
-> - The `-Include` and `-Exclude` parameters can be used together and the inclusions are applied after the exclusions.
+> - __This parameter works only on files.__
+> - Patterns are evaluated using the object's `.Name` property.
+> - The `-Include` and `-Exclude` parameters can be used together, however the exclusions are applied before the inclusions.
 
 ```yaml
 Type: String[]
@@ -222,7 +228,8 @@ Accept wildcard characters: False
 
 ### -Path
 
-Specifies a path to one or more locations. Wildcards are accepted. The default location is the current directory (`.`).
+Specifies a path to one or more locations. Wildcards are accepted.
+The default location is the current directory (`$PWD`).
 
 ```yaml
 Type: String[]
@@ -231,7 +238,7 @@ Aliases:
 
 Required: False
 Position: 0
-Default value: Current directory
+Default value: $PWD
 Accept pipeline input: True (ByValue)
 Accept wildcard characters: True
 ```

module/PSTree.psd1

@@ -11,7 +11,7 @@
     RootModule = 'bin/netstandard2.0/PSTree.dll'
 
     # Version number of this module.
-    ModuleVersion = '2.2.0'
+    ModuleVersion = '2.2.1'
 
     # Supported PSEditions
     # CompatiblePSEditions = @()