Merge pull request #9 from KubaP/development

Release v0.1.4

README.md

@@ -100,7 +100,7 @@ The following cmdlets support `-WhatIf` and `-Confirm` parameters:
 - `Set-Symlink`
 - `Build-Symlink`
 
-Use `-WhatIf` to see a list of what changes a command will do.
+Use `-WhatIf` to see a list of what changes a cmdlet will do.
 
 Use `-Confirm` to ask for a prompt for every state-altering change.
 

Symlink/Symlink.psd1

@@ -3,7 +3,7 @@
 	RootModule = 'Symlink.psm1'
 
 	# Version number of this module.
-	ModuleVersion = '0.1.3'
+	ModuleVersion = '0.1.4'
 
 	# ID used to uniquely identify this module
 	GUID = '7849ff1f-d264-4a49-8de2-9c01e79a22a9'

Symlink/Symlink.psm1

@@ -3,8 +3,7 @@ $script:ModuleRoot = $PSScriptRoot
 $script:ModuleVersion = (Import-PowerShellDataFile -Path "$ModuleRoot\Symlink.psd1").ModuleVersion
 $script:DataPath = "$env:APPDATA\Powershell\Symlink\database.xml"
 
-# For the debug output to be displayed, $DebugPreference must be set
-# to 'Continue' within the current session.
+# For the debug output to be displayed, $DebugPreference must be set to 'Continue' within the current session.
 Write-Debug "`e[4mMODULE-WIDE VARIABLES`e[0m"
 Write-Debug "Module root folder: $ModuleRoot"
 Write-Debug "Module version: $ModuleVersion"
@@ -17,8 +16,7 @@ if (-not (Test-Path -Path "$env:APPDATA\Powershell\Symlink" -ErrorAction Ignore)
 	Write-Debug "Created database folder!"
 }
 
-# Potentially force this module script to dot-source the files, rather than 
-# load them in an alternative method.
+# Potentially force this module script to dot-source the files, rather than load them in an alternative method.
 $doDotSource = $global:ModuleDebugDotSource
 $doDotSource = $true # Needed to make code coverage tests work
 
@@ -131,8 +129,8 @@ function Import-ModuleFile
 # the individual files can be imported, as they don't exist.
 
 
-# If this module file contains the compiled code, import that, but if it
-# doesn't, then import the individual files instead.
+# If this module file contains the compiled code, import that, but if it doesn't, then import the
+# individual files instead.
 $importIndividualFiles = $false
 if ("<was not built>" -eq '<was not built>')
 {

Symlink/changelog.md

@@ -1,4 +1,7 @@
 # Changelog
+## 0.1.4 (2021-02-27)
+ - Update: Format.ps1xml: Improve formatting styles to present information and the state of the symbolic-links in a clearer manner.
+ - Fix: `New-Symlink`: Incorrectly throwing an error when using the *'-MoveExistingItem'* switch and when no renaming is necessary as the existing and desired item names are identical.
 ## 0.1.3 (2020-12-30)
  - Add: *'-Force'* for `New-Symlink`: Forces the creation of the symbolic-link even if the creation condition evaluates to false, and overwrites any existing symlink if the names collide.
  - Add: *'-Force'* for `Build-Symlink`: Forces the creation of the symbolic-link even if the creation condition evaluates to false.

Symlink/functions/Build-Symlink.ps1

@@ -120,8 +120,8 @@ function Build-Symlink
 	{
 		foreach ($link in $linkList)
 		{
-			# Check if the symlink should be created, but it has an invalid
-			# target, as in such a case it must be skipped.
+			# Check if the symlink should be created, but it has an invalid target,
+			# as in such a case it must be skipped.
 			if (($link.ShouldExist() -or $Force) -and ($link.TargetState() -ne "Valid"))
 			{
 				Write-Error "The symlink named '$($link.Name)' has a target which is invalid/non-existent!`nAborting creation of this symlink."
@@ -132,21 +132,18 @@ function Build-Symlink
 			$expandedPath = $link.FullPath()
 			if (($link.ShouldExist() -or $Force) -and ($link.TargetState() -eq "Valid") -and $PSCmdlet.ShouldProcess("Creating symbolic-link item at '$expandedPath'.", "Are you sure you want to create the symbolic-link item at '$expandedPath'?", "Create Symbolic-Link Prompt"))
 			{
-				# Appropriately delete any existing items before creating the
-				# symbolic-link.
+				# Appropriately delete any existing items before creating the symbolic-link.
 				$item = Get-Item -Path $expandedPath -ErrorAction Ignore
-				# Existing item may be in use and unable to be deleted, so retry until
-				# the user has closed any programs using the item.
+				# Existing item may be in use and unable to be deleted, so retry until the user has closed
+				# any programs using the item.
 				while (Test-Path -Path $expandedPath)
 				{
 					try
 					{
-						# Calling `Remove-Item` on a symbolic-link will delete the
-						# original items the link points to; calling Delete() will
-						# only destroy the symbolic-link iteself, whilst calling
-						# Delete() on a folder will not delete it's contents. Therefore
-						# check whether the item is a symbolic-link to call the
-						# appropriate method.
+						# Calling 'Remove-Item' on a symbolic-link will delete the original items the link points
+						# to; calling 'Delete()' will only destroy the symbolic-link iteself,
+						# whilst calling 'Delete()' on a folder will not delete it's contents. Therefore check
+						# whether the item is a symbolic-link to call the appropriate method.
 						if ($null -eq $item.LinkType)
 						{
 							Remove-Item -Path $expandedPath -Force -Recurse -ErrorAction Stop -WhatIf:$false `

Symlink/functions/New-Symlink.ps1

@@ -155,9 +155,8 @@ function New-Symlink
 	$expandedPath = [System.Environment]::ExpandEnvironmentVariables($Path)
 	$expandedTarget = [System.Environment]::ExpandEnvironmentVariables($Target)
 
-	# Validate that the target location exists. If the item isn't being moved
-	# there, check the full path, otherwise check that the parent folder
-	# is valid.
+	# Validate that the target location exists. If the item isn't being moved there, check the full path,
+	# otherwise check that the parent folder is valid.
 	if (-not (Test-Path -Path $expandedTarget -ErrorAction Ignore) -and -not $MoveExistingItem)
 	{
 		Write-Error "The target path: '$Target' points to an invalid/non-existent location!"
@@ -189,13 +188,12 @@ function New-Symlink
 
 	if ((Test-Path -Path $expandedPath -ErrorAction Ignore) -and $MoveExistingItem -and $PSCmdlet.ShouldProcess("Moving and renaming existing item from '$expandedPath' to '$expandedTarget'.", "Are you sure you want to move and rename the existing item from '$expandedPath' to '$expandedTarget'?", "Move File Prompt")) 
 	{
-		# Move the item over to the target parent folder, and rename it
-		# to the specified name name given in the target path.
+		# Move the item over to the target parent folder, and rename it to the specified name given as part
+		# of the target path.
 		$fileName = Split-Path -Path $expandedPath -Leaf
 		$newFileName = Split-Path -Path $expandedTarget -Leaf
 		$targetFolder = Split-Path -Path $expandedTarget -Parent
-		# Prevent error logging in `Move-Item` cmdlet due to same 
-		# origin/destination.
+		# Only troy to move the item if the parent folders differ, otherwise 'Move-Item' will thrown an error.
 		if ((Split-Path -Path $expandedPath -Parent) -ne $targetFolder)
 		{
 			try
@@ -210,15 +208,19 @@ function New-Symlink
 			}
 		}
 
-		try
+		# Only try to rename the item if the name differs, otherwise 'Rename-Item' will throw an error.
+		if ($fileName -ne $newFileName)
 		{
-			Rename-Item -Path "$targetFolder\$filename" -NewName $newFileName -Force -ErrorAction Stop `
-				-WhatIf:$false -Confirm:$false | Out-Null
-		}
-		catch
-		{
-			Write-Error "Could not rename the existing item to match the target path.`nClose any programs which may be using this path and re-run the cmdlet."
-			return
+			try
+			{
+				Rename-Item -Path "$targetFolder\$filename" -NewName $newFileName -Force -ErrorAction Stop `
+					-WhatIf:$false -Confirm:$false | Out-Null
+			}
+			catch
+			{
+				Write-Error "Could not rename the existing item to match the target path.`nClose any programs which may be using this path and re-run the cmdlet."
+				return
+			}
 		}
 	}
 	elseif (-not (Test-Path -Path $expandedPath -ErrorAction Ignore) -and $MoveExistingItem)
@@ -247,21 +249,18 @@ function New-Symlink
 	# Build the symbolic-link item on the filesytem.
 	if (-not $DontCreateItem -and ($newLink.TargetState() -eq "Valid") -and ($newLink.ShouldExist() -or $Force) -and $PSCmdlet.ShouldProcess("Creating symbolic-link item at '$expandedPath'.", "Are you sure you want to create the symbolic-link item at '$expandedPath'?", "Create Symbolic-Link Prompt"))
 	{
-		# Appropriately delete any existing items before creating the
-		# symbolic-link.
+		# Appropriately delete any existing items before creating the symbolic-link.
 		$item = Get-Item -Path $expandedPath -ErrorAction Ignore
-		# Existing item may be in use and unable to be deleted, so retry until
-		# the user has closed any programs using the item.
+		# Existing item may be in use and unable to be deleted, so retry until the user has closed any
+		# programs using the item.
 		while (Test-Path -Path $expandedPath)
 		{
 			try
 			{
-				# Calling `Remove-Item` on a symbolic-link will delete the
-				# original items the link points to; calling Delete() will
-				# only destroy the symbolic-link iteself, whilst calling
-				# Delete() on a folder will not delete it's contents. Therefore
-				# check whether the item is a symbolic-link to call the
-				# appropriate method.
+				# Calling 'Remove-Item' on a symbolic-link will delete the original items the link points
+				# to; calling 'Delete()' will only destroy the symbolic-link iteself,
+				# whilst calling 'Delete()' on a folder will not delete it's contents. Therefore check whether the
+				# item is a symbolic-link to call the appropriate method.
 				if ($null -eq $item.LinkType)
 				{
 					Remove-Item -Path $expandedPath -Force -Recurse -ErrorAction Stop -WhatIf:$false `

Symlink/functions/Remove-Symlink.ps1

@@ -98,15 +98,14 @@ function Remove-Symlink
 			$item = Get-Item -Path $expandedPath -ErrorAction Ignore
 			if (-not $DontDeleteItem -and $existingLink.Exists() -and $PSCmdlet.ShouldProcess("Deleting symbolic-link at '$expandedPath'.", "Are you sure you want to delete the symbolic-link at '$expandedPath'?", "Delete Symbolic-Link Prompt"))
 			{
-				# Existing item may be in use and unable to be deleted, so retry until
-				# the user has closed any programs using the item.
+				# Existing item may be in use and unable to be deleted, so retry until the user has closed
+				# any programs using the item.
 				while (Test-Path -Path $expandedPath)
 				{
 					try
 					{
-						# Calling `Remove-Item` on a symbolic-link will delete
-						# the original items the link points to; calling
-						# Delete() will only destroy the symbolic-link iteself.
+						# Calling 'Remove-Item' on a symbolic-link will delete the original items the link points
+						# to; calling 'Delete()' will only destroy the symbolic-link iteself.
 						$item.Delete()
 					}
 					catch

Symlink/functions/Set-Symlink.ps1

@@ -172,21 +172,19 @@ function Set-Symlink
 				return
 			}
 
-			# Firstly, delete the symlink from the filesystem at the original
-			# path location.
+			# Firstly, delete the symlink from the filesystem at the original path location.
 			$expandedPath = $existingLink.FullPath()
 			$item = Get-Item -Path $expandedPath -ErrorAction Ignore
 			if ($existingLink.Exists() -and $PSCmdlet.ShouldProcess("Deleting old symbolic-link at '$expandedPath'.", "Are you sure you want to delete the old symbolic-link at '$expandedPath'?", "Delete Symbolic-Link Prompt"))
 			{
-				# Existing item may be in use and unable to be deleted, so retry until
-				# the user has closed any programs using the item.
+				# Existing item may be in use and unable to be deleted, so retry until the user has closed
+				# any programs using the item.
 				while (Test-Path -Path $expandedPath)
 				{
 					try
 					{
-						# Calling `Remove-Item` on a symbolic-link will delete
-						# the original items the link points to; calling
-						# Delete() will only destroy the symbolic-link iteself.
+						# Calling 'Remove-Item' on a symbolic-link will delete the original items the link points
+						# to; calling 'Delete()' will only destroy the symbolic-link iteself.
 						$item.Delete()
 					}
 					catch
@@ -197,28 +195,24 @@ function Set-Symlink
 				}
 			}
 
-			# Then change the path property, and re-create the symlink at the
-			# new location, taking into account that there may be existing
-			# items at the new path.
+			# Then change the path property, and re-create the symlink at the new location, taking into account
+			# that there may be existing items at the new path.
 			$existingLink._Path = $Value
 			$expandedPath = $existingLink.FullPath()
 			if (($existingLink.ShouldExist() -or $Force) -and ($existingLink.TargetState() -eq "Valid") -and $PSCmdlet.ShouldProcess("Creating new symbolic-link item at '$expandedPath'.", "Are you sure you want to create the new symbolic-link item at '$expandedPath'?", "Create Symbolic-Link Prompt"))
 			{
-				# Appropriately delete any existing items before creating the
-				# symbolic-link.
+				# Appropriately delete any existing items before creating the symbolic-link.
 				$item = Get-Item -Path $expandedPath -ErrorAction Ignore
-				# Existing item may be in use and unable to be deleted, so retry until
-				# the user has closed any programs using the item.
+				# Existing item may be in use and unable to be deleted, so retry until the user has closed
+				# any programs using the item.
 				while (Test-Path -Path $expandedPath)
 				{
 					try
 					{
-						# Calling `Remove-Item` on a symbolic-link will delete the
-						# original items the link points to; calling Delete() will
-						# only destroy the symbolic-link iteself, whilst calling
-						# Delete() on a folder will not delete it's contents. Therefore
-						# check whether the item is a symbolic-link to call the
-						# appropriate method.
+						# Calling 'Remove-Item' on a symbolic-link will delete the original items the link points
+						# to; calling 'Delete()' will only destroy the symbolic-link iteself,
+						# whilst calling 'Delete()' on a folder will not delete it's contents. Therefore check
+						# whether the item is a symbolic-link to call the appropriate method.
 						if ($null -eq $item.LinkType)
 						{
 							Remove-Item -Path $expandedPath -Force -Recurse -ErrorAction Stop -WhatIf:$false `
@@ -250,21 +244,19 @@ function Set-Symlink
 				return
 			}
 
-			# Firstly, delete the symlink with the old target value from
-			# the filesystem.
+			# Firstly, delete the symlink with the old target value from the filesystem.
 			$expandedPath = $existingLink.FullPath()
 			$item = Get-Item -Path $expandedPath -ErrorAction Ignore
 			if ($existingLink.Exists() -and $PSCmdlet.ShouldProcess("Deleting outdated symbolic-link at '$expandedPath'.", "Are you sure you want to delete the outdated symbolic-link at '$expandedPath'?", "Delete Symbolic-Link Prompt"))
 			{
-				# Existing item may be in use and unable to be deleted, so retry until
-				# the user has closed any programs using the item.
+				# Existing item may be in use and unable to be deleted, so retry until the user has closed
+				# any programs using the item.
 				while (Test-Path -Path $expandedPath)
 				{
 					try
 					{
-						# Calling `Remove-Item` on a symbolic-link will delete
-						# the original items the link points to; calling
-						# Delete() will only destroy the symbolic-link iteself.
+						# Calling 'Remove-Item' on a symbolic-link will delete the original items the link points
+						# to; calling 'Delete()' will only destroy the symbolic-link iteself.
 						$item.Delete()
 					}
 					catch
@@ -275,28 +267,24 @@ function Set-Symlink
 				}
 			}
 
-			# Then change the target property, and re-create the symlink at the
-			# with the new target, taking into account that there may be
-			# existing items at the new path.
+			# Then change the target property, and re-create the symlink at the with the new target,
+			# taking into account that there may be existing items at the new path.
 			$existingLink._Target = $Value
 			$expandedPath = $existingLink.FullPath()
 			if (($existingLink.ShouldExist() -or $Force) -and ($existingLink.TargetState() -eq "Valid") -and $PSCmdlet.ShouldProcess("Creating new symbolic-link item at '$expandedPath'.", "Are you sure you want to create the new symbolic-link item at '$expandedPath'?", "Create Symbolic-Link Prompt"))
 			{
-				# Appropriately delete any existing items before creating the
-				# symbolic-link.
+				# Appropriately delete any existing items before creating the symbolic-link.
 				$item = Get-Item -Path $expandedPath -ErrorAction Ignore
-				# Existing item may be in use and unable to be deleted, so retry until
-				# the user has closed any programs using the item.
+				# Existing item may be in use and unable to be deleted, so retry until the user has closed
+				# any programs using the item.
 				while (Test-Path -Path $expandedPath)
 				{
 					try
 					{
-						# Calling `Remove-Item` on a symbolic-link will delete the
-						# original items the link points to; calling Delete() will
-						# only destroy the symbolic-link iteself, whilst calling
-						# Delete() on a folder will not delete it's contents. Therefore
-						# check whether the item is a symbolic-link to call the
-						# appropriate method.
+						# Calling 'Remove-Item' on a symbolic-link will delete the original items the link points
+						# to; calling 'Delete()' will only destroy the symbolic-link iteself,
+						# whilst calling 'Delete()' on a folder will not delete it's contents. Therefore check
+						# whether the item is a symbolic-link to call the appropriate method.
 						if ($null -eq $item.LinkType)
 						{
 							Remove-Item -Path $expandedPath -Force -Recurse -ErrorAction Stop -WhatIf:$false `