Dev

README.md

@@ -85,27 +85,49 @@ the particular package.
 
 ## [Upgrading](#table-of-contents)
 
-To upgrade to a new release of the module run:
+### For module versions >= 1.6.1
+
+To upgrade from a previously configured installation to a newer release of the
+module, in an Administrator instance of PowerShell, run:
+
+```pwsh
+Update-WinGetEssentials
+```
+
+### Alternative update method (for module versions < 1.6.1)
+
+If desired, it is also possible to perform a more manual upgrade process using
+`Update-Module` as shown below and performing the additional actions outlined
+in the paragraphs that follow.
 
 ```pwsh
-Upgrade-Module -Name WinGet-Essentials -Repository PSGallery
+Update-Module -Name WinGet-Essentials -Repository PSGallery
 ```
 
 > [!NOTE]\
 > If the `WinGet-Essentials` module is already loaded, restart the terminal or
   reload the module explicitly via `Remove-Module` followed by `Import-Module`.
 
-After the upgrade completes, it is advisable to run the following commands in
-an administrator PowerShell instance to allow new symbolic links to be created.
-Some cmdlets will attempt to perform this automatically, but it will only
-be possible to create a SymLink if the cmdlet is running in an administrator
-PowerShell instance.
+After `Upgrade-Module` completes, it is advisable to run the following commands
+in an administrator PowerShell instance to allow new symbolic links to be
+created. Some cmdlets will attempt to perform this automatically, but it will
+only be possible to create a SymLink if the cmdlet is running in an
+administrator PowerShell instance.
 
 ```pwsh
 Initialize-WinGetIgnore
 Initialize-WinGetRestore
 ```
 
+It may also be desirable to run the following to have other resources/functions
+ready to use (such as tab-completion for package IDs with
+`Update-WinGetSoftware` or use of `Restore-WinGetSoftware`):
+
+```pwsh
+Checkpoint-WinGetSoftware
+Update-WinGetSoftware -Sync
+```
+
 > [!NOTE]\
 > The commands above will find the previous module install to determine where
   the resource files reside. If no such files existed, then it will be necessary
@@ -324,6 +346,27 @@ file is given the default name of `winget.packages.json`):
 ]
 ```
 
+### Fake Packages (EXPERIMENTAL)
+
+> [!NOTE]\
+> Behavior is subject to change in the future.
+
+As a side-effect of adding CI testing, there was a need to create a _fake_
+`PackageIdentifier` as a way to skip potentially length `winget` install requests
+during test execution and to allow more control over how test execution flows
+through the PowerShell logic. A `PackageIdentifier` following the form, `/*/`
+will be detected as _fake_ (where * is a wildcard and represents the
+user-defined name of the _fake_ package):
+
+Because of this, it is possible to specify `winget.packages.json` entries
+that do not point to a software package to install, rather a series of
+commands/scripts via the `PostInstall` functionality. However, one current
+limitation of this feature is there is no guarantee that `-NotInstalled` will
+work correctly for these packages as they exist outside the scope of `winget`.
+
+While it is certainly handy to provide a unified way to download all tools via
+one interface, the current advice is to __use this feature sparingly__.
+
 ### Example PostInstall Entry
 
 Below is an example entry for installing `python` (version 3.11) from `winget`

WinGet-Essentials/WinGet-Essentials.psd1

@@ -1,6 +1,6 @@
 @{
     RootModule = 'WinGet-Essentials.psm1'
-    ModuleVersion = '1.6.1'
+    ModuleVersion = '1.6.2'
     GUID = '2a2b6c24-d6cc-4d59-a456-e7ccd90afd03'
     Author = 'Jon Carrier'
     CompanyName = 'Unknown'

WinGet-Essentials/modules/WinGet-Update.psm1

@@ -211,8 +211,8 @@ function Update-WinGetEssentials
     Write-Output 'Upgrading module from PSGallery ...'
     $current = @(Get-Module WinGet-Essentials -ListAvailable)[0]
     Write-Output "- Current Version: $($current.Version)"
-    Remove-Module WinGet-Essentials
-    Update-Module WinGet-Essentials
+    Remove-Module -Name WinGet-Essentials
+    Update-Module -Name WinGet-Essentials -Repository PSGallery
     $newest = @(Get-Module WinGet-Essentials -ListAvailable)[0]
     Write-Output "- Updated Version: $($newest.Version)"
 
@@ -501,17 +501,26 @@ function Update-WinGetSoftware
         $UPDATE_NOT_APPLICABLE = 0x8A15002B
 
         Write-Output "Updating '$($Item.Id)' ..."
-        winget $(Get-WinGetSoftwareUpgradeArgs -Item $Item -Interactive:$Interactive)
+        $commandArgs = Get-WinGetSoftwareUpgradeArgs -Item $Item -Interactive:$Interactive
+        winget $commandArgs
 
         $upgradeOk = $LASTEXITCODE -eq 0
 
         if (-not($upgradeOk) -and ($LASTEXITCODE -eq $UPDATE_NOT_APPLICABLE)) {
-            # This is a workaround for an issue currently present in winget where
-            # the listing reports an update, but it is not possible to 'upgrade'.
-            # Instead, use the 'install' command. This issue might be caused by
-            # different install wizard on the local system versus what is
-            # present on the winget source.
+            # This is a best-effort workaround for an issue currently present in
+            # winget where the listing reports an update, but it is not possible
+            # to 'upgrade'. Instead, use the 'install' command. This is
+            # typically due to a different installer used for the current
+            # installation versus what is available on the winget source. In
+            # this case, try with --uninstall-previous, but support for this is
+            # not guaranteed. If this fails, the user likely needs to
+            # "winget uninstall" and then "winget install". This could
+            # potentially be handled here, but there may be issues with ensuring
+            # the install state is maintained. For now it is best to force the
+            # user to upgrade this package manually.
             $commandArgs[0] = 'install'
+            $commandArgs += '--uninstall-previous'
+            Write-Verbose "command: winget $commandArgs"
             winget $commandArgs
         }