docs(git-provider): Document New-GitRepoRegistration

- output when no name is given
- update message when current location is confirmed to be a git repo

PowershellModule.slnx

@@ -1,20 +1,23 @@
 <Solution>
-  <Folder Name="/build/">
+    <Folder Name="/build/">
-    <Project Path="build/Build.csproj" />
+        <Project Path="build/Build.csproj" />
-  </Folder>
+    </Folder>
-  <Folder Name="/harnesses/">
+    <Folder Name="/docs/">
-    <Project Path="src/ModuleHarness/ModuleHarness.csproj" />
+        <File Path="docs/GitRepositoryRegistration.md" />
-    <Project Path="src/PowershellHarness/PowershellHarness.csproj" />
+    </Folder>
-  </Folder>
+    <Folder Name="/harnesses/">
-  <Folder Name="/scripts/">
+        <Project Path="src/ModuleHarness/ModuleHarness.csproj" />
-    <File Path="build.ps1" />
+        <Project Path="src/PowershellHarness/PowershellHarness.csproj" />
-  </Folder>
+    </Folder>
-  <Folder Name="/solutionItems/">
+    <Folder Name="/scripts/">
-    <File Path="Directory.Packages.props" />
+        <File Path="build.ps1" />
-  </Folder>
+    </Folder>
-  <Folder Name="/tests/">
+    <Folder Name="/solutionItems/">
-    <Project Path="tests/ModuleTests/ModuleTests.csproj" />
+        <File Path="Directory.Packages.props" />
-  </Folder>
+    </Folder>
-  <Project Path="src/ModuleCore/ModuleCore.csproj" />
+    <Folder Name="/tests/">
-  <Project Path="src/PowershellModule/PowershellModule.csproj" />
+        <Project Path="tests/ModuleTests/ModuleTests.csproj" />
+    </Folder>
+    <Project Path="src/ModuleCore/ModuleCore.csproj" />
+    <Project Path="src/PowershellModule/PowershellModule.csproj" />
 </Solution>

docs/GitRepositoryRegistration.md

@@ -0,0 +1,47 @@
+# Git Repo Registration
+
+- all commands support `-debug`
+
+## New-GitRepoRegistration
+
+`New-GitRepoRegistration [-Name string]`
+
+Creates a new registration for the current directory, optionally registering against the given name. If `-Name` is not given the folder for the root level of the git repo will be used.
+
+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.
+
+```pwsh
+# Default registration 
+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 
+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!
+DEBUG: Registered 'D:/Repos/Project-a' to name 'test repo'
+
+PS D:/Repos/Project-a> Get-GitRepoRegistration
+
+Name         Location              CurrentBranch
+----         --------              -------------
+test-repo    D:/Repos/Project-a    main
+Project-a    D:/Repos/Project-a    main
+```
+
+If the current directory is not in a git repo, a registration already exists by name or default folder, or if any other issue occurs such as git not being available an error will be thrown.
+
+## Get-GitRepoRegistration
+
+`Get-GitRepoRegistration`
+
+## Show-GitRepoRegistration
+
+`Show-GitRepoRegistration -Name string [-NoStack|-NoSetLocation]`
+
+## Remove-GitRepoRegistration
+
+`Remove-GitRepoRegistration [-Name string]`

src/ModuleCore/Git/GitManager.cs

@@ -108,6 +108,7 @@ public class GitManager
 
 			if (_registrations.TryAdd(registrationName, gitRegistration))
 			{
+				_debugWriterDelegate?.Invoke($"Registered '{gitRegistration.Location}' to name '{registrationName}'");
 				return registrationName;
 			}
 
@@ -155,6 +156,7 @@ public class GitManager
 			if (_registrations.TryRemove(registrationName, out var removedItem))
 			{
 				_debugWriterDelegate?.Invoke($"Removed {registrationName}.");
+				return;
 			}
 
 			// Weird error to throw, but by this stage we shouldn't have a git repo registered under this name
@@ -195,6 +197,9 @@ public class GitManager
 
 	/// <summary>
 	/// Returns the git root directory for any nested directory if git rev-parse --show-toplevel returns a value.
+	/// <para>
+	/// Will always return a non-null value if the directory is a git repo, otherwise an exception will be thrown
+	/// </para>
 	/// </summary>
 	/// <param name="path">Path to check if it or any of its parents contain a git repository</param>
 	/// <returns></returns>
@@ -235,7 +240,7 @@ public class GitManager
 			// Gotta trim what we get as it might already have a newline character at the end
 			var dirInfo = new DirectoryInfo(directory.Trim());
 
-			_debugWriterDelegate?.Invoke("...location is a git repo (duh).");
+			_debugWriterDelegate?.Invoke("...location is a git repo!");
 
 			var repoFolderInfo = new ParsedGitFolderDetails
 			{

src/PowershellModule/Git/Commands/NewGitRepoRegistrationCommand.cs

@@ -19,8 +19,15 @@ public sealed class NewGitRepoRegistrationCommand : PSCmdlet
 		{
 			GitManager.SetDebugWriter(WriteDebug);
 
+			// Test that we're in a git repo first. If we aren't (or git isn't available), this method will throw
+			// so we don't need to handle for null (yet).
 			var repoFolder = GitManager.IsGitRepo(SessionState.Path.CurrentLocation.Path);
 
+			if (string.IsNullOrWhiteSpace(Name))
+			{
+				WriteDebug("No name given for registration, defaulting to git folder root.");
+			}
+
 			GitManager.Instance.RegisterRepo(repoFolder.Directory, Name ?? repoFolder.Folder);
 			GitManager.ClearDebugWriter();