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.2'
+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
                 }
             }
@@ -337,6 +337,9 @@ Function Invoke-GiteaFileDownload {
     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 {
@@ -410,8 +420,12 @@ Function Invoke-GiteaFileDownload {
     }
 
     process {
-        Write-Verbose "Type: $type"
+        # If type is not provided, check for any hints for cases such as LFS where a type can be inferred and special handling is needed
+        If($downloadURL -match "/api/v1/repos/[^/]+/[^/]+/media/") {
+            $type = "lfs"
+        }
 
+        Write-Verbose "Type: $type"
         # Handle the type parameter
 
         # Skip directories and provide a verbose message
@@ -420,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
@@ -434,7 +448,7 @@ Function Invoke-GiteaFileDownload {
             return [PSCustomObject]@{
                 SourceURL = $downloadURL
                 Type = $type
-                Success = $false
+                Result = 'Failure'
                 Error = $errorMsg
                 Timestamp = Get-Date
                 FileSize = $null
@@ -447,10 +461,20 @@ Function Invoke-GiteaFileDownload {
         # Separate the URL into its components: Gitea URL, Repo Owner, Repo Name, branch, file path, and file name
         $uri = New-Object System.Uri($downloadURL)
         $pathSegments = $uri.AbsolutePath.Trim('/').Split('/')
-        # Everything after the branch + 1 segment is considered the file path with the last segment being the file name
-        $branchIndex = [Array]::IndexOf($pathSegments, "branch") + 2
-        $DownloadFilePath = $pathSegments[$branchIndex..($pathSegments.Length - 2)] -join '/'
-        $DownloadFileName = $pathSegments[-1]
+        If($type -eq "lfs") {
+            # Everything after the media segment is considered the file path with the last segment being the file name
+            $branchIndex = [Array]::IndexOf($pathSegments, "media") + 1
+            $DownloadFilePath = $pathSegments[$branchIndex..($pathSegments.Length - 2)] -join '/'
+            $DownloadFileName = $pathSegments[-1]
+        }
+        Else {
+            # Everything after the branch + 1 segment is considered the file path with the last segment being the file name
+            $branchIndex = [Array]::IndexOf($pathSegments, "branch") + 2
+            $DownloadFilePath = $pathSegments[$branchIndex..($pathSegments.Length - 2)] -join '/'
+            # Replace any URL encoded characters in the file name
+            $DownloadFilePath = [System.Uri]::UnescapeDataString($DownloadFilePath)
+            $DownloadFileName = $pathSegments[-1]
+        }
                 
         if ($PreserveRelativePath -and $outputPath) {
             # If PreserveRelativePath is used, set up the directory structure
@@ -497,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 {
@@ -532,7 +574,7 @@ Function Invoke-GiteaFileDownload {
                 $result.FileSize = $fileInfo.Length
             }
             
-            $result.Success = $true
+            $result.Result = 'Success'
             return $result
         }
         catch {
@@ -732,7 +774,7 @@ Function Get-GiteaChildItem {
                             $item.size = [long]$matches[1]
                         }
                         # Set the download URL to the media endpoint for LFS files to download the actual file
-                        $item.download_url = "$giteaURL/api/v1/repos/$repoOwner/$repoName/media/$($item.path)"
+                        $item.download_url = "$giteaURL/api/v1/repos/$repoOwner/$repoName/media/$($item.path)?ref=$branch"
                     }
 
                     $itemObj = [PSCustomObject]@{
@@ -742,7 +784,7 @@ Function Get-GiteaChildItem {
                         size = $item.size
                         sha = $item.sha
                         downloadURL = $item.download_url
-                        Success = $true
+                        Result = 'Success'
                         Error = $null
                         Level = 0
                     }
@@ -825,7 +867,7 @@ Function Get-GiteaChildItem {
                                     size = $subItem.size
                                     sha = $subItem.sha
                                     downloadURL = $subItem.download_url
-                                    Success = $true
+                                    Result = 'Success'
                                     Error = $null
                                     Level = $currentLevel
                                 }
@@ -872,7 +914,7 @@ Function Get-GiteaChildItem {
                     size = $null
                     sha = $null
                     downloadURL = $null
-                    Success = $false
+                    Result = 'Failure'
                     Error = $_.Exception.Message
                     Level = 0
                 }