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.0'
+ModuleVersion = '1.5.0'
 
 # Supported PSEditions
 # CompatiblePSEditions = @()
@@ -69,7 +69,7 @@ PowerShellVersion = '5.1'
 # NestedModules = @()
 
 # Functions to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no functions to export.
-FunctionsToExport = 'Set-GiteaConfiguration', 'Get-GiteaConfiguration', 'Get-GiteaFileContent', 'Invoke-GiteaFileDownload', 'Get-GiteaChildItem'
+FunctionsToExport = 'Set-GiteaConfiguration', 'Get-GiteaConfiguration', 'Get-GiteaFileContent', 'Invoke-GiteaFileDownload', 'Get-GiteaChildItem', 'Get-GiteaReleases'
 
 # Cmdlets to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no cmdlets to export.
 CmdletsToExport = '*'

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('/')
+        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,18 +521,36 @@ 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)) {
+            # 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 {
             # Create the directory structure if it doesn't exist
@@ -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
                 }
@@ -1029,4 +1071,4 @@ function Get-GiteaReleases {
     }
 }
 
-Export-ModuleMember -Function Set-GiteaConfiguration, Get-GiteaConfiguration, Get-GiteaFileContent, Invoke-GiteaFileDownload, Get-GiteaChildItem, Get-GiteaLFSFile, Get-GiteaReleases
+# Export-ModuleMember -Function Set-GiteaConfiguration, Get-GiteaConfiguration, Get-GiteaFileContent, Invoke-GiteaFileDownload, Get-GiteaChildItem, Get-GiteaReleases