Bump module version to 1.5.0 and update Invoke-GiteaFileDownload and Get-GiteaChildItem functions to use 'Result' instead of 'Success' for status reporting, and add OverwriteByHash parameter for conditional file overwriting.

PS-GiteaUtilities/PS-GiteaUtilities.psd1

@@ -12,7 +12,7 @@
 RootModule = 'PS-GiteaUtilities.psm1'
 
 # Version number of this module.
-ModuleVersion = '1.4.5'
+ModuleVersion = '1.5.0'
 
 # Supported PSEditions
 # CompatiblePSEditions = @()

PS-GiteaUtilities/PS-GiteaUtilities.psm1

@@ -207,7 +207,7 @@ Function Get-GiteaFileContent {
                     Content = $content
                     Size = $fileContent.size
                     SHA = $fileContent.sha
-                    Success = $true
+                    Result = 'Success'
                     Error = $null
                 }
             }
@@ -218,7 +218,7 @@ Function Get-GiteaFileContent {
                     Content = $null
                     Size = $null
                     SHA = $null
-                    Success = $false
+                    Result = 'Failure'
                     Error = $_.Exception.Message
                 }
             }
@@ -336,6 +336,9 @@ Function Invoke-GiteaFileDownload {
     If used without specifying an outputPath, creates the directory structure in the current location.
     If used with outputPath, treats the outputPath as the base directory to append the relative path to.
     Cannot be used with outputName.
+
+    .PARAMETER OverwriteByHash
+    A switch parameter to overwrite the file if it exists based on its hash.
     
     .PARAMETER force
     A switch parameter to force overwriting of an existing file at the output path.
@@ -344,6 +347,10 @@ Function Invoke-GiteaFileDownload {
     The type of the item to download (file, dir, lfs). This parameter is typically used with pipeline input from Get-GiteaChildItem.
     Directories will be skipped with a verbose message.
 
+    .PARAMETER sha
+    The SHA of the file to download. This parameter is typically used with pipeline input from Get-GiteaChildItem.
+    Can be combined with OverwriteByHash to overwrite an existing file if the hashes do not match.
+
     .EXAMPLE
     # Example 1: Download a file to the current directory
     Invoke-GiteaFileDownload -downloadURL "https://gitea.example.com/api/v1/repos/owner/repo/raw/path/to/file.txt" -token "your_token"
@@ -375,9 +382,12 @@ Function Invoke-GiteaFileDownload {
         [Parameter(ValueFromPipelineByPropertyName)]
         [string]$outputName,
         [switch]$PreserveRelativePath,
+        [switch]$OverwriteByHash,
         [switch]$force,
         [Parameter(ValueFromPipelineByPropertyName)]
-        [string]$type
+        [string]$type,
+        [Parameter(ValueFromPipelineByPropertyName)]
+        [string]$sha
     )
 
     begin {
@@ -424,7 +434,7 @@ Function Invoke-GiteaFileDownload {
             return [PSCustomObject]@{
                 SourceURL = $downloadURL
                 Type = $type
-                Success = $true
+                Result = 'Success'
                 Error = "Skipped - item is a directory"
                 Timestamp = Get-Date
                 FileSize = $null
@@ -438,7 +448,7 @@ Function Invoke-GiteaFileDownload {
             return [PSCustomObject]@{
                 SourceURL = $downloadURL
                 Type = $type
-                Success = $false
+                Result = 'Failure'
                 Error = $errorMsg
                 Timestamp = Get-Date
                 FileSize = $null
@@ -511,17 +521,35 @@ Function Invoke-GiteaFileDownload {
             Path = $fileOutputPath
             SourceURL = $downloadURL
             Type = "file"
-            Success = $false
+            Result = 'Failure'
             Error = $null
             Timestamp = Get-Date
             FileSize = $null
         }
 
         if((Test-Path -Path $fileOutputPath -PathType Leaf) -and (-not $force)) {
-            $errorMsg = "The file '$fileOutputPath' already exists. Use the -Force switch to overwrite the file."
-            Write-Error $errorMsg
-            $result.Error = $errorMsg
-            return $result
+            # Check if OverwriteByHash is set
+            if ($OverwriteByHash) {
+                Write-Verbose "OverwriteByHash is set; checking file hash for existing file: $fileOutputPath"
+                $existingFileHash = (Get-FileHash -Path $fileOutputPath -Algorithm SHA256).Hash
+                $downloadFileHash = $sha
+                
+                if ($existingFileHash -eq $downloadFileHash) {
+                    Write-Host "The file '$fileOutputPath' already exists and hashes match. Skipping download."
+                    $result.Result = 'Skipped'
+                    return $result
+                }
+                else {
+                    Write-Host "The file '$fileOutputPath' already exists but hashes do not match and OverwriteByHash is set; overwriting file."
+
+                }
+            }
+            else {
+                $errorMsg = "The file '$fileOutputPath' already exists. Use the -Force switch to overwrite the file."
+                Write-Error $errorMsg
+                $result.Error = $errorMsg
+                return $result
+            }
         }
 
         try {
@@ -546,7 +574,7 @@ Function Invoke-GiteaFileDownload {
                 $result.FileSize = $fileInfo.Length
             }
             
-            $result.Success = $true
+            $result.Result = 'Success'
             return $result
         }
         catch {
@@ -756,7 +784,7 @@ Function Get-GiteaChildItem {
                         size = $item.size
                         sha = $item.sha
                         downloadURL = $item.download_url
-                        Success = $true
+                        Result = 'Success'
                         Error = $null
                         Level = 0
                     }
@@ -839,7 +867,7 @@ Function Get-GiteaChildItem {
                                     size = $subItem.size
                                     sha = $subItem.sha
                                     downloadURL = $subItem.download_url
-                                    Success = $true
+                                    Result = 'Success'
                                     Error = $null
                                     Level = $currentLevel
                                 }
@@ -886,7 +914,7 @@ Function Get-GiteaChildItem {
                     size = $null
                     sha = $null
                     downloadURL = $null
-                    Success = $false
+                    Result = 'Failure'
                     Error = $_.Exception.Message
                     Level = 0
                 }