Revert module version to 1.5.3 in the module manifest

PS-GiteaUtilities/PS-GiteaUtilities.psd1

@@ -12,7 +12,7 @@
 RootModule = 'PS-GiteaUtilities.psm1'
 
 # Version number of this module.
-ModuleVersion = '1.4.3'
+ModuleVersion = '1.5.3'
 
 # 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,8 +434,8 @@ Function Invoke-GiteaFileDownload {
             return [PSCustomObject]@{
                 SourceURL = $downloadURL
                 Type = $type
-                Success = $true
-                Error = "Skipped - item is a directory"
+                Result = 'Skipped'
+                Error = $null
                 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,21 @@ 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
             $DownloadFileName = $pathSegments[-1]
+        }
+
+        $DownloadFilePath = [System.Uri]::UnescapeDataString($DownloadFilePath)
                 
         if ($PreserveRelativePath -and $outputPath) {
             # If PreserveRelativePath is used, set up the directory structure
@@ -497,18 +522,37 @@ Function Invoke-GiteaFileDownload {
             Path = $fileOutputPath
             SourceURL = $downloadURL
             Type = "file"
-            Success = $false
+            Result = $null
             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 {
+                $result.Result = 'Skipped'
                 $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,10 +576,11 @@ Function Invoke-GiteaFileDownload {
                 $result.FileSize = $fileInfo.Length
             }
             
-            $result.Success = $true
+            $result.Result = 'Success'
             return $result
         }
         catch {
+            $result.Result = 'Failure'
             $errorMsg = "Failed to download file from Gitea: $_"
             Write-Error $errorMsg
             $result.Error = $errorMsg
@@ -742,7 +787,7 @@ Function Get-GiteaChildItem {
                         size = $item.size
                         sha = $item.sha
                         downloadURL = $item.download_url
-                        Success = $true
+                        Result = 'Success'
                         Error = $null
                         Level = 0
                     }
@@ -825,7 +870,7 @@ Function Get-GiteaChildItem {
                                     size = $subItem.size
                                     sha = $subItem.sha
                                     downloadURL = $subItem.download_url
-                                    Success = $true
+                                    Result = 'Success'
                                     Error = $null
                                     Level = $currentLevel
                                 }
@@ -872,7 +917,7 @@ Function Get-GiteaChildItem {
                     size = $null
                     sha = $null
                     downloadURL = $null
-                    Success = $false
+                    Result = 'Failure'
                     Error = $_.Exception.Message
                     Level = 0
                 }

Tests/Get-GiteaFileContent.Tests.ps1

@@ -21,7 +21,7 @@ Describe 'Get-GiteaFileContent' {
             $result = Get-GiteaFileContent -repoOwner 'user' -repoName 'repo' -filePath 'README.md' -token 'abc123'
 
             $result | Should -Not -BeNullOrEmpty
-            $result.Success | Should -Be $true
+            $result.Result | Should -Be 'Success'
             $result.Content | Should -Be ([System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes('Hello World')))
         }
 
@@ -29,7 +29,7 @@ Describe 'Get-GiteaFileContent' {
             $result = Get-GiteaFileContent -repoOwner 'user' -repoName 'repo' -filePath 'README.md' -token 'abc123' -decode
 
             $result | Should -Not -BeNullOrEmpty
-            $result.Success | Should -Be $true
+            $result.Result | Should -Be 'Success'
             $result.Content | Should -Be 'Hello World'
         }
     }
@@ -73,7 +73,7 @@ Describe 'Get-GiteaFileContent' {
         It 'Should capture error and mark result as unsuccessful' {
             $result = Get-GiteaFileContent -repoOwner 'user' -repoName 'repo' -filePath 'badfile.ps1' -token 'abc123'
     
-            $result.Success | Should -Be $false
+            $result.Result | Should -Be 'Failure'
             $result.Error | Should -Match 'API call failed'
         }
     }
@@ -103,7 +103,7 @@ Describe 'Get-GiteaFileContent' {
             $result = Get-GiteaFileContent -repoOwner 'user' -repoName 'repo' -filePath 'testfile.txt' -token 'abc123'
     
             $result | Should -Not -BeNullOrEmpty
-            $result.Success | Should -Be $true
+            $result.Result | Should -Be 'Success'
             $result.Content | Should -Be ([System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes('Hello from API!')))
         }
     
@@ -111,7 +111,7 @@ Describe 'Get-GiteaFileContent' {
             $result = Get-GiteaFileContent -repoOwner 'user' -repoName 'repo' -filePath 'testfile.txt' -token 'abc123' -decode
     
             $result | Should -Not -BeNullOrEmpty
-            $result.Success | Should -Be $true
+            $result.Result | Should -Be 'Success'
             $result.Content | Should -Be 'Hello from API!'
         }
     }

Tests/Invoke-GiteaFileDownload.Tests.ps1

@@ -49,7 +49,7 @@ Describe 'Invoke-GiteaFileDownload' {
             $result = Invoke-GiteaFileDownload -downloadURL 'https://gitea.example.com/raw/path/to/file.txt' -token 'abc123'
 
             $result | Should -Not -BeNullOrEmpty
-            $result.Success | Should -Be $true
+            $result.Result | Should -Be 'Success'
             $result.Path | Should -Match 'file\.txt$'
         }
     }
@@ -60,7 +60,7 @@ Describe 'Invoke-GiteaFileDownload' {
             -outputPath 'docs/manual/' -token 'abc123'
 
             $result.Path | Should -Match 'docs[\\/]+manual[\\/]+file\.txt$'
-            $result.Success | Should -Be $true
+            $result.Result | Should -Be 'Success'
         }
     }
 
@@ -70,7 +70,7 @@ Describe 'Invoke-GiteaFileDownload' {
             -outputName 'newfile.txt' -token 'abc123'
 
             $result.Path | Should -Match 'newfile\.txt$'
-            $result.Success | Should -Be $true
+            $result.Result | Should -Be 'Success'
         }
     }
 
@@ -80,7 +80,7 @@ Describe 'Invoke-GiteaFileDownload' {
             -outputPath 'docs/manual/' -outputName 'newfile.txt' -token 'abc123'
 
             $result.Path | Should -Match 'docs[\\/]+manual[\\/]+newfile\.txt$'
-            $result.Success | Should -Be $true
+            $result.Result | Should -Be 'Success'
         }
     }
 
@@ -90,7 +90,7 @@ Describe 'Invoke-GiteaFileDownload' {
             -PreserveRelativePath -token 'abc123'
 
             $result.Path | Should -Match 'path[\\/]+to[\\/]+file\.txt$'
-            $result.Success | Should -Be $true
+            $result.Result | Should -Be 'Success'
         }
     }
 
@@ -98,8 +98,7 @@ Describe 'Invoke-GiteaFileDownload' {
         It 'Should skip items with type = dir' {
             $result = Invoke-GiteaFileDownload -outputPath 'docs/' -type 'dir' -token 'abc123'
 
-            $result.Success | Should -Be $true
-            $result.Error | Should -Match 'Skipped'
+            $result.Result | Should -Be 'Skipped'
         }
     }
 
@@ -116,8 +115,7 @@ Describe 'Invoke-GiteaFileDownload' {
         It 'Should not overwrite existing file without Force' {
             $result = Invoke-GiteaFileDownload -downloadURL 'https://gitea.example.com/raw/path/to/existingfile.txt' -token 'abc123'
 
-            $result.Success | Should -Be $false
-            $result.Error | Should -Match 'already exists'
+            $result.Result | Should -Be 'Skipped'
         }
     }
 
@@ -145,7 +143,7 @@ Describe 'Invoke-GiteaFileDownload' {
         It 'Should capture error and mark download as failed' {
             $result = Invoke-GiteaFileDownload -downloadURL 'https://gitea.example.com/raw/path/to/badfile.txt' -token 'abc123'
     
-            $result.Success | Should -Be $false
+            $result.Result | Should -Be 'Failure'
             $result.Error | Should -Match 'Failed to download'
         }
     }