docs(git-provider): Small documentation updates to verb usage and default behaviour for New-GitRepoRegistration

docs/GitRepositoryRegistration.md

@@ -1,6 +1,11 @@
 # Git Repo Registration
 
 - all commands support `-debug`
+- at its simplest level these commands allow you to register a git repo against a simple name, and provide the ability to quickly pushd to a location
+
+Most `*-GitRepoRegistration` commands are expected to be run within a folder that is contained within a git repo. The only exceptions to this are any verbs that list information or change locations such as `Get-`, `Show-`, `Push-`, `Pop-`.
+
+Any exceptions to behaviours are outlined within the relevant command section
 
 ## New-GitRepoRegistration
 
@@ -10,15 +15,17 @@ Creates a new registration for the current directory, optionally registering aga
 
 Name registrations are _not_ case-sensitive, so registrations can be made using different cases for the same location, and multiple registrations can exist for the git repository.
 
+If `New-GitRepoRegistration` is used in 2 repositories with the same name but different locations, the 2nd call will fail as a registration will already exist by name.
+
 ```pwsh
-# Default registration 
+# Default registration without a name within a folder in a git repo
 PS D:/Repos/Project-a> New-GitRepoRegistration -debug
 DEBUG: Checking if current directory is a git repository...
 DEBUG: ...location is a git repo!
 DEBUG: No name given for registration, defaulting to git folder root.
 DEBUG: Registered 'D:/Repos/Project-a' to name 'Project-a'
 
-# Named registration 
+# Named registration
 PS D:/Repos/Project-a> New-GitRepoRegistration "test repo" -debug
 DEBUG: Checking if current directory is a git repository...
 DEBUG: ...location is a git repo!
@@ -55,10 +62,67 @@ The current branch is cached for 15 minutes for performance reasons so it may no
 
 `Show-GitRepoRegistration -Name string [-NoStack|-NoPushLocation]`
 
-Changes your location to the location of the git repo registered by the given `-Name`. If used without `-NoStack` or its alias `-NoPushLocation`, your original location will be preserved and can be returned to at any time via `Pop-Location`/`Popd`.
+Changes your location to the location of the git repo registered by the given `-Name` and your original location will be preserved and can be returned to at any time via `Pop-Location`/`Popd`. By default, this command is identical to calling
+`pushd [repository directory]`.
 
-Using `-NoStack`/`-NoPushLocation` will not push your current location onto the stack, and will behave the same as `cd`/`Set-Location`.
+Using `-NoStack`/`-NoPushLocation` will not push your current location onto the stack, and will behave the same as `cd [repository directory]`/`Set-Location [repository directory]`.
+
+```pwsh
+PS C:/> Show-GitRepoRegistration Project-a
+PS D:/Repos/Project-a> Get-Location -stack
+
+Path
+----
+C:\
+
+PS D:/Repos/Project-a> cd ./build
+PS D:/Repos/Project-a/Build> Get-Location -stack
+
+Path
+----
+C:\
+
+PS D:/Repos/Project-a/Build> popd
+PS C:/>
+```
 
 ## Remove-GitRepoRegistration
 
-`Remove-GitRepoRegistration [-Name string]`
+`Remove-GitRepoRegistration [-Name string]`
+
+Removes a repo registration by the given name, or if no name is specified, attempts to remove the git repo registered by resolving the git repo.
+
+If `Name` is not provided then the command must be run in a location that is a git repo and the registration to remove will use the parent git repo folder name. If `Name` _is_ provided this command can be executed from any location.
+
+```pwsh
+# Default registration without a name within a folder in a git repo
+PS D:/Repos/Project-a> New-GitRepoRegistration
+
+# List registrations
+PS D:/Repos/Project-a> Get-GitRepoRegistration
+
+Name         Location              CurrentBranch
+----         --------              -------------
+Project-a    D:/Repos/Project-a    main
+Test-Repo    D:/Repos/Project-a    main
+
+# Remove a registration from within a git repo
+PS D:/Repos/Project-a> Remove-GitRepoRegistration
+# No output indicates successful removal
+
+PS D:/Repos/Project-a> Get-GitRepoRegistration
+
+Name         Location              CurrentBranch
+----         --------              -------------
+Test-Repo    D:/Repos/Project-a    main
+
+# Duplicate calls error if there is no registration
+PS D:/Repos/Project-a> Remove-GitRepoRegistration
+Remove-GitRepoRegistration: No registration exists for 'Project-a'.
+
+# Debug output via named argument
+PS D:/Repos/Project-a> Remove-GitRepoRegistration -name Test-Repo -debug
+DEBUG: Checking if current directory is a git repository...
+DEBUG: ...location is a git repo!
+DEBUG: Removed Test-Repo.
+```

src/PowershellModule/Git/Commands/RemoveGitRepoRegistrationCommand.cs

@@ -19,11 +19,18 @@ public class RemoveGitRepoRegistrationCommand : PSCmdlet
 		{
 			GitManager.SetDebugWriter(WriteDebug);
 
-			var repoFolder = GitManager.IsGitRepo(SessionState.Path.CurrentLocation.Path);
+			// If we aren't given a value for the Name argument, default behaviour is to attempt to remove a registration
+			// by the current git repo folder name for the current location.
+			// If we have a name, don't bother testing for a git repo, just attempt to remove the registration by name
+			// regardless of where we're being called from
+			var registrationNameToRemove = string.IsNullOrEmpty(Name)
+				? GitManager.IsGitRepo(SessionState.Path.CurrentLocation.Path).Folder
+				: Name;
+
+			GitManager.Instance.UnregisterRepo(registrationNameToRemove);
 
 			// Removing a registration works similar to registering a new one - we either remove by exact name, or by
 			// the folder if no name is given (so a user can remove a registration from a git repo they're currently in)
-			GitManager.Instance.UnregisterRepo(Name ?? repoFolder.Folder);
 			GitManager.ClearDebugWriter();
 
 			base.BeginProcessing();