Release 1.114.2025

Author: genXdev

Functions/GenXdev.FileSystem/AssurePester.ps1

@@ -1,14 +1,17 @@
 ################################################################################
 <#
 .SYNOPSIS
-Ensures that Pester testing framework is installed and available.
+Ensures Pester testing framework is available for use.
 
 .DESCRIPTION
-This function checks if Pester module is installed. If not found, it attempts to
-install it from the PowerShell Gallery and imports it into the current session.
+This function verifies if the Pester module is installed in the current
+PowerShell environment. If not found, it automatically installs it from the
+PowerShell Gallery and imports it into the current session. This ensures that
+Pester testing capabilities are available when needed.
 
 .EXAMPLE
 AssurePester
+# This ensures Pester is installed and ready for use
 #>
 function AssurePester {
 
@@ -17,36 +20,43 @@ function AssurePester {
 
     begin {
 
+        # inform user that we're checking pester installation
         Write-Verbose "Checking for Pester module installation..."
     }
 
     process {
 
-        # attempt to import pester module without showing errors
+        # attempt silent import of pester to check if it's available
         Import-Module -Name Pester -ErrorAction SilentlyContinue
 
-        # check if pester module is available
+        # verify if pester module is now loaded in the current session
         if (-not (Get-Module -Name Pester -ErrorAction SilentlyContinue)) {
 
+            # notify about installation attempt through verbose and regular output
             Write-Verbose "Pester module not found, attempting installation..."
             Write-Host "Pester not found. Installing Pester..."
 
             try {
-                # install pester from powershell gallery
-                $null = Install-Module -Name Pester -Force -SkipPublisherCheck
+                # install pester module from the powershell gallery
+                $null = Install-Module -Name Pester `
+                    -Force `
+                    -SkipPublisherCheck
 
-                # import the newly installed module
+                # load the newly installed pester module
                 $null = Import-Module -Name Pester -Force
 
+                # confirm successful installation
                 Write-Host "Pester installed successfully."
                 Write-Verbose "Pester module installation and import completed."
             }
             catch {
+                # report any installation failures
                 Write-Error "Failed to install Pester. Error: $PSItem"
                 Write-Verbose "Pester installation failed with error."
             }
         }
         else {
+            # inform that pester is already available
             Write-Verbose "Pester module already installed and imported."
         }
     }

Functions/GenXdev.FileSystem/Find-DuplicateFiles.ps1

@@ -1,27 +1,29 @@
 ################################################################################
 <#
 .SYNOPSIS
-Find duplicate files by name and properties across specified directories.
+Find duplicate files across multiple directories based on configurable criteria.
 
 .DESCRIPTION
-Takes an array of directory paths, searches each path recursively for files,
-then groups files by name and optionally by size and modified date. Returns
-groups containing two or more duplicate files.
+Recursively searches specified directories for duplicate files. Files are
+considered duplicates if they share the same name and optionally match on size
+and modification date. Returns groups of duplicate files for further processing.
 
 .PARAMETER Paths
-One or more directory paths to search for duplicate files.
+Array of directory paths to recursively search for duplicate files. Accepts
+pipeline input and wildcard paths.
 
 .PARAMETER DontCompareSize
-Skip file size comparison when determining duplicates.
+When specified, file size is not used as a comparison criterion, only names
+are matched.
 
 .PARAMETER DontCompareModifiedDate
-Skip last modified date comparison when determining duplicates.
+When specified, file modification dates are not used as a comparison criterion.
 
 .EXAMPLE
-Find-DuplicateFiles -Paths "C:\Folder1","D:\Folder2" -DontCompareSize
+Find-DuplicateFiles -Paths "C:\Photos","D:\Backup\Photos"
 
 .EXAMPLE
-Get-Item "C:\Folder1","D:\Folder2" | Find-DuplicateFiles
+"C:\Photos","D:\Backup\Photos" | fdf -DontCompareSize
 #>
 function Find-DuplicateFiles {
 
@@ -58,69 +60,68 @@ function Find-DuplicateFiles {
 
     begin {
 
-        # normalize all input paths to full paths
+        # convert all input paths to full filesystem paths
         $normalizedPaths = @()
         $Paths | ForEach-Object {
             $normalizedPaths += (Expand-Path $_)
         }
 
-        # helper function to generate unique key for file comparison
+        # internal helper function to generate unique comparison key for each file
         function Get-FileKey([System.IO.FileInfo]$file) {
 
-            # start with filename as base key
+            # start with filename as the base identifier
             $key = $file.Name
 
-            # add size to key if size comparison is enabled
+            # include file size in comparison key if enabled
             if (-not $DontCompareSize) {
                 $key += "|$($file.Length)"
             }
 
-            # add modified date to key if date comparison is enabled
+            # include modification date in comparison key if enabled
             if (-not $DontCompareModifiedDate) {
                 $key += "|$($file.LastWriteTimeUtc.ToString('o'))"
             }
 
             return $key
         }
 
-        # initialize generic list for better performance with large collections
+        # initialize high-performance collection for gathering files
         $allFiles = [System.Collections.Generic.List[System.IO.FileInfo]]::new()
     }
 
     process {
 
-        # process each normalized path
         foreach ($path in $normalizedPaths) {
 
-            # verify directory exists before processing
+            # verify directory exists before attempting to process
             if ([System.IO.Directory]::Exists($path)) {
 
-                Write-Verbose "Scanning directory: $path"
+                Write-Verbose "Scanning directory for duplicates: $path"
 
-                # get all files using direct .NET IO methods for performance
+                # use direct .NET IO for faster recursive file enumeration
                 [System.IO.Directory]::GetFiles($path, "*.*",
                     [System.IO.SearchOption]::AllDirectories) |
                 ForEach-Object {
                     $null = $allFiles.Add([System.IO.FileInfo]::new($_))
                 }
             }
             else {
-                Write-Warning "Directory not found: $path"
+                Write-Warning "Skipping non-existent directory: $path"
             }
         }
     }
 
     end {
 
-        # group files by composite key and return groups with duplicates
+        # group files by composite key and return only groups with duplicates
         $allFiles |
         Group-Object -Property { Get-FileKey $_ } |
         Where-Object { $_.Count -gt 1 } |
         ForEach-Object {
-            # create custom object for each group of duplicates
+            # create result object for each duplicate group
             [PSCustomObject]@{
                 FileName = $_.Group[0].Name
-                Files = $_.Group
+                Files    = $_.Group
             }
         }
     }

Functions/GenXdev.FileSystem/Find-Item.ps1

@@ -1,34 +1,37 @@
 ################################################################################
 <#
 .SYNOPSIS
-Searches for file- or directory- names with optionally filtering regex content matching
+Searches for files or directories with optional content filtering.
 
 .DESCRIPTION
-Searches for file- or directory- names, optionally performs a regular expression
-match within the content of each matched file.
+Performs recursive file and directory searches with support for:
+- File/directory name patterns
+- Content matching using regular expressions
+- Searching across all drives
+- Directory-only searches
+- Object pipeline output
 
 .PARAMETER SearchMask
-Specify the file name or pattern to search for. Default is "*".
+The file/directory name pattern to search for. Supports wildcards.
+Defaults to "*" if not specified.
 
 .PARAMETER Pattern
-Regular expression pattern to search within the content of files to match against. Default is ".*".
+Regular expression to match against file contents.
+Only applies when searching files, not directories.
 
 .PARAMETER AllDrives
-Search all drives.
+Search across all available drives instead of just the current path.
 
 .PARAMETER Directory
-Search for directories only.
+Search for directories only, ignoring files.
 
 .PARAMETER PassThru
-Pass through the objects to the pipeline.
+Output matched items as objects instead of formatted strings.
 
 .EXAMPLE
-# Find all files with the .txt extension in the current directory and its subdirectories
+# Search for all .txt files in current directory and subdirectories
 Find-Item -SearchMask "*.txt"
 
-# or in short
-l *.txt
-
 .EXAMPLE
 # Find all files with that have the word "translation" in their name
 Find-Item -SearchMask "*translation*"
@@ -113,7 +116,7 @@ function Find-Item {
             Mandatory = $false,
             Position = 1,
             ParameterSetName = 'WithPattern',
-            HelpMessage = "Regular expression pattern to search within the content of files to match against"
+            HelpMessage = "Regular expression pattern to search within file contents"
         )]
         [Alias("mc", "matchcontent")]
         [PSDefaultValue(Value = ".*")]
@@ -144,23 +147,36 @@ function Find-Item {
 
     begin {
 
+        Write-Verbose "Starting Find-Item with SearchMask: $SearchMask"
+
+        # normalize and validate the search mask
         $SearchMask = $SearchMask.Trim()
         if ($SearchMask -eq [string]::Empty) {
-
             $SearchMask = ".\*"
         }
-        $SearchMask = $SearchMask.Trim().Replace("\", [IO.Path]::DirectorySeparatorChar).Replace("/", [IO.Path]::DirectorySeparatorChar).Replace([IO.Path]::DirectorySeparatorChar + [IO.Path]::DirectorySeparatorChar, [IO.Path]::DirectorySeparatorChar)
 
-        if ($SearchMask.EndsWith([IO.Path]::DirectorySeparatorChar)) {
+        # normalize path separators
+        $SearchMask = $SearchMask.Trim().Replace("\", [IO.Path]::DirectorySeparatorChar).`
+            Replace("/", [IO.Path]::DirectorySeparatorChar).`
+            Replace([IO.Path]::DirectorySeparatorChar + [IO.Path]::DirectorySeparatorChar,
+            [IO.Path]::DirectorySeparatorChar)
 
+        # ensure directory paths end with wildcard
+        if ($SearchMask.EndsWith([IO.Path]::DirectorySeparatorChar)) {
             $SearchMask += "*"
         }
 
-        # expand search mask path to full path
+        Write-Verbose "Normalized SearchMask: $SearchMask"
+
+        # convert to full path
         $SearchMask = Expand-Path $SearchMask
+        Write-Verbose "Expanded SearchMask: $SearchMask"
 
-        # get current directory for relative path handling
+        # store current location for relative path handling
         $location = Get-Location | ForEach-Object Path
+    }
+
+    process {
 
         # helper function to search file content
         function Search-FileContent {
@@ -172,11 +188,6 @@ function Find-Item {
             return Select-String -Path $FilePath -Pattern $Pattern
         }
 
-        $SearchMask = Expand-Path $SearchMask
-    }
-
-    process {
-
         # output blank line unless passing through objects
         if (-not $PassThru) {
             "" | Out-Host
@@ -186,14 +197,17 @@ function Find-Item {
         if ((-not $Directory) -and ($Pattern -ne ".*") -and
             (-not [string]::IsNullOrWhiteSpace($Pattern))) {
 
-            # searching all drives
+            Write-Verbose "Searching files with content pattern: $Pattern"
+
+            # search all drives
             if ($AllDrives) {
+                Write-Verbose "Searching across all drives"
 
-                # get all drives and process in parallel
+                # process drives in parallel
                 Get-PSDrive -ErrorAction SilentlyContinue |
                 ForEach-Object -ThrottleLimit 8 -Parallel {
 
-                    # extract filename from search mask
+                    # extract filename part
                     $file = [IO.Path]::GetFileName($SearchMask)
                     $filter = [string]::IsNullOrEmpty($file) ? "*" : $file
 
@@ -208,7 +222,7 @@ function Find-Item {
                         Where-Object -Property Name -Like $filter |
                         ForEach-Object {
 
-                            # check file content for pattern
+                            # check file content
                             if (Search-FileContent -FilePath $PSItem.FullName `
                                     -Pattern $Pattern) {
 
@@ -233,8 +247,9 @@ function Find-Item {
                 return
             }
 
-            # regular content search in current location
-            Get-ChildItem $SearchMask -File -Recurse | ForEach-Object {
+            # regular content search
+            Get-ChildItem $SearchMask -File -Recurse |
+            ForEach-Object {
                 if (($Pattern -eq ".*") -or
                     (Search-FileContent -FilePath $PSItem.FullName -Pattern $Pattern)) {
 
@@ -255,8 +270,10 @@ function Find-Item {
             return
         }
 
-        # searching all drives without content pattern
+        # search all drives without content
         if ($AllDrives) {
+            Write-Verbose "Searching all drives for matching items"
+
             Get-PSDrive -ErrorAction SilentlyContinue |
             ForEach-Object -ThrottleLimit 8 -Parallel {
                 try {
@@ -282,7 +299,9 @@ function Find-Item {
             return
         }
 
-        # regular file/directory search without content pattern
+        # regular file/directory search
+        Write-Verbose "Performing regular file/directory search"
+
         $dir = [IO.Path]::GetDirectoryName($SearchMask)
         if ([string]::IsNullOrEmpty($dir)) {
             $dir = ".$([IO.Path]::DirectorySeparatorChar)"
@@ -321,3 +340,4 @@ function Find-Item {
     end {
     }
 }
+################################################################################